JavaScript SDK reference
The actual injected API, return types, callbacks and feature restrictions.
Downloads for this guide
SDK TypeScript declarationsGenerated from packages/game-sdk; browser types only.Loading and readiness
Hosted release delivery injects play-island-sdk.js after the HTML head opening tag. It assigns window.PlayIsland and dispatches playisland:ready. If your script executes later, check window.PlayIsland first; waiting only for an already-fired readiness event can hang. Do not include a second hand-written SDK or send messages to '*'. External hosted releases do not receive this injection automatically.
function startIntegration() {
window.PlayIsland.getConfiguration().then(config => {
console.log('Locale', config.locale);
}).catch(error => console.error(error.message));
}
if (window.PlayIsland) startIntegration();
else window.addEventListener('playisland:ready', startIntegration, { once: true });Public TypeScript contract
This block is generated from the real SDK source. Method existence is not permission or universal feature availability.
export interface RoomContext {
roomId: string;
code: string;
gameId: string;
playerId: string;
expiresAt: number;
launchToken: string;
}
export interface GameConfiguration {
version: 1 | 2;
sessionId: string;
gameId: string;
locale: "en" | "he";
room: RoomContext | null;
reducedMotion: boolean;
personalBest?: number;
preferences?: { muted?: boolean; reducedMotion?: boolean };
dailyChallenge?: { seed: string; releaseId: string; date?: string } | null;
}
export interface GameAcknowledgement {
eventId: string;
status?: "accepted" | "pending" | "rejected";
accepted?: boolean;
[key: string]: unknown;
}
export interface GameRewardReceipt {
id?: string;
status?: "issued" | "no_reward" | "held_for_review" | "capped";
[key: string]: unknown;
}
export interface PlayIslandSDK {
loadSave(): Promise<{
revision: number;
value: Record<string, unknown> | null;
storage: string;
}>;
saveGame(
value: Record<string, unknown>,
revision: number,
): Promise<{ revision: number; storage: string }>;
exit(): Promise<unknown>;
openLeaderboard(
mode: "daily" | "endless" | "mission",
mission?: number,
): Promise<unknown>;
send(name: string, data?: Record<string, unknown>): string;
event(name: string, data?: Record<string, unknown>): string;
started(data?: Record<string, unknown>): string;
paused(data?: Record<string, unknown>): string;
resumed(data?: Record<string, unknown>): string;
progress(value: number, data?: Record<string, unknown>): string;
score(value: number, data?: Record<string, unknown>): string;
completed(data?: Record<string, unknown>): string;
failed(data?: Record<string, unknown>): string;
getConfiguration(): Promise<GameConfiguration>;
setPreferences(preferences: {
muted?: boolean;
reducedMotion?: boolean;
}): Promise<{ muted?: boolean; reducedMotion?: boolean }>;
requestPurchase(
productId: string,
): Promise<{ orderId: string; status: string }>;
onAcknowledgement(callback: (ack: GameAcknowledgement) => void): () => void;
onReceipt(callback: (receipt: GameRewardReceipt) => void): () => void;
}Event methods
send and event are aliases. started/paused/resumed/completed/failed are named shortcuts. progress(value,data) adds progress:value and score(value,data) adds score:value, overriding a same-named property in data. All event methods return a UUID synchronously; none returns an acceptance Promise. For custom registered names use event(name,data).
Configuration and preferences
getConfiguration resolves the current launcher configuration. setPreferences accepts optional boolean muted/reducedMotion and persists through the parent; account writes can fail. Listen for promise rejection. This is a preference store, not a general game save.
Acknowledgements and receipts
onAcknowledgement and onReceipt return unsubscribe functions. Attach before reporting. Accepted acknowledgement status is currently event_accepted for guests or reward_pending for signed-in players, with accepted:true, duplicate and rewardsPending. A duplicate may return only accepted:true and duplicate:true. Rejection includes accepted:false, status:'rejected', error. The TypeScript status union is narrower than the actual accepted status strings; check accepted rather than assuming status:'accepted'. The request helper times out after 120 seconds; it rejects when the parent returns an error. Event sends have no built-in acknowledgement timeout or retry. The example helper adds a 15-second acknowledgement deadline and stops after failure. Receipt data is open-ended; display server decisions rather than manufacturing a balance.
Conditional methods
loadSave/saveGame/exit/openLeaderboard exist in the SDK but are currently allowlisted by game slug. New games receive an error. requestPurchase opens parent confirmation only for an available published product matching the game or global catalog; it does not bypass sign-in, price, ownership or payment policy. See feature availability.