Carousel Integration

The OpenGame Protocol Carousel is a vertical scrolling game feed that displays play-to-earn games with reward information. Partners can embed the carousel to showcase games filtered by tokens, users, or display all available games.

Live Deployments

• Production: https://carousel.opengameprotocol.com

Basic Integration

Simple Embed (All Games)

Embed the carousel to show all available games:

<iframe 
  src="https://carousel.opengameprotocol.com"
  width="100%"
  height="100%"
  style="border: none; min-height: 600px;"
  allow="accelerometer; autoplay; camera; clipboard-write; encrypted-media; fullscreen; geolocation; gyroscope; microphone; payment; picture-in-picture; pointer-lock"
></iframe>

URL Parameters

Customize the carousel behavior using URL query parameters:

Supported Parameters

Parameter	Type	Description
tokenAddress	string	Filter games that reward a specific token (Solana address)
tokenNetwork	string	Network of the token (e.g., solana)
userId	string	Filter games created or owned by a specific user/creator ID
targetGameId	string	Deep link to a specific game (shows it first in the feed)
gameRef	string	User's Privy ID or OGP ID for referral tracking. Referrers receive a portion of active players' points
distributorKeys	string or object	Solana public key (string) or network mapping object (e.g., {solana: "pubKey"}) for reward distribution. Distributors receive a portion of creator rewards

Integration Examples

1. Token-Filtered Carousel

Show only games that reward a specific token. Perfect for token communities wanting to showcase their gaming ecosystem.

<!-- Filter by token address -->
<iframe 
  src="https://carousel.opengameprotocol.com?tokenAddress=X7K5SC5kiPiMc2BHD7pyu1v18L1sWCnxk8KTVUYgame&tokenNetwork=solana"
  width="100%"
  height="100%"
  style="border: none;"
  allow="accelerometer; autoplay; camera; clipboard-write; encrypted-media; fullscreen; geolocation; gyroscope; microphone; payment"
></iframe>

Use Cases:

• Token community websites showcasing games in their ecosystem

• DEX listings showing games that reward specific tokens

• Token dashboards displaying gaming opportunities

API Response includes:

• token object with token metadata (image, symbol)

• Games sorted by reward pool value for that token

• Top 3 rewarded tokens per game

• Total allocated rewards in USD

2. User-Specific Carousel

Display games created or owned by a specific user. Ideal for game developer portfolios or studio showcases.

<!-- Filter by user/creator ID -->
<iframe 
  src="https://carousel.opengameprotocol.com?userId=be44c6b5-b3b4-45bd-ba04-025f4111af4f"
  width="100%"
  height="100%"
  style="border: none;"
  allow="accelerometer; autoplay; camera; clipboard-write; encrypted-media; fullscreen; geolocation; gyroscope; microphone; payment"
></iframe>

Use Cases:

• Game developer portfolio pages

• Studio showcases

• Publisher catalogs

3. Deep Link to Specific Game

Open the carousel with a specific game displayed first. Great for marketing campaigns or direct game links.

<!-- Deep link to a specific game -->
<iframe 
  src="https://carousel.opengameprotocol.com?targetGameId=dca7c105-2d37-4dc7-95df-fd22e727b72c"
  width="100%"
  height="100%"
  style="border: none;"
  allow="accelerometer; autoplay; camera; clipboard-write; encrypted-media; fullscreen; geolocation; gyroscope; microphone; payment"
></iframe>

Behavior:

• Specified game appears first in the feed

• User can scroll to discover more games

• If game not in current results, it's fetched and added to the top

Use Cases:

• Marketing campaigns for specific games

• Social media sharing

• Email campaigns

• Direct game promotion

4. Combined Filters

Combine parameters for specific use cases:

<!-- Show games by a user that reward a specific token -->
<iframe 
  src="https://carousel.opengameprotocol.com?userId=abc123&tokenAddress=X7K5SC5kiPiMc2BHD7pyu1v18L1sWCnxk8KTVUYgame&tokenNetwork=solana"
  width="100%"
  height="100%"
  style="border: none;"
  allow="accelerometer; autoplay; camera; clipboard-write; encrypted-media; fullscreen; geolocation; gyroscope; microphone; payment"
></iframe>

API Response Structure

When you filter by token or specify parameters, the carousel API returns:

