@animochi/react-native

The React Native SDK fetches a project's ETag-enabled OTA manifest, verifies each downloaded .animochi package with SHA-256, extracts it into a content-addressed device cache, and swaps states only after the full package is ready. A bundled fallback can be supplied for first launch and offline use.

Each .animochi package holds a transparent AVIF spritesheet plus a manifest.json describing its frame grid (no video, no platform-specific files) — AnimochiPlayer steps through frames with expo-image's Image and a View, so there's no native video/webview dependency to install.

Install

npm install @animochi/react-native react-native-fs react-native-zip-archive expo-image
cd ios && pod install

expo-image bundles its own AVIF/WebP decoders (SDWebImage on iOS, Glide on Android) rather than relying on the OS's own image codecs, so playback doesn't depend on OS version. In a bare React Native app (not using Expo), run npx install-expo-modules@latest once to wire up expo-modules-core — this is a lightweight native-module registration step, not the full Expo framework/tooling. Expo projects need a development build/prebuild because these peers contain native code.

Get your API key and origin

Open your project's dashboard → SDK & Publishing in the sidebar:

• API origin is shown at the top of that panel (e.g. https://animochi-web-production.up.railway.app, or your custom domain once one is configured).
• API keys: click Create key, name it (e.g. "Production"), and copy the secret shown — it's only ever displayed once. Use it as sdkKey below.

Publish before you sync

The SDK reads from a project's published release, not directly from whatever you've generated — regenerating or adding an animation in the dashboard doesn't reach devices until you publish. From the same SDK & Publishing panel, click Review & publish to pick exactly which characters' animations to ship (with a select-all option) and confirm — that selection becomes a new release version.

Reference an animation

Each animation has a key — a short slug like wave or jump-a1b2c3, generated from its name when you create it. This is the exact string to pass as state. Every animation card in the dashboard shows its key with a copy button next to the name.

Usage

const client = new AnimochiClient({
  projectId: "your-project-id",
  sdkKey: "animochi_...",       // from the SDK & Publishing panel
  apiOrigin: "https://animochi-web-production.up.railway.app",
  bundledFallback: {
    packageUri: "file:///path/in/the/native/app/bundle/fallback.animochi",
    contentHash: "sha256:...",
    state: "idle",
  },
});

<AnimochiPlayer client={client} state="wave" style={{ width: 240, height: 240 }} />

Omit state to play the project's default animation. AnimochiPlayer calls client.sync() on mount (disable with autoSync={false} to control timing yourself, e.g. call client.sync() once at app startup) and re-resolves whenever state changes.

bundledFallback is optional — the SDK works without it, just with nothing to show until the first successful sync(). When supplied, it must be a single-state .animochi package (one manifest.json + spritesheet, matching contentHash) shipped inside the app bundle; the SDK extracts it into the same verified cache shape without requiring a network connection. A character's Export .animochi button in the dashboard produces a different, multi-state bundle meant for archival/backup, not this — there's no dashboard download for a single-state package yet.

See API.md for the manifest and asset endpoint contract.