#tokenApps SDK — developer handoff v1.4

Updated: 2026-09-18. Runtime: https://tokenapps.io/sdk/v1.js (1.4.0). This guide describes the deployed code; the specification covers the full wire contract.

#What to deliver

1. A public HTTPS player URL that opens the game itself, without a landing page, navigation, FAQ or a second scrollbar.
2. Mobile / PC / tablet support, touch / keyboard / mouse controls, orientation and supported game languages.
3. One responsive build, or mobile and PC review URLs with a primary URL that routes correctly. The host currently uses one play_url; it does not select the submitted device URLs automatically.
4. SDK status, tested browsers with versions, known issues, build version and a developer contact.
5. Icon, cover and up to three screenshots.

Use the submission form to enter the details and download a Markdown brief. Existing owners can update the same information in My games. The private brief is visible to its owner and operators, not the public listing. Unchecked tests mean unverified, not passed.

See Mobile & PC for the implementation checklist and target viewports.

#Game-only screen: required alongside the SDK

SDK integration does not turn a website into an embedded game. It connects identity, scores and saves; the game team owns routing, layout, canvas sizing and input.

1. Reuse the existing game in a deployed /embed route (or equivalent). Exclude website navigation, hero, FAQ and footer; preserve the board, HUD, pause, sound, restart and touch controls.
2. Fit the actual iframe width and height. Reserve HUD/control space, observe the remaining board container, use contain scaling, update rendering resolution and input coordinates, and preserve the current round during resize.
3. Keep SDK handlers persistent and register them before ready(). Start guest play independently of SDK/network success. Do not add nested iframes or a second login flow.
4. Test inside frames, including 310x360, 380x640, 558x160, 834x220, 1340x560 and 1894x875 CSS px. No unintended scrollbars and no clipped controls. Report unsupported configurations rather than hiding failures with overflow.
5. Deploy first, then register the exact game-only URL. /embed is not auto-created, and mobile/PC review URLs do not automatically replace the primary player URL.

Read the detailed embed implementation for Next.js/Vite routing, HTML/CSS, canvas scaling, CSP, diagnostics and a copyable AI coding request. Try the runnable HTML reference; it sends no score or reward events.

#Minimal integration

A game must boot for guests and when the platform is unavailable. Do not make gameplay wait indefinitely for a session event. This sketch uses your own game functions:

<script>
  startGameAsGuest(); // Your normal game boot, once.
  function connectPlatform() {
    if (!window.TokenApps) return;
    TokenApps.on("session", function (session) {
      // This event can repeat on login / token refresh. Do not restart a round.
      setPlayerIdentity(session.player || null);
      setGameLocale(session.locale || "en");
    });
    TokenApps.ready();
  }

  function onGameOver(score) {
    if (!window.TokenApps) return;
    TokenApps.submitScore(score);
    TokenApps.track("session_complete");
  }
</script>
<script async src="https://tokenapps.io/sdk/v1.js" onload="connectPlatform()"></script>

Register listeners before ready(). The runtime retries its handshake until the first session arrives. session.player.id is a per-game pseudonym, not a platform account identifier. Do not implement a second OAuth flow inside the frame. Platform sign-in currently offers Google and Privy; new TokenPost sign-in/linking is disabled. Legacy player.verified is compatibility data, not a requirement for play.

#Automatic farming and SDK events

The host heartbeats every 15 seconds while visible. Games do not send elapsed time or reward amounts. The server decides eligibility and caps. A returning session may already have earned its reward. Keep gameplay usable on ignored, duplicate, capped and signin_required.

TokenApps.on("points", function (result) {
  // SDK event response only. Automatic farming is displayed by the host.
  if (result.status === "awarded") showPoints(result.delta);
});

#Save, load and browser storage

External HTTPS frames retain their origin through allow-same-origin; platform-hosted relative frames do not. Browser privacy settings can still deny cookies, localStorage or IndexedDB. Guard storage access and keep an in-memory fallback. Never assume third-party storage works.

TokenApps.canSave() checks availability. Signed-in players can call load() and save(json) for one cross-device slot per game (up to 64KB serialized). Catch guest and expired; a new session can arrive after expiry. A repeated session event must not overwrite an active run with an older save.

#Optional capabilities

Ads, purchases and matchmaking may be unavailable. Keep a solo/replay path. Prices belong to the platform; restore purchases using inventory and grant only on purchased / already_owned. A duel changes rating, not TAP.

Use feature detection for optional APIs. TokenApps.on() registers a callback; v1.4 has no off() method. Register once in a persistent integration module; avoid accumulating subscriptions every time a React view mounts.

#Embed and release checks

• Permit https://tokenapps.io in the game's HTTP CSP frame-ancestors. Remove conflicting X-Frame-Options: DENY/SAMEORIGIN on the player document.
• Fit the iframe viewport, not the monitor. Resize without resetting the run. Fullscreen and rotation are optional enhancements.
• Provide touch controls for every mobile action. No hover-only or keyboard-only mobile path.
• Test guest boot, blocked storage, audio unlock, background/resume, replay and unavailable SDK features.
• Test inside the tokenApps player on real supported browsers, not only in a standalone tab.
• An automatic header embed check does not certify input, layout, audio or SDK behavior.

Detailed device checklist · Feature guide · Specification · Submit