Tokomi MiniApp

Check whether the current container supports a given SDK capability.

boolean — returned synchronously

• true only means "the container recognizes this API", not that the current launch mode can use it (when opened from the store, actor.speak still fails for lack of a sessionId).
• On startup the container writes the capability table into window.__shine_capabilities; the workbench preview injects one too.
• When no capability table is injected (plain browser debugging), the check falls back to whether the SDK itself exposes the method.

if (Shine.canIUse('device.vibrate')) {
  await Shine.device.vibrate({ style: 'light' });
}
if (!Shine.canIUse('tts.listVoices')) {
  // Older app build: hide the narration voice picker and fall back to silent text
}

Run one AI conversation turn and return the model's reply text.

Promise<string> — AI reply text

const reply = await Shine.ai.chat({
  system: 'You are a tarot reader — mysterious but friendly.',
  message: 'Read these three cards for me: The Fool, The Lovers, Wheel of Fortune',
});

Generate an image from a text description.

Promise<string> — public OSS URL of the image

const url = await Shine.ai.image('Watercolor style, an orange tabby cat sitting on a windowsill');
// <img src={url} />

Read the value of a key.

Promise<any | null> — null if never set

const save = await Shine.storage.get('game_save');
if (save) board = JSON.parse(save);

Write or overwrite a key.

Promise<void>

await Shine.storage.set('coins', 128);
await Shine.storage.set('inventory', { sword: 1, potion: 3 });

Delete a key.

Promise<void>

Enumerate keys under the current user+app (values not included), with cursor pagination.

Promise<{ keys: string[]; nextCursor: string | null; hasMore: boolean }>

const page = await Shine.storage.list({ prefix: 'save_' });
for (const k of page.keys) console.log(k);

Read multiple keys in one call (up to 50).

Promise<Record<string, any | null>>

const vals = await Shine.storage.mget(['coins', 'inventory']);
console.log(vals.coins, vals.inventory);

Get key count, used space, and quota limits.

Promise<{ keyCount: number; currentSizeBytes: number; limitKeys: number; limitSizeBytes: number }>

Bulk-delete keys, optionally by prefix. The platform shows no confirmation — call ui.confirm yourself.

Promise<{ status: 'ok'; deletedCount: number }>

Session-scoped storage namespace: identical methods to Shine.storage.*, but isolated per session — the same user opening the same app from different stories/sessions gets an independent save slot each, with no cross-contamination.

Same as the corresponding Shine.storage.* method

• If you need per-story saves, use session.* — no need to concatenate sessionId into your keys yourself.

// User level: shared across stories (settings, favorites)
await Shine.storage.set('settings', { sound: true });

// Session level: one save slot per story (progress / stats / mini-games)
await Shine.storage.session.set('progress', { chapter: 3, hp: 80 });
const p = await Shine.storage.session.get('progress');

Get current-user info. When launched with a story (launch options include sessionId) it returns the player's in-story persona (mask / user_role) — the same source as the user_identity injected by actor.speak. In store mode it returns the real account. The return shape is identical either way, so you don't need to branch.

Promise<{ id: string; nickname: string; avatar: string | null }>

// With a story attached, nickname is the player's in-story name (the mask), matching what characters see
const me = await Shine.user.getInfo();
document.getElementById('name').textContent = me.nickname;

Brief message at the top of the screen.

Promise<void>

Confirmation dialog.

Promise<boolean> — true if the user taps OK, false on cancel

Single-line input dialog.

Promise<string | null> — null on cancel

Bottom action sheet.

Promise<number> — index of the selected option; -1 on cancel

Control the container's top navigation bar.

Promise<void>

• MiniApps are full screen by default (navigation bar hidden): the container takes no top bar, and back / app details / story switching are handled by the native capsule in the top-right corner — you don't need (and shouldn't) draw your own back button. Call { visible: true } only if you actually want a top bar.
• The capsule covers part of the top-right corner — don't put buttons or key info there. See getCapsuleRect below for how to avoid it.
• With the navigation bar hidden, the page extends under the status bar / notch, so handle the top safe area yourself: the container provides --shine-safe-area-{top,right,bottom,left} (in px, auto-updated on rotation); env(safe-area-inset-*) is always 0 in Android WebView, so always use max(env(...), var(--shine-safe-area-*, 0px)) as a fallback.

await Shine.ui.setNavigationBar({ visible: false });

