Browser SDK

The @subgames/sdk package lets you add tier-gating, login, subscribe prompts, and a social overlay to your browser game.

Installation

npm install @subgames/sdk

Or include via CDN:

<script src="https://cdn.sub.games/sdk/latest/index.js"></script>

When loaded via CDN, the SDK is available as SubGames.SubGamesSDK on the global window object.

Quick Start

With npm / bundler:

import { SubGamesSDK } from '@subgames/sdk';

const sdk = SubGamesSDK.init({
  gameKey: 'your-game-key',
});

With CDN script tag:

const sdk = SubGames.SubGamesSDK.init({
  gameKey: 'your-game-key',
});

That's all you need for basic integration. The SDK will:

• Restore any existing player session from localStorage
• Start a 30-second timer that prompts unauthenticated players to subscribe
• Signal readiness to the sub.games platform (if embedded)

Configuration

interface SubGamesConfig {
  gameKey: string;    // Required. Your game's unique key from the dashboard.
  apiUrl?: string;    // API endpoint. Defaults to https://api.sub.games
  appUrl?: string;    // Platform URL. Defaults to https://sub.games
  overlay?: boolean;  // Enable the in-game social overlay (like, comment, share)
}

Game Key

Your game key is a unique identifier assigned to every game you create. The SDK uses it to look up your game's creator, subscription tiers, and access rules.

Where to find it:

1. When you create a game in the creator dashboard at sub.games/publish/games, the game key is displayed on the success screen with a copy button.
2. You can also find it on the game's settings page in the dashboard at any time.

The game key is a URL-friendly slug derived from your game name (e.g., my-platformer). It is permanent and cannot be changed after creation.

const sdk = SubGamesSDK.init({
  gameKey: 'my-platformer', // from the creator dashboard
});

Overlay

When overlay: true, the SDK adds a floating UI in the corner of your game with like, comment, re-game (share), save, and subscribe buttons. This is recommended for most games — it adds social features without any additional code.

const sdk = SubGamesSDK.init({
  gameKey: 'your-game-key',
  overlay: true,
});

The overlay is only shown when the game is not embedded on the sub.games platform (which provides its own UI).

Tier-Gating

The core feature of the SDK. Gate content behind subscription tiers.

Check Player Tier

const tier = await sdk.getPlayerTier();
// Returns: 'none' | 'free' | 'supporter' | 'founder'

The tier hierarchy (lowest to highest): none < free < supporter < founder.

Require a Tier

Use requireTier() to check access and automatically prompt the player if they don't meet the requirement:

const hasAccess = await sdk.requireTier('supporter', 'bonus levels');

if (hasAccess) {
  // Player is a Supporter or higher — unlock the content
  loadBonusLevels();
}
// If false, the SDK already showed a subscribe prompt and paused the game

requireTier() returns true if the player meets the tier. If they don't, it automatically:

1. Pauses the game (emits 'pause' event)
2. Opens a subscribe popup targeting the required tier
3. Unpauses when the popup closes (emits 'unpause' event)

The optional second argument is a feature label shown in the subscribe prompt (e.g., "bonus levels").

Authentication

Check Login Status

if (sdk.isLoggedIn()) {
  const player = await sdk.getPlayer();
  // { id, email, displayName, avatarUrl }
}

Prompt Login

Open a login popup for the player:

await sdk.promptLogin();
// Resolves when the player logs in or closes the popup
// Game is automatically paused while the popup is open

Prompt Subscribe

Open a subscribe popup:

await sdk.promptSubscribe('supporter', 'exclusive skins');
// Pauses the game, opens the subscribe popup
// Resolves when the player subscribes or closes the popup

Token Management

The SDK stores the player's auth token in localStorage under the key subgames_token. You generally don't need to interact with this directly, but if needed:

const token = sdk.getToken();  // Get current token
sdk.setToken(token);           // Set token (e.g., from external auth)
sdk.logout();                  // Clear session

Pause / Unpause

The SDK automatically pauses your game when opening modals (login, subscribe). Listen for pause events to freeze your game loop:

sdk.on('pause', () => {
  // Freeze game loop, mute audio, etc.
  game.pause();
});

sdk.on('unpause', () => {
  // Resume game loop
  game.resume();
});

You can also check or control pause state directly:

sdk.isPaused();  // true or false
sdk.pause();     // Manually pause
sdk.unpause();   // Manually unpause

30-Second Subscribe Prompt

The SDK includes a mandatory subscribe prompt that fires 30 seconds after initialization for unauthenticated players (tier = none). This is not configurable — it's a platform requirement to help convert players into subscribers.

If you call requireTier() before the 30-second mark, your prompt takes priority.

Full Example

import { SubGamesSDK } from '@subgames/sdk';

const sdk = SubGamesSDK.init({
  gameKey: 'my-platformer',
  overlay: true,
});

// Handle pause/unpause
sdk.on('pause', () => game.pause());
sdk.on('unpause', () => game.resume());

// React to tier changes (e.g., player just subscribed)
sdk.on('tierChange', (newTier) => {
  if (newTier === 'supporter' || newTier === 'founder') {
    unlockSupporterContent();
  }
});

// Gate a feature
async function tryBonusLevel() {
  const allowed = await sdk.requireTier('supporter', 'bonus levels');
  if (allowed) {
    startBonusLevel();
  }
}

API Reference