AI Integration Guide

A simple guide for integrating the OpenGameSDK into HTML/JavaScript games. Get your game connected to OGP in minutes!

After login, ogp.playerId is the player's Privy ID. Use it as the canonical user key in your game/backend.

🚀 Quick Start - It's This Easy

// 1. Initialize
const ogp = new OpenGameSDK({ ui: { usePointsWidget: true } });
ogp.init({ gameId: 'YOUR_GAME_ID' });

// 2. Add points during gameplay (display only)
ogp.addPoints(10);

// 3. Save when game ends - auto-logs in if needed!
await ogp.savePoints(totalScore);

That's it! The SDK handles authentication automatically when you call savePoints().

💡 Key Concepts

Feature

What It Does

Auto-Login

savePoints() automatically prompts login if user isn't authenticated

Points Widget

Built-in UI shows player's points - no extra work needed

Privy Auth

Secure authentication handled by SDK

One Save Per Session

Call savePoints() once when game ends

1) Install

Add two lines to your HTML <head>:

<meta name="x-ogp-key" content="YOUR_API_KEY" />
<script src="https://cdn.opengameprotocol.com/opengame-sdk-latest.min.js"></script>

2) Initialize

const ogp = new OpenGameSDK({
  ui: { usePointsWidget: true, theme: 'dark' },
  logLevel: 1, // 0 none, 1 errors, 2 warnings, 3 info
});

ogp.on('OnReady', () => {
  console.log('SDK ready - start your game!');
  startGame();
});

ogp.on('LoginSuccess', () => {
  console.log('Logged in as:', ogp.playerId);
});

ogp.init({ gameId: 'YOUR_GAME_ID' });

Simple Rules:

Create one SDK instance per page
Register event handlers before calling init
Wait for OnReady before enabling gameplay

You don't need to handle login manually! When you call savePoints(), the SDK automatically prompts the user to log in if they aren't already authenticated.

// Just call savePoints when the game ends
// SDK handles login automatically if needed!
await ogp.savePoints(score);

This means you can:

Let players start playing immediately
Only prompt for login when they want to save progress
Keep your code simple

If you prefer to prompt login earlier (e.g., for multiplayer features):

ogp.login(); // Opens login modal
ogp.logout(); // Clears session

After login, ogp.playerId contains the user's Privy ID - use this as their unique identifier.

4) Scoring & Saving

The Simple Pattern

// During gameplay - show points accumulating (display only)
ogp.addPoints(10);

// When game ends - save and trigger auto-login if needed
await ogp.savePoints(totalScore);

Best Practice: Save Only Improvements

To prevent duplicate rewards, only save the difference when players beat their best:

let bestScore = 0;
let currentScore = 0;

// On game start, get player's best score
async function initBestScore() {
  const points = await ogp.getPoints();
  bestScore = points?.points ? Number(points.points) : 0;
}

// During gameplay
function updateScore(newScore) {
  currentScore = Math.max(currentScore, newScore);
  if (currentScore > bestScore) {
    ogp.addPoints(currentScore - bestScore); // Display only
  }
}

// When game ends
async function handleGameEnd() {
  if (currentScore > bestScore) {
    const improvement = currentScore - bestScore;
    await ogp.savePoints(improvement); // Save difference only
    bestScore = currentScore;
  }
  currentScore = 0; // Reset for next run
}

Game Type Examples

// PLATFORMER - Height/distance based (higher is better)
currentScore = Math.max(currentScore, distance);

// RACING - Time based (lower is better)
if (time < bestScore || bestScore === 0) currentScore = time;

// SHOOTER - Points accumulated
currentScore = Math.max(currentScore, points);

Key Rules:

addPoints() for display during gameplay
savePoints() once when session ends
Save improvements, not absolute scores

5) Rewards & Claims

// Show rewards and claim flow
await ogp.claimRewards(true);

// Get player's rewards
const rewards = await ogp.listPlayerRewards();