/* Root container of a full-screen page: iOS uses env(), Android uses the container's variables — take the max; adapts to rotation automatically */
body {
  padding:
    max(env(safe-area-inset-top,0px),    var(--shine-safe-area-top,0px))
    max(env(safe-area-inset-right,0px),  var(--shine-safe-area-right,0px))
    max(env(safe-area-inset-bottom,0px), var(--shine-safe-area-bottom,0px))
    max(env(safe-area-inset-left,0px),   var(--shine-safe-area-left,0px));
}

Get the native capsule's position on the page, so a custom top bar can avoid it.

{ visible, top, right, bottom, left, width, height } — CSS px, returned synchronously

• Same idea as WeChat's wx.getMenuButtonBoundingClientRect: when drawing your own title bar / top toolbar, keep content within left — don't let it slide under the capsule.
• For pure-CSS layouts you can use the container-provided --shine-capsule-{top,right,width,height} directly, without calling this method.
• When the top bar is visible (setNavigationBar({ visible: true })), the capsule moves into the bar and no longer overlaps the page; visible is then false and all values are 0.
• After rotation or toggling the top bar, the container refreshes and dispatches a shine:capsulechange event — dynamic layouts can listen to it and re-measure.

/* Pure CSS: leave room for the capsule on the right of a custom top bar */
.app-header {
  padding-top: max(env(safe-area-inset-top,0px), var(--shine-safe-area-top,0px));
  padding-right: calc(var(--shine-capsule-width,0px) + var(--shine-capsule-right,0px) + 8px);
}

/* JS: when you need exact coordinates */
const cap = Shine.ui.getCapsuleRect();
if (cap.visible) toolbar.style.maxWidth = cap.left - 12 + 'px';
window.addEventListener('shine:capsulechange', relayout);

Set the status bar text color.

Promise<void>

Lock or restore the screen orientation.

Promise<void>

Immersive full screen: hide/restore the system status bar.

Promise<void>

• This hides the system status bar (clock/battery); Android also hides the bottom system bar, which the user can swipe up to reveal temporarily.
• In full screen, --shine-safe-area-top automatically becomes 0 and content fills the screen — no extra handling needed.
• The container restores the system bars automatically when the MiniApp exits; you don't need to undo it manually.
• Complements setNavigationBar: that controls the app's own navigation bar, this controls the system status bar.

// Good for distraction-free scenes: full-screen games, image viewers, video
await Shine.ui.setNavigationBar({ visible: false });
await Shine.ui.setFullscreen(true);
// When leaving the page / restoring
await Shine.ui.setFullscreen(false);

Get platform, host app version, light/dark theme, screen size, and safe area.

Promise<{ platform: 'ios'|'android'|'other'; appVersion: string; theme: 'light'|'dark'; locale: string; screen: { width, height, pixelRatio }; safeArea: { top, right, bottom, left } }>

• theme follows the host app's light/dark mode; your H5 can use it to switch its own color scheme.
• appVersion is the host app version; combined with canIUse it explains why a capability is missing on a given device.
• Browser / preview environments also return a synthesized result (appVersion is 'preview' in the preview).

const info = await Shine.device.getSystemInfo();
document.documentElement.dataset.theme = info.theme;

Write to the system clipboard.

Promise<{ ok: boolean }>

await Shine.device.setClipboard({ text: inviteCode });
await Shine.ui.toast('Invite code copied');

Read text from the system clipboard.

Promise<{ text: string }>

• Some browsers show a permission dialog; the Promise rejects if the user denies.

const { text } = await Shine.device.getClipboard();
if (text) input.value = text.trim();

Short haptic feedback (game combos, button presses, etc.).

Promise<{ ok: boolean }>

if (Shine.canIUse('device.vibrate')) {
  await Shine.device.vibrate({ style: combo > 1 ? 'medium' : 'light' });
}

Read the parameters the container passed when launching the MiniApp.

{ sessionId?: string; characterId?: string } | null

Opened directly from the store → null; launched from a story → includes sessionId

• actor.speak / contact.list / wallet all depend on sessionId later on.
• characterId can be passed to character.getDetail() as the default story ID.

const launch = Shine.context.getLaunchOptions();
if (!launch) {
  // Store mode: show a friendly empty state
  return;
}
console.log(launch.sessionId, launch.characterId);

Fetch the public details of the attached story.

Promise<{ id, name, brief, avatar_url, cover_url }>

• To make a character speak in persona, use actor.speak — don't try to assemble the internal prompt yourself.

