Ship your mascot in an app

An app key lets an app without a backend, such as a desktop or mobile app, play your mascot. You put the key inside the app. It belongs to one mascot and can only read that mascot's released canvases, so it never exposes your account: someone who digs it out of the app gets what the app already has.

How it works#

1. Release the canvas with Update on the canvas page. An app key never sees drafts.
2. Create an app key for the mascot, in Get Links → App keys or with the API. The key is shown once.
3. Ship the key and the canvas ID in your app.
4. The app asks for the canvas's latest release, downloads its files, keeps them and plays them with the Masko player. On iPhone, iPad and Mac, the player does all of this from the canvas's URL and the key.
5. Release again whenever you like: the app gets the new release the next time it asks, for example every hour. No new app version is needed.

Play it with the Masko player#

On iPhone, iPad and Mac (Masko player 0.1.12 and later), give the player the canvas's URL and the app key:

import MaskoPlayer

let player = MaskoPlayer(
  url: URL(string: "https://api.masko.ai/v1/canvases/CANVAS_ID/delivery")!,
  appKey: "masko_app_YOUR_APP_KEY")
MaskoView(player: player)  // or MaskoPlayerView(player: player)
player.set("pointerHover", true)

The player asks for the latest release, downloads every file once and keeps it, so the mascot plays offline. It asks again at launch and every hour. A new release is used once all its files are downloaded, and it takes over when the mascot's first pose starts its loop again, so nothing jumps; the values your app set carry over. The files live in the app's Application Support folder, left out of backups. Before the first release has arrived, the values you set choose the first pose and fire calls are dropped.

The rest of this page is what the player does for you, for other platforms or your own code.

What an app key can read#

The app sees exactly what the canvas plays. For other files of the mascot, such as stickers or images that no canvas uses, use hosting or your own backend with your API key.

Create an app key#

In Studio, open the mascot, click Get Links and open the App keys tab: name the key after the app (for example "My app for Mac"), create it and copy it. Or call the API with your API key:

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/app-keys \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My app for Mac"}'

key appears only in this response: Masko keeps a hash, never the key. A mascot can have 20 active app keys; make one per app so you can revoke them separately.

Read the latest release#

The app sends its app key as a bearer token. Ask for your platform with target (apple for iPhone, iPad and Mac, android, web) and add formats=av1 for the lighter AV1 files the Masko player plays in apps. Masko-Install-Id is optional: a random UUID the installed copy keeps, so you can see how many copies are active. Nothing else about the device is recorded.

curl "https://api.masko.ai/v1/canvases/CANVAS_ID/delivery?target=apple&formats=av1" \
  -H "Authorization: Bearer masko_app_YOUR_APP_KEY" \
  -H "Masko-Install-Id: 6f0c0e5a-1f0b-4a57-9d0a-2b7c5c1d9e11"

GET /v1/canvases/{canvasId}/releases/{releaseId}/delivery returns one release in the same shape, to pin an app to it.

What a release holds#

The delivery describes everything the mascot can do in the app:

• Poses are runtimeGraph.nodes. Each has an id, a name and transparentThumbnailUrl, its still picture with a transparent background. initialNode is the pose it starts on.
• Animations are runtimeGraph.edges. An edge from one pose to another is a move. An edge whose source and target are the same pose plays on that pose: the first one without conditions is the pose's loop, and the others play when their conditions hold, or now and then. videos holds the file for your target (av1, hevc, webm or stacked), duration its length in seconds. Edges with source: "*" have no file: they choose the pose to go to when an input is on.
• Inputs are runtimeGraph.inputs: the names your app sends with set or fire, such as behavior::pointerHover while the pointer is over the mascot, or your own action::snack. conditions on each edge say which input plays it.
• Capabilities, when the canvas has them, are runtimeGraph.capabilities: each behavior and action with a short name and description of what the mascot does, to show in your app's settings.

So an app lists its mascot's poses and animations from nodes and edges, and the Masko player runs the rules for it: your app only says what is happening. Canvas graphs explains every field.

Keep the files#

The file links are signed and stop working after one to two days (deliveryAccess.signedUrlExpiresAt), so download the files when the delivery arrives and keep them:

1. Name each file after its link's path, without the query: the path never changes, only the signature does.
2. Download only the files you do not have yet.
3. Rewrite the links in the delivery to your local file:// URLs, leave out deliveryAccess, and give that delivery to the player.
4. Ask again later, for example at launch and every hour. The same release_id means nothing changed; a new one means a new release to download. Switch to it once every file is there.

Offline, the app keeps playing what it has. Ship the first pose's loop inside the app so the mascot appears before the first download.

See and revoke keys#

GET /v1/mascots/MASCOT_ID/app-keys lists the active keys with their last_used_at and installs_7d, the installed copies that asked in the last 7 days. The App keys tab shows the same. Revoking a key stops it at once: apps that carry it keep what they downloaded and stop receiving new releases. Ship a new app version with a new key to bring them back.

curl -X DELETE https://api.masko.ai/v1/mascots/MASCOT_ID/app-keys/APP_KEY_ID \
  -H "Authorization: Bearer masko_YOUR_API_KEY"