// Check time until next claim
const seconds = await ogp.getTimeUntilNextClaim();

6) UI Helpers

ogp.ui.showPoints();
ogp.ui.hidePoints();
ogp.ui.setTheme('dark'); // or 'light'

7) Events

// Core lifecycle
ogp.on('OnReady', () => {
  /* SDK ready */
});
ogp.on('SessionStarted', () => {
  /* session active */
});

// Authentication
ogp.on('LoginSuccess', () => {
  /* ogp.playerId now available */
});
ogp.on('LoginFailed', () => {
  /* show error */
});
ogp.on('Logout', () => {
  /* clear player state */
});

// Points
ogp.on('SavePointsSuccess', () => {
  /* saved successfully */
});
ogp.on('SavePointsFailed', () => {
  /* show retry option */
});

// Claims
ogp.on('ClaimSuccess', () => {
  /* claim succeeded */
});
ogp.on('ClaimFailure', () => {
  /* claim failed */
});

8) Complete Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="x-ogp-key" content="YOUR_API_KEY" />
    <script src="https://cdn.opengameprotocol.com/opengame-sdk-latest.min.js"></script>
  </head>
  <body>
    <div id="score">0</div>
    <button id="add" disabled>+10 Points</button>
    <button id="end" disabled>End Game</button>

    <script>
      let score = 0;
      const ogp = new OpenGameSDK({ ui: { usePointsWidget: true } });

      ogp.on('OnReady', () => {
        document.getElementById('add').disabled = false;
        document.getElementById('end').disabled = false;
      });

      ogp.init({ gameId: 'YOUR_GAME_ID' });

      document.getElementById('add').onclick = () => {
        score += 10;
        document.getElementById('score').textContent = score;
        ogp.addPoints(10);
      };

      document.getElementById('end').onclick = async () => {
        // Auto-logs in if needed, then saves
        await ogp.savePoints(score);
        alert('Saved!');
      };
    </script>
  </body>
</html>

9) Integration Checklist

Add <meta name="x-ogp-key"> with your API key
Include the SDK script from CDN
Create one OpenGameSDK instance
Register events before init
Wait for OnReady before gameplay
Use addPoints() during gameplay
Use savePoints() once at game end (auto-login handles auth!)
Handle save failures with retry option

API Reference

Methods

Method

Description

init({ gameId })

Initialize SDK with your game ID

addPoints(amount)

Update points display during gameplay

savePoints(score)

Save score to server (auto-login if needed)

getPoints()

Get player's current points

claimRewards(showModal?)

Open claim rewards flow

listPlayerRewards()

Fetch player's available rewards

getTimeUntilNextClaim()

Seconds until next claim available

login()

Manually trigger login modal

logout()

Clear user session

showError({ title, message })

Display error modal to user

UI Namespace

Method

Description

ui.showPoints()

Show the points widget

ui.hidePoints()

Hide the points widget

ui.setTheme(theme)

Set "light" or "dark" theme

Events

Event

When Fired

OnReady

SDK initialized and ready

SessionStarted

Player session established

SessionFailed

Session failed (API error, missing params)

LoginRequest

LoginSuccess

User successfully logged in

LoginFailed

LoginCancelled

User closed login modal

Logout

User logged out

SavePointsSuccess

Points saved to server

SavePointsFailed

Failed to save points

SavePointsCancelled

User cancelled save

ClaimRequest

Claim transaction requested

ClaimSuccess

Claim transaction sent

ClaimFailure

Claim failed

ClaimCancelled

User cancelled claim

Constructor Options

new OpenGameSDK({
  ui: {
    usePointsWidget: true, // Show built-in points display
    theme: 'dark', // "light" or "dark"
    gameIcon: 'url', // Optional custom game icon
  },
  logLevel: 1, // 0=none, 1=errors, 2=warnings, 3=info
});

That's everything you need! The SDK handles the complexity—you just call savePoints() and let auto-login do its thing. 🎮

PreviousCarousel Integration

Last updated 3 days ago