play.fun SDK

play.fun is the fastest way to launch, distribute, and monetize games - without middlemen.

The play.fun SDK provides a simple interface for frontend developers to integrate authentication, points management, and rewards functionality into their games. It supports built-in authentication (via Privy).

Before using the SDK, see Game Developer Onboarding

For advanced integrations, see API Endpoints

---

Quickstart

For the most basic integration, you only need to do the following steps:

1. Install SDK

2. Create an SDK Instance

3. Call init() with your game Id

4. Call addPoints() during gameplay to track points

5. Call endGame() after a round of game play

With this setup, all play.fun related UI will be handled automatically. Seamless and simple!

---

Example Integrations

• Simple React Example

• Hybrid Integration (Client + Server SDK) — for games with a backend that need server-authoritative point saving

---

Installation

To use the play.fun SDK in your project, you can choose one of the following methods:

Via Script Tag

Include the following script tag in your HTML file:

<script src="https://sdk.play.fun"></script>

Once the script is loaded, the SDK becomes available as a global variable OpenGameSDK

Via NPM

The SDK is also available as an NPM package. Install it using:

npm install @playdotfun/game-sdk

Then, import it in your JavaScript code:

import OpenGameSDK from '@playdotfun/game-sdk';

After installation, create an instance of the SDK as detailed in the Initialization section.

Before initializing the SDK, ensure that your index.html file's header includes:

<meta name="x-ogp-key" content="dev-api-key" />

---

Initialization

After installing the SDK, you need to create an instance and initialize it with your game's configuration. This section covers the steps to set up the SDK for use.

Creating an SDK Instance

Create a new instance of the SDK with optional configuration options for UI customization.

const ogp = new OpenGameSDK({ ui: { usePointsWidget: true } });

Parameters

Parameter	Type	Default	Description
ui.theme	'light' | 'dark' | 'system'	'system'	Sets a light, dark, or system theme for the default UI
ui.usePointsWidget	boolean	true	Show floating points widget
ui.useCustomUI	boolean	false	Disable all automatic modals/widgets; control UI entirely yourself
logLevel	string	undefined	Logging level passed to the widget

Log Levels

Value	Description
'debug'	Most detailed logging
'info'	Standard information logging
'warn'	Warning messages only
'error'	Error messages only

interface SDKOpts {
  apiKey?: string; // Auto-read from <meta name="x-ogp-key">, or pass explicitly
  gameId?: string; // Can also be passed to init()
  ui?: {
    theme?: 'dark' | 'light' | 'system';
    usePointsWidget?: boolean;
    useCustomUI?: boolean;
  };
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
  baseUrl?: string; // Override API base URL (e.g., for dev environment)
}

init

Initialize the SDK with your game's unique identifier.

ogp.init({ gameId: 'your-game-id' });

Parameters:

• gameId (string, optional) – Your game's ID from the play.fun Dashboard. Can also be set via the constructor or URL query params.

Returns:

• Promise<void>

---

Authentication

The SDK supports authentication via a built-in login interface (powered by Privy).

Built-in Login

Trigger the SDK's default login UI.

ogp.login();

This opens the Privy login modal via the widget.

Login is automatically displayed and handled by the SDK widget. When endGame() is called without an active session, the SDK will automatically prompt the user to log in first, then save their points. In most cases you do not need to call login() manually.

---

Points

Manage player points with methods to save and retrieve them.

addPoints

Adds points to the current session. Points are accumulated locally and flushed to the server incrementally using the flush protocol. These points are displayed in the points widget but are not finalized until endGame() is called.

ogp.addPoints(10);

Parameters:

• points (number, required) – The number of points to add to the session.

Returns:

• Promise<void>

endGame

Ends the current game round and commits all points accumulated via addPoints(). savePoints() is an alias for endGame().

await ogp.endGame();

This method opens a gameplay-blocking modal. It displays a loading screen while saving, then shows either a success screen (with a points boost prompt) or an error screen. Do not call this during active gameplay — only call it when the game round/session has ended.

endGame() takes no parameters. Points must be accumulated via addPoints() before calling. If no points have been added, an error is thrown.

Parameters:

• None — saves all points accumulated via addPoints()

Returns:

• Promise<void>

If the user is not logged in, the SDK will automatically trigger the login modal first, then save points after authentication completes.

Rate limited to once every 5 seconds.

For hybrid integrations (games with a backend), do NOT call endGame() on the client. Instead, save points via the server SDK and call refreshPointsAndMultiplier() to sync the widget. See Hybrid Integration.

savePoints

Alias for endGame(). See above for full documentation.

await ogp.savePoints();

getPoints

Retrieves the player's current points for today.

const { points, activeMultiplier } = await ogp.getPoints();
console.log('Total points:', points);
console.log('Active multiplier:', activeMultiplier);