{
  "items": [
    {
      "id": "game-uuid",
      "name": "Game Name",
      "description": "Game description",
      "imageUrl": "https://cdn.opengameprotocol.com/...",
      "coverImage": "https://cdn.opengameprotocol.com/...",
      "gameUrl": "https://game-url.com",
      "isHTMLGame": true,
      "iframable": true,
      "creatorId": "creator-uuid",
      "ownerId": "owner-uuid",
      "hasSDK": false,
      "rewardPoolValueUsd": "119.56",
      "totalRewardsAllocatedUsd": "0.64",
      "rewardStatus": "with-rewards",
      "tokens": [
        {
          "address": "token-address",
          "symbol": "SYMBOL",
          "name": "Token Name",
          "imageUrl": "https://cdn.opengameprotocol.com/...",
          "totalAllocatedUsd": "99.66"
        }
      ],
      "topRewardedToken": {
        "address": "token-address",
        "symbol": "SYMBOL",
        "name": "Token Name",
        "imageUrl": "https://cdn.opengameprotocol.com/...",
        "totalAllocatedUsd": "99.66"
      }
    }
  ],
  "total": 158,
  "nextToken": "MjA=",
  "targetGame": { /* if targetGameId was specified */ },
  "token": { /* if tokenAddress was specified */
    "image": "https://cdn.opengameprotocol.com/...",
    "symbol": "SYMBOL"
  }
}

Advanced Integration

PostMessage Communication

The carousel communicates with parent windows via postMessage for advanced integrations.

Messages FROM Carousel

// Listen for game navigation updates
window.addEventListener('message', (event) => {
  if (event.data.type === 'GAME_ID_UPDATE') {
    const gameId = event.data.gameId;
    console.log('User navigated to:', gameId);
    // Update your UI, analytics, etc.
  }
});

Messages TO Carousel

Partners can inject their own referral and distributor data into games through the carousel using postMessage. These settings apply to all games played through the carousel and are passed to each game via the OpenGame SDK.

Note: These cannot be set via URL parameters - they must be injected via postMessage after the carousel iframe loads. This is a security feature to prevent URL tampering.

1. Referral Data (Revenue Sharing)

Partners can inject their own referral ID to earn revenue attribution from games played through their carousel:

const iframe = document.getElementById('carousel');

// Send once after iframe loads
iframe.addEventListener('load', () => {
  iframe.contentWindow.postMessage({
    type: 'REFERRAL_DATA',
    data: {
      referredGameId: 'game-uuid',  // Optional: specific game being referred
      gameReferrer: 'your-partner-id'  // Your partner/affiliate ID
    }
  }, '*');
});

How it works:

• The carousel stores your referral data in localStorage

• When a game initializes, the carousel's SDK Bridge passes this data to the game

• Games track which partner referred the player via the OpenGame SDK

• Revenue share is attributed to your partner ID

• Applies to all games played through this carousel instance

Use cases:

• Affiliate programs and revenue sharing agreements

• Partner attribution tracking

• Marketing campaign tracking

• Platform monetization

2. Distributor Keys (Reward Distribution Fees)

YES! Partners can inject their own Solana wallet address to receive a share of rewards distributed through games:

const iframe = document.getElementById('carousel');

iframe.addEventListener('load', () => {
  iframe.contentWindow.postMessage({
    type: 'DISTRIBUTOR_KEYS',
    data: {
      solana: 'YourBase58EncodedSolanaPublicKey'
    }
  }, '*');
});

How it works:

• The carousel stores your distributor key in localStorage

• When a game initializes, the carousel's SDK Bridge passes this key to the game via the OpenGame SDK

• When games distribute rewards (via SDK methods), your wallet receives a distribution fee

• Each game implements its own distribution fee structure

• Typically 1-5% of rewards go to the distributor wallet

Use cases:

• Platform operators taking a distribution fee on all games

• Token communities incentivizing game distribution

• Marketing partners earning from reward flows

• Gaming platforms monetizing game embeds

Important notes:

• Distributor keys must be valid Solana public keys (base58 encoded)

• Games must use the OpenGame SDK for reward distribution for this to work

• Distribution fees are implemented at the game level (check with game developers)

• Some games may not support distributor fees

• The carousel stores these keys and the SDK Bridge passes them to each game that launches

• This is a game SDK feature, not a carousel-specific feature

Responsive Design

The carousel is optimized for mobile and desktop viewing:

