Integration guide — React Native

End-to-end walkthrough: from getting your API key to a live multiplayer game in your React Native (Expo or bare) app.

Setup Board components Game hooks EventBus & hooks

Get your API key

Register at beta-gamer.com/register. You'll receive a live key (bg_live_…) and a test key (bg_test_…). Use the test key during development.

🔒 Never bundle your API key in the app. Session creation must happen on your backend.

Install the SDK

npm install @beta-gamer/react-native socket.io-client

Expo only:

npx expo install expo-modules-core

React Native's JS runtime does not have atob — the SDK handles base64 decoding internally, no polyfill needed.

Create a session (your backend)

Call POST /v1/sessions from your server and return the sessionToken to the app. Never call this from the device.

const res = await fetch('https://api.beta-gamer.com/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer bg_live_xxxx',
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    game:      'chess',
    matchType: 'matchmaking',
    players:   [{ id: user.id, displayName: user.name }],
  }),
});
const { sessionToken, sessionId } = await res.json();

Fetch the token in your app

const startGame = async () => {
  const res = await fetch('https://your-api.com/game/start', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${userAuthToken}` },
  });
  const { sessionToken, sessionId } = await res.json();
  navigation.navigate('Game', { sessionToken, sessionId });
};

Wrap your game screen in BetaGamerProvider

Pass the token to BetaGamerProvider. It decodes the JWT and exposes all hooks to children.

import { BetaGamerProvider, ChessBoard } from '@beta-gamer/react-native';

export default function GameScreen({ route }) {
  const { sessionToken } = route.params;
  return (
    <BetaGamerProvider token={sessionToken} serverUrl="https://api.beta-gamer.com" connectSocket={false}>
      <ChessBoard layout="default" onLeave={() => navigation.goBack()} />
    </BetaGamerProvider>
  );
}

Prop	Default	Description
token	required	Session token from your backend
serverUrl	'https://api.beta-gamer.com'	Your Beta Gamer server URL
socketPath	'/socket.io'	Socket.IO path — change if self-hosting
connectSocket	true	Set `false` when using board components or game hooks — they manage their own socket and register it back into the provider

Validate the token on mount

Tokens are single-use. Validate before rendering the provider so navigating back to a finished game shows the result instead of re-entering matchmaking.

export default function GameScreen({ route }) {
  const { sessionToken } = route.params;
  const [status, setStatus] = useState<'checking' | 'ok' | 'ended'>('checking');

  useEffect(() => {
    fetch(`https://api.beta-gamer.com/v1/sessions/validate?token=${sessionToken}`)
      .then(r => r.json())
      .then(d => setStatus(d.status === 'ended' ? 'ended' : 'ok'))
      .catch(() => setStatus('ok'));
  }, [sessionToken]);

  if (status === 'checking') return <ActivityIndicator />;
  if (status === 'ended')    return <Text>This session has already ended.</Text>;

  return (
    <BetaGamerProvider token={sessionToken} serverUrl="https://api.beta-gamer.com" connectSocket={false}>
      <ChessBoard layout="default" onLeave={() => navigation.goBack()} />
    </BetaGamerProvider>
  );
}

Receive webhooks (optional)

When a game ends, Beta Gamer POSTs a signed payload to your webhookUrl. Set it in your dashboard or via PATCH /api/settings.

app.post('/webhooks/beta-gamer', (req, res) => {
  const { event, sessionId, winner, reason } = req.body;
  // event: 'game.ended'
  res.sendStatus(200);
});

✅ Setup done. Continue with Board components, Game hooks, or EventBus & hooks.

Beta Gamer GaaS API — questions? support@beta-gamer.com