How to add Apple Game Center leaderboards to an Expo app

#ios #mobile #reactnative #tutorial

I shipped my indie game Chromatch with Apple Game Center leaderboards earlier this week. My first submit got approved with the binary alone and my 6 leaderboards stayed "In Preparation" with no warning from Apple. It took a re-submit to find all the pieces that aren't obvious from the docs. Here's what ended up working, code included.

The native module

Expo doesn't ship any game center package, so you have to write a small local module with npx create-expo-module@latest --local. Here's the Swift side:

import ExpoModulesCore
import GameKit

public class ExpoGameCenterModule: Module {
  private var hasSetHandler = false

  public func definition() -> ModuleDefinition {
    Name("ExpoGameCenter")
    Events("onAuthStateChanged")

    Function("isAuthenticated") { () -> Bool in
      GKLocalPlayer.local.isAuthenticated
    }

    AsyncFunction("authenticate") { (promise: Promise) in
      if self.hasSetHandler {
        promise.resolve(GKLocalPlayer.local.isAuthenticated)
        return
      }
      self.hasSetHandler = true

      GKLocalPlayer.local.authenticateHandler = { [weak self] vc, err in
        guard let self = self else { return }
        if let vc = vc {
          DispatchQueue.main.async {
            self.rootViewController()?.present(vc, animated: true)
          }
          return
        }
        self.emitAuthState()
        promise.resolve(GKLocalPlayer.local.isAuthenticated)
      }
    }

    AsyncFunction("submitScore") { (score: Int, leaderboardID: String) in
      guard GKLocalPlayer.local.isAuthenticated else { return }
      try await GKLeaderboard.submitScore(
        score, context: 0,
        player: GKLocalPlayer.local,
        leaderboardIDs: [leaderboardID]
      )
    }

    AsyncFunction("showLeaderboards") { (leaderboardSetID: String) in
      guard GKLocalPlayer.local.isAuthenticated else { return }
      await MainActor.run {
        let gcVC: GKGameCenterViewController
        if #available(iOS 18.0, *), !leaderboardSetID.isEmpty {
          gcVC = GKGameCenterViewController(leaderboardSetID: leaderboardSetID)
        } else {
          gcVC = GKGameCenterViewController(state: .leaderboards)
        }
        gcVC.gameCenterDelegate = GameCenterDismissHandler.shared
        self.rootViewController()?.present(gcVC, animated: true)
      }
    }
  }

  private func emitAuthState() {
    self.sendEvent("onAuthStateChanged", [
      "authenticated": GKLocalPlayer.local.isAuthenticated
    ])
  }

  private func rootViewController() -> UIViewController? {
    UIApplication.shared.connectedScenes
      .compactMap { $0 as? UIWindowScene }
      .flatMap { $0.windows }
      .first { $0.isKeyWindow }?
      .rootViewController
  }
}

private class GameCenterDismissHandler: NSObject, GKGameCenterControllerDelegate {
  static let shared = GameCenterDismissHandler()
  func gameCenterViewControllerDidFinish(_ gcVC: GKGameCenterViewController) {
    gcVC.dismiss(animated: true)
  }
}

hasSetHandlerprevents reassigning Apple's handler on later calls. Reassignment is allowed but would orphan the first promise, so we set once and emit updates via events.

Events("onAuthStateChanged") with sendEvent inside the handler fills a gap in the promise flow since a second authenticate() call during pending sign-in resolves with false, and the promise won't re-fire when sign-in completes. The event will.

#available(iOS 18.0, *) is required because GKGameCenterViewController(leaderboardSetID:) is iOS 18+ only. Expo's default target is lower, so without the gate the build fails with "'init(leaderboardSetID:)' is only available in iOS 18.0 or newer". The fallback state: .leaderboards opens the generic leaderboards tab and Apple groups them under the set, so iOS 15-17 users get one extra tap.

JS bindings and hook

// modules/expo-game-center/index.ts
import { Platform } from 'react-native';
import { requireNativeModule } from 'expo-modules-core';

type AuthStateChangedEvent = { authenticated: boolean };