<div style="width: 100%; max-width: 600px; margin: 0 auto;">
  <iframe 
    src="https://carousel.opengameprotocol.com?tokenAddress=YOUR_TOKEN"
    width="100%"
    height="100vh"
    style="border: none;"
    allow="accelerometer; autoplay; camera; clipboard-write; encrypted-media; fullscreen; geolocation; gyroscope; microphone; payment"
  ></iframe>
</div>

Recommended dimensions:

• Mobile: 100% width, 100vh height

• Desktop: 600px max-width, centered

• Minimum height: 600px

Features

For Users

• Vertical scrolling: Swipe up/down to browse games (TikTok-style)

• Game preview: See game cover, description, and reward information

• Play instantly: Click "Play" to launch games directly

• Reward information: View reward pools, top tokens, and allocated rewards

• Wallet integration: Connect wallet via Privy for claiming rewards

For Partners

• White-label ready: Embed with your own context

• Token filtering: Show games specific to your token ecosystem

• User filtering: Display games from specific creators

• Deep linking: Direct users to specific games

• Analytics: Track game navigation via postMessage events

• Authentication: Pass authentication tokens for seamless user experience

• Referral injection: Inject your partner ID for revenue attribution

• Distributor fees: Set your wallet to receive distribution fees from game rewards

Best Practices

1. Always specify tokenNetwork when using tokenAddress (currently only solana is supported)

2. Set appropriate iframe dimensions for your use case (mobile vs desktop)

3. Include all required allow permissions for proper game functionality

4. Use targetGameId for marketing campaigns to feature specific games

5. Monitor GAME_ID_UPDATE messages to track user engagement

6. Test on mobile devices as the carousel is optimized for touch interactions

Example: Token Community Integration

Here's a complete example for a token community website:

<!DOCTYPE html>
<html>
<head>
  <title>Play & Earn $MYTOKEN</title>
  <style>
    body {
      margin: 0;
      padding: 0;
      font-family: system-ui;
    }
    .container {
      max-width: 600px;
      margin: 0 auto;
      background: #000;
    }
    .header {
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
      padding: 20px;
      text-align: center;
    }
  </style>
</head>
<body>
  <div class="container">
    <div class="header">
      <h1>🎮 Play & Earn $MYTOKEN</h1>
      <p>Discover games that reward you with $MYTOKEN</p>
    </div>
    <iframe 
      id="carousel"
      src="https://carousel.opengameprotocol.com?tokenAddress=YOUR_TOKEN_ADDRESS&tokenNetwork=solana"
      width="100%"
      height="calc(100vh - 120px)"
      style="border: none; display: block;"
      allow="accelerometer; autoplay; camera; clipboard-write; encrypted-media; fullscreen; geolocation; gyroscope; microphone; payment"
    ></iframe>
  </div>

  <script>
    const carousel = document.getElementById('carousel');

    // Inject your referral and distributor data after carousel loads
    carousel.addEventListener('load', () => {
      // Set your referral ID for revenue attribution
      carousel.contentWindow.postMessage({
        type: 'REFERRAL_DATA',
        data: {
          gameReferrer: 'your-partner-id'  // Replace with your partner ID
        }
      }, '*');

      // Set your distributor wallet to receive reward distribution fees
      carousel.contentWindow.postMessage({
        type: 'DISTRIBUTOR_KEYS',
        data: {
          solana: 'YourSolanaPublicKeyHere'  // Replace with your Solana public key
        }
      }, '*');
    });

    // Track which games users are viewing
    window.addEventListener('message', (event) => {
      if (event.data.type === 'GAME_ID_UPDATE') {
        console.log('User viewing game:', event.data.gameId);
        // Send to your analytics
      }
    });
  </script>
</body>
</html>

Filtering Behavior

Token Filter (tokenAddress + tokenNetwork)

• Shows only games that reward the specified token

• Games are sorted by total reward pool value (highest first)

• Returns token metadata in response (image, symbol)

• Each game shows top 3 tokens it rewards

• If no games reward the token, returns empty array

User Filter (userId)

• Shows games where the user is the creator OR owner

• Useful for portfolio or studio pages

• Games still sorted by reward pool value

• Can be combined with token filter

Target Game (targetGameId)

• Fetches specified game and places it first in the feed

• If game matches other filters, it's moved to top

• If game doesn't match filters, it's still added to top

• Remaining games follow normal filtering/sorting

• Only applied on first page load (offset = 0)

No Filters

• Returns all available HTML games

• Sorted by reward pool value (highest first)

• Paginated with 20 games per page (configurable)