const story = await Shine.character.getDetail();
titleEl.textContent = story.name;

Fetch the contact list.

Promise<Array<{ id: string; name: string; avatar_url: string | null; is_custom_npc: boolean }>>

• id can be used directly as the actorId for actor.speak.

const contacts = await Shine.contact.list();
const partner = contacts[0];

Have a given actor generate a line of dialogue.

Promise<string> — the actor's line

• For information-isolation games like Werewolf: turn off includeOtherActors / includeActorMemory.
• For a judge / system narrator: turn off includeActorPersona and control everything via extraSystem.

const reply = await Shine.actor.speak({
  actorId: partner.id,
  message: 'Where do you think the story goes from here?',
  extraSystem: 'You two are reading chapter three together; stay in character.',
  includeWorldScenario: true,
  includeActorPersona: true,
  customHistory: [
    { role: 'user', content: 'What did we discuss last round?' },
    { role: 'assistant', content: 'You mentioned the protagonist\'s choice…' },
  ],
});

Deliver a (one-way by default) message to a recipient under some sender identity — tip-offs, approaches, notifications, warnings, or making a character DM the player.

Promise<{ status: 'ok' | 'blocked'; delivered: boolean }>

• Difference from speak: notify returns no dialogue — it just makes the recipient "aware" so they can act on it themselves (they may later reach out to the user or others).
• Delivering to an NPC: the sender isn't visible in contacts and the DM is invisible to the user; the message enters the target's memory, so they're naturally informed next time they appear. Delivering to 'user': the message visibly lands in the player's inbox (raises the unread count).

const contacts = await Shine.contact.list();
const cop = contacts.find(c => c.name === 'Officer Zhang');

// 1) Anonymous dark-web tip to an NPC: custom sender identity, invisible to the user
await Shine.actor.notify({
  actorId: cop.id,
  message: 'There is a deal at the east warehouse tonight. Move fast.',
  fromName: 'Unknown number',
  fromPersona: 'A mysterious informant of unknown identity. Speaks tersely and never reveals who they are.',
});

// 2) Deliver to the player: the message visibly lands in their WeTalk inbox
await Shine.actor.notify({
  actorId: 'user',
  message: '[System] You received an anonymous threat letter…',
  fromName: 'Anonymous letter',
});

// 3) Have an existing character DM the player (actor → user)
await Shine.actor.notify({
  actorId: 'user',
  fromActorId: cop.id,
  message: 'It\'s me, Zhang. There is something I have to tell you right now.',
});

Get the platform voice catalog — with an id you can speak right away, no story or character needed.

Promise<Array<{ id: string; name: string; gender: string; tags: string[]; languages: string[]; previewUrl: string | null }>>

• Same catalog as the host app's character voices, and platform additions/removals take effect immediately — don't hardcode ids; list them on your settings page and let the user pick.

const voices = await Shine.tts.listVoices({ gender: 'female' });
narratorVoiceId = voices[0].id;          // Let the user pick one in settings and save it
await Shine.tts.speak({ voiceId: narratorVoiceId, text: 'Night falls, and you push open the door.' });

Synthesize and play (only one at a time; a new call interrupts the old one). The Promise resolves when playback ends.

Promise<{ audioUrl: string; durationMs: number; usageCharacters: number; cached: boolean; cost: number }>

• Omitting both voiceId and actorId is an immediate error — the platform won't guess whose voice you want.
• The Promise resolves when playback ends. If you just want a playable URL to control yourself, use synthesize.

// Narration: no story or character needed
await Shine.tts.speak({ voiceId: narratorVoiceId, text: 'On the morning of the third day, the rain stopped.', speed: 0.9 });

// Character line: in their own voice
const reply = await Shine.actor.speak({ actorId: him.id, message: 'Your move' });
await Shine.tts.speak({ actorId: him.id, text: reply });

Resolve a playable URL without playing it — for custom playback or prefetching.

Promise<{ audioUrl: string; durationMs: number; usageCharacters: number; cached: boolean; cost: number }>

• audioUrl may be a direct OSS cache link or a streaming address (preview-stream); either plays progressively in the native player or an <audio> element.

const { audioUrl } = await Shine.tts.synthesize({ voiceId: narratorVoiceId, text: 'Steady. Read the room.' });
new Audio(audioUrl).play();

Immediately stop the audio currently played by speak (if any).

void

Loop background music (only one track at a time; calling again switches tracks).

Promise<boolean>

Shine.audio.playBgm({ url: 'https://.../bgm.mp3' });