Parameters:

• None

Returns:

• Promise<{ points: string; activeMultiplier: number }> – Today's points as a string, and the player's active multiplier.

---

sessionToken

Returns the current Play.fun session token for the authenticated player. Use this to send to your backend for server-side validation via the server SDK.

const token = ogp.sessionToken; // "player_xxx..." or undefined

Returns:

• string | undefined – The session token (player_xxx format), or undefined if no active session. Token is scoped to the current game and expires after 30 minutes.

See the Hybrid Integration guide for a full walkthrough of using sessionToken with the server SDK.

---

Points Widget

refreshPointsAndMultiplier

Fetches the latest points and multiplier from the play.fun API and updates the widget display. This is the recommended method for hybrid integrations — call it after your server saves points via the server SDK to sync the widget with the server's actual data.

Does NOT open any modal or blocking UI — safe to call at any time.

await ogp.refreshPointsAndMultiplier();

Parameters:

• None

Returns:

• Promise<void>

The widget has no way of knowing when your server saves points. Without this call, displayed points will be stale until the next page refresh. See Hybrid Integration for the full flow.

refreshWidget

Alias for refreshPointsAndMultiplier(). Fetches the latest points from the play.fun API and updates the widget display.

await ogp.refreshWidget();

Parameters:

• None

Returns:

• Promise<void>

showPoints

Shows the points widget.

ogp.showPoints();

Parameters:

• None

hidePoints

Hides the points widget.

ogp.hidePoints();

Parameters:

• None

setTheme

Change the widget theme at runtime.

ogp.setTheme('dark');

Parameters:

• theme ('dark' | 'light' | 'system') – The theme to apply.

---

Rewards

Manage player rewards with methods for listing and claiming.

The reward functions only need to be called when providing a custom UI. You can opt in to automatic default UI during Initialization.

listUserRewards

Fetches the player's available rewards, grouped by game.

const rewards = await ogp.listUserRewards();
console.log('Rewards:', rewards);

Parameters:

• None

Returns:

• Promise<ListUserRewardsResponse> – Rewards data grouped by game, with token breakdown.

claimRewards

Attempts to claim available rewards for the player at the specified token addresses.

await ogp.claimRewards(['token-address-1', 'token-address-2']);

Parameters:

• addresses (string[], required) – Array of token mint addresses to claim rewards for.

Returns:

• Promise<ClaimRewardsResponse> – Map of gameId:tokenAddress to transaction signatures.

---

Event Callbacks

Handle SDK events with individual listeners or a catch-all approach.

ogp.onAll((eventName, data) => {
  console.log(`Event: ${eventName}`, data);
});

onAll

Capture all SDK events with a single listener.

Parameters:

• callback (function) – Receives the event name and optional data object.

Specific Events

Handle specific events as needed:

• OnReady: Fired when the SDK is initialized.

ogp.on('OnReady', () => {
  console.log('SDK ready');
});

• SessionStarted: Fired when a session begins.

ogp.on('SessionStarted', () => {
  console.log('Session started');
});

• LoginSuccess: Fired after successful login.

ogp.on('LoginSuccess', () => {
  console.log('Login successful');
});

Full Event List:

• 'OnReady': SDK initialized.

• 'SessionStarted': Session established.

• 'SessionEnded': Session ended.

• 'LoginRequest': Login process starts.

• 'LoginCancelled': Login canceled.

• 'LoginSuccess': Login succeeds.

• 'LoginFailed': Authentication fails.

• 'Logout': User logs out.

• 'SavePointsSuccess': Points saved successfully.

• 'SavePointsCancelled': Save points canceled.

• 'SavePointsFailed': Points save fails.

• 'ClaimRequest': Claim request sent.

• 'ClaimSuccess': Claim transaction succeeds.

• 'ClaimFailed': Claim fails.

• 'ClaimCancelled': Claim transaction not signed.

Unsubscribing from Events

To unsubscribe from a specific event, use ogp.off(eventName, callback). To unsubscribe from all events captured by onAll, use ogp.off('*', callback)

const onReadyCallback = () => console.log('SDK ready');
ogp.on('OnReady', onReadyCallback);
// Later
ogp.off('OnReady', onReadyCallback);

---

Demos

Our public demo GitHub is at https://github.com/playdotfun/ogp-demos

Simple Game Demo (simple-game/)

This demo shows how to:

• Initialize and configure the play.fun SDK

• Track player points in real-time using addPoints()

• Save final scores using endGame()

• Handle SDK events (OnReady, SessionStarted)

Claim Creator Rewards Demo (claim-creator-rewards/)

This demo shows how to:

• Claim creator rewards using claimRewards()

• Handle async SDK operations with proper error handling

• Provide user feedback during claim operations

• Implement a simplified single-purpose SDK integration