Eight endpoints. Under thirty minutes.

Post Score

Call on game-over, round-end or level-complete. Records the score, writes a leaderboard entry, and returns the player rank, a top-10 snippet and ready-made share data.

// Request fields:
//   gameId: string (required)
//   score: number (required)
//   playerId: string — omit for anonymous
//   gameName: string — falls back to gameId
//   durationMs: number — round duration in ms
//   sessionId: string
//   platform: string — e.g. "flutter-webview"
//   playerName: string — falls back to "Player"
//   metadata: object — arbitrary key-value pairs

const data = await InZoneSDK.postScore({
  score: 14820,
  durationMs: 92447,
  playerName: 'ProGamer42',
  metadata: { lap: 3 },
});

// Response types:
//   data.player.rank: number | null
//   data.score.value: number
//   data.score.best: number
//   data.leaderboard.entries: Array<{
//     rank: number, playerId: string,
//     displayName: string, score: number }>
//   data.share.title: string
//   data.share.url: string

Challenge

Creates a 24-hour duel and generates a share card in one call — the old standalone share-card endpoint no longer exists. Includes a deep link (inzone://game?gameId=…, delivered via an AppsFlyer OneLink with deep_link_value=community_game) that opens the community game on the Game Hub inside InZone.

// Request fields:
//   gameId: string (required)
//   senderId: string (required) — challenger's userId
//   recipientId: string — omit for open challenge
//   score: number
//   message: string — default "Can you beat this score?"
//   sessionId: string
//   challengeType: string — default "duel"
//   expiresHours: number — default 24
//   title: string — auto-generated from score if omitted
//   template: string — default "default"
//   shareUrl: string — default AppsFlyer OneLink (deep_link_value=community_game, af_dp=inzone://game?gameId={gameId})
//   imageUrl: string | null

const data = await InZoneSDK.sendChallenge({
  senderId: config.userId,
  recipientId: 'friend_abc',
  score: 14820,
  message: 'Can you beat this score?',
});

// Response types:
//   data.challenge.challengeId: string
//   data.challenge.gameDeepLink: string
//   data.challenge.expiresAt: string (ISO 8601)
//   data.challenge.status: "pending"
//   data.share.url: string
//   data.share.gameDeepLink: string
//   data.share.text: string

Progress

Shareable snapshot of an achievement, high score or milestone — without creating a challenge. Use for "Share Progress" / "Brag" buttons. No bridge method — use direct fetch.

// Request fields:
//   gameId: string (required)
//   userId: string (required)
//   score: number
//   title: string — auto-generated from score
//   message: string — default "Check out what I just did"
//   sessionId: string
//   visual: string — default "auto"
//   metrics: object — arbitrary stats for share card
//   achievements: string[] — achievement IDs/names
//   template: string — default "progress"
//   imageUrl: string | null
//   shareUrl: string — default AppsFlyer OneLink (deep_link_value=community_game, af_dp=inzone://game?gameId={gameId})

const config = window.__INZONE_SOCIAL_LOOP_CONFIG__;
const res = await fetch(config.backendBaseUrl
  + '/api/game-sdk/progress/share', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    gameId: config.gameId,
    userId: config.userId,
    score: 14820,
    title: 'New high score — 14820!',
    metrics: { kills: 15, accuracy: 0.82 },
    achievements: ['sharpshooter'],
  }),
});
const data = await res.json();
// data.shareCard.shareCardId: string
// data.share.title: string
// data.share.url: string
// data.shareTargets: string[]

Chat

Opens or joins the per-game group chat thread and sends a message. If no message is provided, one is built from context (score, wave, result). InZone renders the chat UI — your game just ensures the thread exists and the player is in it.

// Request fields:
//   gameId: string (required, unless threadId given)
//   threadId: string — reuse a specific thread
//   userId: string
//   sessionId: string
//   characters: string[] — AI character names
//   context: object — { score, result, wave, gameName }
//   message: string — auto-built from context if omitted

const data = await InZoneSDK.openChat({
  context: { score: 14820, result: 'win', wave: 5 },
  characters: ['nova', 'orin'],
});