Stop the background music.

Promise<boolean>

Pick an image from the photo library or take a photo.

Promise<string | null> — public OSS URL; null if the user cancels

Hold-to-talk recording, returning the speech-recognition text.

Promise<string | null> — recognized text; null on cancel or empty input

Fires when the MiniApp becomes visible.

void

Fires when the MiniApp becomes hidden.

void

Remove a listener.

void

Close the current MiniApp and return to the previous screen.

Promise<void>

Intercept the system back button / swipe-back and handle it yourself first.

Promise<void>

• Without a handler, one system back press closes the app. Multi-page apps or apps with overlays should register one and pop their own layers first.
• The handler must return a boolean synchronously; the container waits at most 200ms and treats a timeout as false (so stuck JS can't jam the back button).
• This only covers system back (the Android back button / system back gesture); the ⊗ on the top-right capsule is "close" and always exits directly, bypassing the handler.
• Use Shine.nav.offBackPressed() to remove the interception.

Shine.nav.onBackPressed(function () {
  if (dialogOpen) { closeDialog(); return true; }   // Close overlays first
  if (page !== 'home') { goHome(); return true; }   // Then go back to home
  return false;                                      // On home, the next press exits
});

Remove the back interception, restoring "back press closes the app".

Promise<void>

Enter the current character's offline story page (the offline scene).

Promise<void>

• Pure navigation; by default enters the session and character the story was launched with.
• To "carry content and trigger a new story beat", use Shine.scene.inject() instead — it persists + notifies rather than force-navigating.
• In browsers / workbench preview it doesn't actually navigate; the call is only logged.

Persist content into the current offline session and trigger a "new story" notification.

Promise<{ status: string; injectedVisible: boolean; injectedHidden: boolean; idempotent: boolean }>

• Provide at least one of visible / hidden.
• visible drives the "new story" prompt as an unread (a light in-app toast when online / push + session badge when offline); hidden is persisted with role=system and shows no bubble.

// Won the key in a mini-game → persist a new story beat; the user gets a "new story" prompt and continues offline on their own
await Shine.scene.inject({
  visible: 'Clutching the copper key you just won, you push open the long-sealed wooden door.',
  hidden: '[Director] The player won the cellar key in a mini-game. NPCs don\'t know yet — build suspense.',
  orderId: 'scene-' + Date.now(),
});

Read the current user's spendable stars balance.

Promise<{ total: number; free: number; membership: number; permanent: number }>

const bal = await Shine.credits.getBalance();
if (bal.total < 2) await Shine.ui.toast('Not enough stars');

Get the estimated stars cost of one capability call.

Promise<{ feature: string; cost: number; currency: 'credits' }>

• The value is an estimate; promotional pricing or model differences can change the actual charge.
• Recommended use: fetch it dynamically when labeling a paid button (e.g. "Costs X stars") instead of hardcoding prices. The overall pre-entry disclosure is shown by the platform based on your declaration — you don't assemble it yourself.

Read the current user's WeTalk wallet balance in this session.

Promise<{ balanceCents: number; balanceYuan: number }>

Charge the wallet (a payment confirmation dialog is shown first).

Promise<{ status: 'ok' | 'cancelled'; charged?: boolean; balanceCents: number; balanceYuan: number }>

// orderId is an idempotency key per user within this app, ≤36 chars; a hyphenated slug is fine
const res = await Shine.wallet.pay({
  orderId: 'shop-sword-001',
  amountCents: 990,
  note: 'Buy the iron sword',
});
if (res.status === 'cancelled') return;

Refund the charge of a given orderId.

Promise<{ status: string; refundedCents: number; balanceCents: number; balanceYuan: number }>

Credit the user's WeTalk wallet (virtual-wallet "top-up / reward"; no confirmation dialog).

Promise<{ status: 'ok'; credited: boolean; balanceCents: number; balanceYuan: number }>

• This credits the virtual wallet only — unrelated to platform stars; it never gives the user real money.
• credited=false in the response means the idempotency key was hit (nothing was actually credited this time).

Send a card, as the user, into the WeTalk DM with a given contact.

Promise<{ status: 'ok' | 'blocked'; sent: boolean }>

const contacts = await Shine.contact.list();
await Shine.wechat.sendCard({
  to: contacts[0].id,
  title: "Today's fortune: Excellent",
  desc: 'Great day for travel and confessions; avoid staying up late.',
  footer: 'Fortune mini-app',
});