Put a mascot in a website or app
This guide is for an AI agent working with Masko's MCP tools; read_docs reads the other guides and docs pages it names. It covers showing finished pictures, animations and canvas releases in the user's website or app. Use what already exists: find it with list_assets, get_job or get_release_delivery, and never make a character again only to put it in an app.
Always the Masko player
Show every Masko animation with the Masko player, even a single loop: never a video tag, motion added to a still picture or playback code of your own, unless the user asks for another way. The player is open source (https://github.com/masko-ai/masko-player). It picks the file each platform shows with transparency and loops it cleanly. Never install or recommend @masko/sdk to play a mascot.
- One animation that never changes plays from its permanent links.
- A mascot that reacts to the app, or switches between animations, is a canvas release. Without one yet, read
ai-agents/build-interactive-mascot.
Permanent links
Links outside assets.masko.ai are private and stop working within hours: show them to the user, but never put them in code, an app or a website.
For pictures and single animations, offer publish_mascot_assets. Once the user agrees, every finished file of the mascot gets a permanent public link on assets.masko.ai, and files made afterwards get one too. Say what becomes public first. Its unpublish takes them offline again, which breaks those links in live websites and apps: use it only when the user asks. get_mascot's hosting says whether a mascot is public already.
Which file
- A pose:
transparent_imageis the picture to show (imagekeeps its plain background). - An animation on the web:
webmwithhevc. - An animation in an app:
stacked_video_av1, the lighter file (stacked_videobefore Android 10), orhevcon Apple. videois an MP4 with a solid background, for previews only: never call it transparent.export_assetmakes a format that is not listed, such as GIF, animated WebP, Lottie or a chat sticker. Wait for its job.
One animation
- Web and Electron:
npm install @masko/player, then<MaskoPlayer clip={{ webm, hevc }} />from@masko/player/react, ormountMascot(element, { clip: { webm, hevc } })from@masko/player. - iPhone, iPad and Mac: Swift package
https://github.com/masko-ai/masko-player, thenMaskoView(player: MaskoPlayer(clip: url))withstacked_video_av1orhevc. - Android:
ai.masko:playerfrom Maven Central, thenMaskoPlayerView(context).loadClip(url)withstacked_video_av1. - React Native and Expo:
npm install @masko/player-react-native, then<MaskoView clip={{ hevc, stacked }} />, and rebuild the native app. - Flutter:
flutter pub add masko_player, thenMaskoView(clip: MaskoClipFiles(hevc: hevc, stacked: stacked)).
A canvas release
get_release_delivery for the target returns the release's files, the player to install, the app's link in app_link and setup code in code (with react_native_code and flutter_code for the apple and android targets), the key already filled in. Use that code: never guess the player API. Targets: web for websites and Electron, apple for iPhone, iPad and Mac, android; React Native and Flutter use apple on iOS and android on Android.
The app reads the release through that link, which carries the mascot's app key: never the account key or a sign-in token. The key can only play that mascot's released canvases, so it is safe to ship, and there is nothing to make or ask about. The canvas needs no publishing.
- iPhone, iPad and Mac:
MaskoPlayer(url:appKey:)(player 0.1.12 and later) makes the request, keeps the files and picks up new releases itself. - Websites and Electron: the web player (0.1.13 and later) does it from the link straight from the page, with no server:
mountMascot(element, { url, appKey }), or<MaskoPlayer url={url} appKey={appKey} />in React. The API refuses a page that sends the account key. - Android, React Native and Flutter: the app makes the request and gives the player a
getDeliverythat repeats it before the signed links expire.
A mascot on the desktop
A desktop pet, or any mascot that lives on the Mac desktop outside the app's windows, goes in MaskoOverlay(player: player, size:) from the Swift package's MaskoOverlay product (0.1.20 or later), never a window of your own: it stays above every app, on every desktop, and still while desktops swipe. The app moves it with setFrameOrigin. Leave it out of Mac App Store apps, since it uses a private macOS framework. On Windows, a desktop mascot is an Electron app with a transparent window and the web player.
Sync the app with the animation
When something in the app must happen at a moment of a clip (close a window when the finger touches it, play a thud when the mascot lands, show a bubble when it turns), call get_release_delivery with motion: "timeline": each clip then lists its moments (touch, takeoff, landing, turn, appears, disappears, with the part) and sections, in seconds from the clip's start. Act on those times when the player's clip event or position() shows that clip; never guess a time. When the app must also place something on the mascot (a finger on a button, a bubble above the head), ask motion: "both": the app request then returns each clip's motionUrl, which the app's code downloads for every part's position over the clip (page generate/motion).
Drive it from the app
set(name, value)holds a state;fire(name)sends a one-time event.app_inputsin the delivery says which input takes which: a reaction the release plays once is fired, never held on.- Use only the inputs the canvas declares or the behaviors listed in
player/canvas; never invent methods or input names. - The player does not watch the pointer: the app sets
pointerHoverand firesclickitself. - Every move starts when the loop on screen ends, unless the app sends the value with
instant. The canvas's priorities decide which behavior shows. - Clips with sound play it by default;
sound: falsemutes them. Browsers allow sound only after the person's first tap or click on the page. Listen toerrorevents.
Check it
Check the starting pose, each event and the way back, quick repeated events, a slow or failing load, and transparency on light and dark backgrounds. Say which platform and behaviors you actually ran: never claim it works from written code alone.
More detail: player (every platform), player/one-animation, player/canvas, player/app-keys and generate/cdn.
