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 have this token in their reward splits (Solana mint address)
tokenNetwork	string	Network of the token (currently only solana is supported)
userId	string	Filter games created or owned by a specific user/creator ID (UUID)
dpgid	string	Deep link to a specific game by ID (shows it first in the feed). Alias: targetGameId
gameRef	string	Referrer's Privy ID or OGP ID for referral tracking. Can also be set via postMessage
gameId	string	Game ID to associate with the referral (used with gameRef)
distributorKeys	string or JSON	Solana public key (string) or JSON object (e.g., {"solana": "pubKey"}) for reward distribution. Can also be set via postMessage
target	string	Special embed target (e.g., ledger for Ledger Live integration)

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?dpgid=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 can also be set via URL parameters (gameRef, gameId, distributorKeys), but postMessage is preferred for sensitive data as it's not visible in the URL. Both methods are supported and the carousel will merge data from both sources.

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 dpgid 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 (dpgid or 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 (when no nextToken cursor is provided)

No Filters

• Returns all available HTML games

• Sorted by reward pool value (highest first)

• Paginated with 20 games per page (configurable)