interface ExpoGameCenterModule {
  authenticate(): Promise<boolean>;
  submitScore(score: number, leaderboardID: string): Promise<void>;
  showLeaderboards(leaderboardSetID: string): Promise<void>;
  isAuthenticated(): boolean;
  addListener(
    eventName: 'onAuthStateChanged',
    listener: (event: AuthStateChangedEvent) => void
  ): { remove: () => void };
}

let NativeModule: ExpoGameCenterModule | null = null;
if (Platform.OS === 'ios') {
  try {
    NativeModule = requireNativeModule<ExpoGameCenterModule>('ExpoGameCenter');
  } catch { NativeModule = null; }
}

export function authenticate() {
  return NativeModule?.authenticate() ?? Promise.resolve(false);
}
export function submitScore(score: number, id: string) {
  return NativeModule?.submitScore(score, id) ?? Promise.resolve();
}
export function showLeaderboards(setID = '') {
  return NativeModule?.showLeaderboards(setID) ?? Promise.resolve();
}
export function isAuthenticated(): boolean {
  return NativeModule?.isAuthenticated() ?? false;
}
export function addAuthStateListener(
  listener: (authenticated: boolean) => void
): { remove: () => void } {
  if (!NativeModule) return { remove: () => {} };
  let last: boolean | null = null;
  return NativeModule.addListener('onAuthStateChanged', ({ authenticated }) => {
    if (authenticated === last) return;
    last = authenticated;
    listener(authenticated);
  });
}

The last variable in addAuthStateListener dedupes duplicate emits. Apple's handler sometimes fires twice with the same state, and without the guard every consumer re-renders for nothing.

// src/hooks/use-game-center.ts
import { useEffect, useState, useCallback } from 'react';
import {
  authenticate, isAuthenticated, addAuthStateListener,
  showLeaderboards as nativeShowLeaderboards,
} from '../../modules/expo-game-center';

let initialized = false;
export function initGameCenter() {
  if (initialized) return;
  initialized = true;
  authenticate();
}

export function useGameCenter(leaderboardSetID = '') {
  const [authed, setAuthed] = useState(isAuthenticated);

  useEffect(() => {
    initGameCenter();
    const sub = addAuthStateListener(setAuthed);
    setAuthed(isAuthenticated());
    return () => sub.remove();
  }, []);

  const showLeaderboard = useCallback(() => {
    if (!authed) return;
    nativeShowLeaderboards(leaderboardSetID);
  }, [authed, leaderboardSetID]);

  return { isAuthenticated: authed, showLeaderboard };
}

initGameCenter() is exported separately so you can call it once from your root layout at app startup. That triggers Apple's sign-in early, and the initialized flag prevents duplicate calls if multiple places trigger it.

Inside the hook, setAuthed(isAuthenticated()) runs right after subscribing to catch the race where Apple fires the handler between the subscribe and the initial useState read.

Config plugin for the entitlement

Game Center needs the com.apple.developer.game-center entitlement. Add it from your local module's config plugin so you don't have to touch ios/ directly.

// modules/expo-game-center/app.plugin.js
const { withEntitlementsPlist } = require('@expo/config-plugins');

module.exports = function withGameCenter(config) {
  return withEntitlementsPlist(config, (cfg) => {
    cfg.modResults['com.apple.developer.game-center'] = true;
    return cfg;
  });
};

Reference it in app.json:

"plugins": ["./modules/expo-game-center/app.plugin.js"]

App Store Connect

You can create leaderboards in the ASC web UI, or script them via the API with a .p8 key. The API has a few field names that will bite you if you're copying from old examples.

The field is defaultFormatter, not scoreFormat. The sort direction is DESC, not DESCENDING. And there's no millisecond formatter in the enum, just ELAPSED_TIME_CENTISECOND, so divide your ms by 10 before you call submitScore.

Sets are optional. Group your leaderboards into one or don't bother. The gotcha is that the moment you create your first set, every leaderboard you add after that has to sit inside a set too. So don't create one unless you actually want the grouping.

Attach components to a version submission

Creating the leaderboards in ASC isn't enough on its own. The first time you ship any Game Center component, you also have to attach it to an app version's submission so Apple reviews them together with your binary. There's no API endpoint for this. It's a manual step in the ASC web UI:

App → Game Center → click each component
"Add for Review" → "Add to an existing draft submission"
Pick the draft with your new version
Open Draft Submissions (bottom-right of the app view). Your components and the app version should all show up in the same draft.