// Response types:
//   data.conversation.conversationId: string
//   data.conversation.participants: string[]
//   data.conversation.characters: string[]
//   data.conversation.context: object

Game State

Account overview: coin balance, last 50 transactions and last 50 scores, newest first. Call on game load before offering purchases. Requires X-Game-Key header.

// Request fields (query params):
//   gameId: string (required)
//   userId: string (required)
// Header: X-Game-Key (required)

const data = await InZoneSDK.gameState({});

// Response types:
//   data.data.balance: number — coin count
//   data.data.currency: "Coin"
//   data.data.transactions: Array<{
//     transactionId: string, title: string,
//     coins: number, commissionCoins: number,
//     developerCoins: number, status: string,
//     createdAt: string }>
//   data.data.scores: Array<{
//     scoreId: string, score: number,
//     durationMs: number, displayName: string,
//     createdAt: string }>

Save / Load

Per-player save blob — progress, inventory, checkpoints. One slot per player per game; each POST overwrites it, max 256 KB, state must be a JSON object. version auto-increments; version 0 means a new player (never a 404). NOT for coin balances.

// Load — GET query params:
//   gameId: string (required)
//   userId: string (required)
// Save — POST body:
//   gameId: string (required)
//   userId: string (required)
//   state: object (required) — max 256 KB
//   metadata: object — { saveLabel, platform, … }

const config = window.__INZONE_SOCIAL_LOOP_CONFIG__;
const base = config.backendBaseUrl + '/api/game-sdk';

// Load response types:
//   data.data.state: object
//   data.data.version: number — 0 = new player
//   data.data.metadata: object
//   data.data.updatedAt: string | null
const res = await fetch(base + '/state'
  + '?gameId=' + config.gameId
  + '&userId=' + config.userId);
const save = (await res.json()).data;

// Save response types:
//   data.data.version: number (auto-incremented)
//   data.data.bytes: number
//   data.data.savedAt: string
await fetch(base + '/state', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    gameId: config.gameId,
    userId: config.userId,
    state: { level: 12, inventory: ['shield'] },
    metadata: { saveLabel: 'Checkpoint Level 12' },
  }),
});

Leaderboard

Full standings for a game, ordered by score descending. post-score already returns a top-10 snippet — use this for a standalone leaderboard screen or more entries. No bridge method — use direct fetch.

// Request fields (query params):
//   gameId: string (required)
//   limit: number — default 50, max 200
//   scope: string — default "global"

const config = window.__INZONE_SOCIAL_LOOP_CONFIG__;
const res = await fetch(config.backendBaseUrl
  + '/api/game-sdk/leaderboard'
  + '?gameId=' + config.gameId + '&limit=20');
const data = await res.json();

// Response types:
//   data.totalEntries: number
//   data.scope: string
//   data.entries: Array<{
//     rank: number, entryId: string,
//     playerId: string, playerName: string,
//     score: number, metadata: object,
//     createdAt: string }>

Coins

Purchase at one of four fixed tiers, debited from the player's InZone balance. Purchases are atomic: on success the coins are already deducted; after a network failure, reconcile via game-state. Requires X-Game-Key header.

// Request fields:
//   userId: string (required)
//   gameId: string (required)
//   title: string (required) — shown in history
//   description: string — defaults to title
//   sessionId: string
// Header: X-Game-Key (required)

try {
  const data = await InZoneSDK.purchaseCoinTier(10, {
    title: 'Extra attempt',
    description: 'One more run',
  });

  // Response types:
  //   data.data.transactionId: string
  //   data.data.coins: number
  //   data.data.newBalance: number
  //   data.data.commissionCoins: number
  //   data.data.developerCoins: number
  //   data.data.commissionRate: number (0.1)
  //   data.tier.name: string
  updateCoinDisplay(data.data.newBalance);
  startNewRound();
} catch (err) {
  // INSUFFICIENT_BALANCE → err.details has
  //   currentBalance: number, required: number
  showMessage(err.message);
}