# Install button
A button for web pages and READMEs that opens a game straight in FramePort. Clicking it hands FramePort an install
link; FramePort shows what it would download and asks before it does anything (see
[Install links](INSTALL.md#install-links-install-with-frameport-buttons)).
## Files
All files are in [`docs/badges/`](badges/). Each SVG is self-contained (no external fonts or images), 216 × 60.
| File | Use it for |
|---|---|
| [`install-with-frameport.svg`](badges/install-with-frameport.svg) | Everywhere. No motion. |
| [`install-with-frameport-animated.svg`](badges/install-with-frameport-animated.svg) | GitHub READMEs and other pages that only allow images. The glow plays by itself every 6 seconds. |
| [`install-with-frameport-hover.svg`](badges/install-with-frameport-hover.svg) | Websites where you can paste HTML. It glows while the pointer is on it, but only when its SVG code is in the page itself (see below). |
| [`install-with-frameport@2x.png`](badges/install-with-frameport@2x.png) | Places without SVG support (some forums, email). 432 × 120; show it at 216 × 60. |
Both animated versions stop moving for visitors who turn on reduced motion in their system settings.
## The link
The button links to FramePort's install page, which names either a manifest or one file:
```
https://frameport.app/install?manifest=
https://frameport.app/install?url=
```
The page shows what the link installs, opens FramePort with the matching `frameport://` link and, when FramePort
isn't installed, offers the download. Pages that only target people who already have FramePort can link to the
`frameport://` form directly:
```
frameport://install?manifest=
frameport://install?url=
```
The manifest:
```json
{
"schema": "framedrop.install/v1",
"name": "My Game",
"version": "1.4.2",
"files": [{ "url": "https://example.com/my-game.apk", "sha256": "<64 hex digits>" }],
"frameport": { "description": "One sentence about the game.", "icon": "https://example.com/icon.png" }
}
```
`name` becomes the game's title in Steam. `sha256` is optional but recommended: FramePort checks the download
against it. The `frameport` object is optional; its icon and description are shown in the
install question. Only public `https://` addresses are accepted.
`version` is optional (it can also go inside the `frameport` object) and makes updates possible: FramePort remembers
the manifest's address and version, fetches the manifest again at start (at most every 6 hours) and, when its
`version` is newer, offers to download and install the update (Library bar and the game's page; CLI
`frameport link-updates [--install]`). Keep the manifest at the same address and raise `version` with every build.
Versions compare number by number (`1.10` > `1.9`), and a suffix sorts before the plain release (`1.2.0-beta2` <
`1.2.0`). Bare file links (`?url=…`) and manifests without a version are never checked.
To build a link from Python: `frameport.deeplink.make_link(manifest_url="https://…/my-game.json")`.
**Where to host the manifest.** The install page shows the manifest's name, description and icon only when the
manifest's host lets web pages read it (CORS); otherwise it shows "A game or app" (FramePort itself reads any public
address). On GitHub, commit the manifest to the repository and link it as a file: `https://raw.githubusercontent.com/
//main/my-game.json`, or the `https://github.com///blob/main/my-game.json` page address,
which the page and FramePort turn into the raw address. A manifest attached to a GitHub release
(`…/releases/download/…`) installs fine, but web pages can't read it: the page then shows the release's name from
GitHub's API instead.
## On a website
Image version (any page):
```html
```
Hover version: paste the contents of `install-with-frameport-hover.svg` inside the link instead of the ``, and
give the link an accessible name:
```html
```
Host the files yourself, or load them from jsDelivr, which serves them with the right content type:
`https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport.svg` (replace `main`
with a release tag such as `v1.0.0` to pin a version; jsDelivr caches `@main` for up to 12 hours).
## In a GitHub README
GitHub removes links that don't start with `https://` or `http://` from READMEs, so a `frameport://` link there is
not clickable. Use the `https://frameport.app/install?…` link:
```markdown
[](https://frameport.app/install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json)
```
Use the animated or still SVG: GitHub shows SVGs as images, so the hover version doesn't react there.
## Testing your setup
The example button on [frameport.app](https://frameport.app/#button) uses a demo link:
```
https://frameport.app/install/?manifest=https%3A%2F%2Fframeport.app%2Fdemo%2Fcool-game.json
```
Click it to check that FramePort receives install links on your PC. FramePort recognises this one address and shows
a demo install question for a placeholder game, "Cool Game"; nothing is downloaded, added to the library or
installed (`frameport open-link` says it's the demo link and stops). Real buttons install real games.
## If a visitor doesn't have FramePort
The `https://frameport.app/install?…` link handles this: its page offers the download and a second try. A bare
`frameport://` link does nothing visible (or shows the browser's "no app for this link" message) when FramePort
isn't installed; put a line next to such a button, for example "Needs [FramePort](https://frameport.app)". On macOS, web pages can't hand links to FramePort yet: users paste the link into Add games →
Add from a link….
## Usage rules
- Keep the alt text "Install with FramePort".
- Don't recolor, stretch, crop or redraw the button, and don't show it smaller than 40 px tall.
- Leave some space around it (at least 8 px) so it doesn't touch other buttons.
- It works on light and dark pages as it is; there is no light version.
```
Hover version: paste the contents of `install-with-frameport-hover.svg` inside the link instead of the `