Getting Started

Quick Start

1. Load the SDK

IIFE (browser script tag) — pin a version in production:

<!-- Production: pin to a specific version -->
<script src="https://cdn.getjar.com/v5.2.0/getjar-iap-sdk.min.js"></script>

<!-- Development only: latest (5-minute CDN TTL) -->
<script src="https://cdn.getjar.com/latest/getjar-iap-sdk.min.js"></script>

ESM (bundler or modern browser):

import { Configuration, Leaderboard, UserGame, bridge } from 'https://cdn.getjar.com/v5.2.0/getjar-iap-sdk.esm.js';

If your game only needs the host integration and no HTTP calls, load the bridge-only bundle instead — getjar-iap-bridge.min.js (~6 KB gzipped, no axios), global GetjarIAPBridge.

2. Get Your API Key

1. Sign in at https://dev.getjar.com
2. Copy your API key from the dashboard

3. Initialize the SDK

Create a Configuration instance, then pass it to each SDK class. IIFE global is GetjarIAP:

// After script loads, GetjarIAP is available globally
const cfg = new GetjarIAP.Configuration({
  basePath: 'https://sdk-new.getjar.com',
  apiKey: 'your-api-key'
});

const leaderboardClient = new GetjarIAP.Leaderboard(cfg);
const userGameClient = new GetjarIAP.UserGame(cfg);

ESM / bundler:

import { Configuration, Leaderboard, UserGame, bridge } from 'https://cdn.getjar.com/v5.2.0/getjar-iap-sdk.esm.js';

const cfg = new Configuration({
  basePath: 'https://sdk-new.getjar.com',
  apiKey: 'your-api-key'
});

const leaderboardClient = new Leaderboard(cfg);
const userGameClient = new UserGame(cfg);

Build the clients once and keep them. They read userId and accessToken from the shared Configuration on every call, so the connect step below fills both in place as soon as the host supplies them.

4. Connect to the Host

Identity arrives from the host page over postMessage, not as a URL parameter. Use the SDK bridge — bridge.connect() — for that handshake and for every other message. It runs the GAME_LOADED exchange, pins the origin in both directions, falls back to a guest session when the host stays silent, and writes the resolved identity into your Configuration.

const host = await GetjarIAP.bridge.connect({
  configuration: cfg,
  hostOrigin: 'https://getjar.com'
});

// Resolved before the promise settles — never a race, never a wait of your own.
console.log(host.identity.status);       // 'authenticated' | 'guest'
console.log(host.identity.anonymousId);
console.log(host.identity.eightpointId);

startGame();

connect() resolves as a guest rather than rejecting when the player is signed out — that is a normal state, not an error. It also re-applies the token on every later PARENT_DATA the host sends, so a cross-tab sign-in updates your clients without any work from you. When the host answers nothing at all, identity resolves as a guest with a null anonymousId — there is no id to write, so userId stays unset and requests go out without x-user-id. Call cfg.setUserId() with your own local guest id if your game needs one.

5. Submit a Score

There is one route: end the round through the bridge and the host submits the score on your behalf. The Leaderboard SDK is read-only — it has no score submission method, so there is nothing to choose between.

const roundId = crypto.randomUUID();

// Terminal end of round — the host validates, acks, then submits the score.
await host.gameOver({ roundId, score: 1250, durationMs: 94000 });

// Mid-game progress, distinct from the terminal end of round.
await host.levelComplete({ roundId, level: 3 });

The promise resolving means the host accepted the round, not that the score reached the backend — never block your end-of-round UI on it. Invalid input rejects with BridgeValidationError before anything is sent, and a host that never answers rejects with BridgeTimeoutError.

Configuration Options