#Getting Started — Game SDK Integration Kit

Updated 2026-09-18: SDK installation and game-only embedding are separate deliverables. Implement the game-only embed guide, then register its deployed URL. A homepage with SDK installed can still overflow inside the player.

Updated 2026-09-17: developer handoff · Mobile & PC requirements. The player now farms automatically after 60 seconds; the existing SDK completion path retains its 45-second gate. Both share one daily award. Host heartbeats run every 15 seconds. The submission form exports a developer brief.

Hands-on instructions written to drop straight into each game's repository. The full specification is the SDK Specification; a complete working example is the reference game Tower Drift (tokenapps.io/embed/demo-game/index.html — it is actually live in the catalog). Following this document alone completes the integration.

#0. Three Things to Know First

1. Measurement is already happening. Play time and return rates are measured by the platform outside the game. Even without any of the integration below, the game keeps running as it does now and metrics keep accumulating. What integration unlocks is TAP (TokenApps Points)-earning integration, account saves, and ad rewards.
2. The game only requests. Awards, caps, and whether an ad appears are all decided by the server. Sending something wrong does not become fraud, and manipulation gains nothing.
3. Guest is the default. The game must work fully for users who arrive without signing in. Encouraging sign-in is the platform's job (via an invitation card after play) — forcing sign-in inside the game is rejected in review.

#1. Required Integration — 5 Minutes

Finish just this step and TAP integration works.

In the game HTML's <head> or at the end of <body>:

<script src="https://tokenapps.io/sdk/v1.js"></script>
<script>
  TokenApps.ready();   // Once, at the moment the game becomes playable
</script>

Then one line at the point where a round naturally ends:

TokenApps.track("session_complete");

That is all. One thing to watch: if measured play that day is under 45 seconds, the server responds ignored (an anti-fraud gate). Fired right after load it is ignored, but the award is idempotent, so when it is sent again at the end of the next round after actual play, it is granted normally at that point — the game has nothing extra to handle.

When opened outside TokenApps (a direct visit on your own site), the SDK quietly does nothing — no branching code is needed.

#2. Recommended — Showing Award Results

TokenApps.on("points", function (p) {
  if (p.status === "awarded")         showToast("+" + p.delta + "P earned!");
  else if (p.status === "duplicate")  {} // Today's share already granted — stay quiet
  else if (p.status === "signin_required") {} // Guest — the platform handles the invitation
});

The platform shows its own toast as well, so you can skip this, but layering in-game presentation on top (effects, sound) makes the experience feel much better.

#3. Optional — Account Saves

Browser privacy settings can block localStorage even when an external frame retains its origin. Guard access and use SDK saves for cross-device progress: one slot per game per user, 64KB.

TokenApps.on("session", function (s) {
  if (TokenApps.canSave()) {
    TokenApps.load().then(function (save) { applySave(save); /* null = first play */ });
  }
});
// When saving:
TokenApps.save({ level: 7, bestScore: 1200 });

For Chart Run, a summary of practice history; for TPC Coin Pusher, cumulative records; for Baedal Rush: Riders, stage progress — those are the natural candidates. Guests have canSave() === false — just skip it.

#4. Optional — Rewarded Ads

Request at whatever point the game chooses; the platform presents the choice screen and the ad in its own UI and reports only the result. No ad SDK or account is needed on the game side.

TokenApps.requestRewardedAd("revive").then(function (r) {
  if (r.status === "rewarded") revivePlayer();  // The server has already granted the points
  else showNormalGameOver();                     // dismissed/unavailable/failed all land here
});

• Allowed placements: "revive" (continue), "bonus_points" (bonus spot).
• Iron rule: unavailable is a normal response. For guests, frequency caps, and the daily TAP ceiling, no ad appears. Always keep a path that proceeds without ads — "watch an ad to continue" is grounds for review rejection. You can follow the continue-button handling in the reference implementation (Tower Drift) as-is.

#4.5 Optional — Selling In-game Goods

To sell items or themes for TAP: register the products (SKU, name, price, type) yourself in the Products panel under My games. The game-side code is three lines — getProducts() to display the shop, requestPurchase(sku) to buy (confirmation and payment happen on the platform sheet), and getInventory() to restore on restart. Grant only on a purchased/already_owned response, and restore from the inventory — for details, see SDK Guide §4.7.

#5. Integration Checklist

Open the game on TokenApps (tokenapps.io/ko/app/<slug>/play):

• Complete a round as a guest → the game works normally, and the platform invitation card appears right after completion
• Sign in, play at least 45 seconds, and complete a round → a "+15 TAP" toast
• Complete a second round the same day → no award (duplicate), the game runs fine
• (If saves are integrated) Save → sign in from another browser → progress carries over
• (If ads are integrated) Continue → choice screen → watch → revive + TAP; "No thanks" → falls through naturally to the normal game over
• Opening the game directly on your own domain produces no errors

#6. Remaining Work Assignments

TPC Coin Pusher blocking issue (observed 2026-08-24): There is no frame-blocking header, yet inside TokenApps's sandboxed iframe the game renders nothing at all (no console errors either — presumably frame-environment detection or a third-party-cookie dependency). It has therefore been demoted to external link only in the catalog for now. Let us know once it is fixed to render in an iframe embed — we will restore the play_url and reopen embedded play (measurement and TAP earning included).

Please frame questions against the SDK Specification. Where the specification and this document differ, the specification is correct.