X Games SDK Integration Guide

The X Games SDK enables seamless integration between games and the X (formerly Twitter) platform. It provides a standardized way for games to share achievements, scores, and progress directly on X, fostering community engagement and competition.

Overview

The SDK is designed to enhance the gaming experience by:

Enabling one-click sharing of game achievements to X
Providing consistent branding and user experience across all integrated games
Supporting dynamic score/level updates during gameplay
Facilitating discovery of other games in the X Games ecosystem
Creating a bridge between X's social features and gaming achievements

Benefits of Integration

Increase game visibility through social sharing
Higher reach potential as X's algorithm favors posts that keep users on the platform
Players can try your game directly within X without leaving the platform
Foster competition between players
Build community around your game
Seamless integration with X's platform
Consistent sharing experience across all X Games

Getting Started

Integration requires just three simple steps:

Add social media meta tags for proper X card display
Include the share button in your game UI
Import the SDK script

1. Add Meta Tags (Server-Side)

These meta tags enable rich game previews when shared on X. They must be added server-side for social media crawlers to see them. The twitter:game URL will also be used in the share message.

<!-- Facebook Meta Tags -->
<meta property="og:url" content="https://[YOUR-DOMAIN]/[game-path]/" />
<meta property="og:type" content="website" />
<meta property="og:title" content="[Game Name]" />
<meta property="og:description" content="[Game Description]" />
<meta property="og:image" content="https://[YOUR-DOMAIN]/[game-path]/screenshot.webp" />

<!-- Twitter Meta Tags -->
<meta name="twitter:card" content="game" />
<meta name="twitter:site" content="@[YOUR-HANDLE]" />
<meta property="twitter:domain" content="[YOUR-DOMAIN]" />
<meta property="twitter:url" content="https://[YOUR-DOMAIN]/[game-path]/" />
<meta name="twitter:title" content="[Game Name]" />
<meta name="twitter:description" content="[Game Description]" />
<meta name="twitter:image" content="https://[YOUR-DOMAIN]/[game-path]/screenshot.webp" />
<meta name="twitter:game" content="https://[YOUR-DOMAIN]/[game-path]" />
<meta name="twitter:game:width" content="1024" />
<meta name="twitter:game:height" content="576" />
<meta name="twitter:game:type" content="mousekeyboard" />

The twitter:game:type meta tag specifies the control scheme:

mousekeyboard (default) - Game uses mouse and/or keyboard controls
touch - Game is optimized for touch input
multi - Game supports both touch and mouse/keyboard input

2. Add Share Button

Place the share button component where you want it to appear:

<div class="x-share" data-name="Your Game Name" data-score="0 points"></div>

Configuration Options

The share button supports these data attributes:

data-name: Your game's name (required)
data-url: Override the default share URL (defaults to twitter:game meta tag URL)
data-score: Initial achievement/score (defaults to "0")

Important: Always initialize data-score with a meaningful starting value that matches your game's scoring format. This ensures the share button shows the correct score before the first score update occurs.

Common placement examples:

<!-- Top-left corner -->
<div class="x-share" data-name="Game Name" data-score="0 points" style="position: absolute; left: 80px; top: 4px;"></div>

<!-- Next to score display -->
<div style="display: flex; align-items: center; gap: 10px;">
  <div id="score">Score: 0</div>
  <div class="x-share" data-name="Game Name" data-score="0 points"></div>
</div>

<!-- In game menu -->
<div class="menu">
  <h2>Game Menu</h2>
  <div class="x-share" data-name="Game Name" data-score="Level 1"></div>
  <button>Restart</button>
  <button>Settings</button>
</div>

3. Import SDK

Add the SDK script to your HTML file. The script will automatically:

Initialize when the DOM is ready
Handle dynamically added share buttons
Use the twitter:game URL for sharing (unless overridden by data-url)
Work with frameworks and dynamic content
Use clipboard API for sharing
Work without jQuery dependency

<script src="https://xg.benallfree.com/xgames.js"></script>

Updating Game Progress

Update the share content whenever the player's progress changes. The score format should match what makes sense for your game:

Use "points" suffix for arcade/action games
Use "Level X" prefix for progression-based games
Use "$" prefix for financial/economy games
Use appropriate units that give context (e.g. "waves", "kills", etc.)

// Include units in the score for clear context
XGames.updateScore('1000 points') // for points-based games
XGames.updateScore('Level 5') // for level-based games
XGames.updateScore('$5000') // for money-based games

// If you have multiple share buttons, specify which one:
XGames.updateScore('Level 5', '#specific-share-button')

Share Message Format

When players share their achievements, the SDK automatically formats the message. The URL used in the share message is taken from:

data-url attribute if specified
twitter:game meta tag if present
Falls back to current window location

I reached [score with units] on [GameName]. Install @xgamesproj to play right here on X and leave a comment with your high score [game-url]

Required Assets

screenshot.webp - Game screenshot for X Card preview (1024x576px recommended)

Example Implementation

Here's a complete example using the Astray game:

<!-- In your HTML template -->
<head>
  <!-- Facebook Meta Tags -->
  <meta property="og:url" content="https://[YOUR-DOMAIN]/astray/" />
  <meta property="og:type" content="website" />
  <meta property="og:title" content="Astray - 3D Maze Game" />
  <meta property="og:description" content="Navigate through an immersive 3D maze using arrow keys or vim controls. A challenging HTML5 game that tests your spatial awareness and reflexes." />
  <meta property="og:image" content="https://[YOUR-DOMAIN]/astray/screenshot.webp" />

  <!-- Twitter Meta Tags -->
  <meta name="twitter:card" content="game" />
  <meta name="twitter:site" content="@[YOUR-HANDLE]" />
  <meta property="twitter:domain" content="[YOUR-DOMAIN]" />
  <meta property="twitter:url" content="https://[YOUR-DOMAIN]/astray/" />
  <meta name="twitter:title" content="Astray - 3D Maze Game" />
  <meta name="twitter:description" content="Navigate through an immersive 3D maze using arrow keys or vim controls. A challenging HTML5 game that tests your spatial awareness and reflexes." />
  <meta name="twitter:image" content="https://[YOUR-DOMAIN]/astray/screenshot.webp" />
  <meta name="twitter:game" content="https://[YOUR-DOMAIN]/astray" />
  <meta name="twitter:game:width" content="1024" />
  <meta name="twitter:game:height" content="576" />
  <meta name="twitter:game:type" content="mousekeyboard" />

  <script src="https://[YOUR-DOMAIN]/xgames.js"></script>
</head>

<body>
  <!-- Position next to level display -->
  <div style="position: absolute; left: 0; top: 0; display: flex; align-items: center; gap: 10px;">
    <div id="level">Level 1</div>
    <div class="x-share" data-name="Astray" data-score="Level 1"></div>
  </div>

  <script>
    // Update score when level changes
    function updateLevel() {
      const level = Math.floor((mazeDimension - 1) / 2 - 4)
      XGames.updateScore(`Level ${level}`)
    }
  </script>
</body>

X GamesPlay the latest web games directly on X