Configuration

Tuning SdkOptions, and when to use createSdk vs. the gamee singleton.

The SDK ships sensible defaults — most games don’t need to touch any of this. Reach for these when you want stricter security in production, are wiring tests, or have an unusual high-throughput workload.

SdkOptions#

Pass an options object to createSdk(). The default singleton (gamee) uses all defaults.

import { createSdk } from '@gamee/sdk';

const sdk = createSdk({
  allowedOrigins: ['https://games.gameeapp.com'],
  requestTimeoutMs: 15_000,
  maxPendingRequests: 64,
  silentMode: false,
});

allowedOrigins#

Whitelist of origins that may exchange messages with the game on web (the postMessage bridge). Any inbound message from an origin outside the list is dropped.

'*' accepts any origin and logs a warning on first use to remind you to lock it down. In production, always pass an explicit list:

const sdk = createSdk({
  allowedOrigins: ['https://games.gameeapp.com', 'https://gamee.com'],
});

Ignored on the iOS and Android bridges (they’re bound to the native platform).

requestTimeoutMs#

How long the SDK waits for a platform response before rejecting a data-returning request with BRIDGE_TIMEOUT. Default is 30 000 ms (30 s) — long enough for showRewardedVideo to span an actual ad.

Lower it (5–10 s) in tests to fail fast. Don’t raise it in production — if the platform is taking longer than 30 s, something is wrong.

const sdk = createSdk({ requestTimeoutMs: 5_000 });

maxPendingRequests#

Cap on the number of data-returning calls that can be in flight at once. When the cap is hit, the oldest pending request is rejected with BRIDGE_OVERFLOW to free a slot.

Default 256 is generous; most games never see the overflow. Lower it (e.g. 16) if you want the SDK to fail fast on a runaway request loop. Fire-and-forget signals like updateScore are not tracked and don’t count.

silentMode#

Suppresses the SDK’s console.warn runtime warnings (origin warnings, deprecation notices, unknown-event logs). Doesn’t affect errors — they always surface as Promise rejections.

Set in production builds where you don’t want console noise:

const sdk = createSdk({ silentMode: import.meta.env.PROD });

bridge#

Inject a custom transport. When set, platform auto-detection is bypassed and getPlatform() returns bridge.platform.

The two practical uses:

• Tests — pass a MockBridge from @gamee/sdk-test-utils.
• The emulator — drives the SDK through a custom in-page bridge.

import { MockBridge } from '@gamee/sdk-test-utils';
const sdk = createSdk({ bridge: new MockBridge('ios') });

createSdk() vs. gamee singleton#

The package exports both:

import { gamee, createSdk } from '@gamee/sdk';

Use gamee (the singleton) when#

• You’re shipping a real game. There’s exactly one platform and exactly one game per page; sharing one SDK instance is the right default.
• You want zero ceremony — no factory call, no plumbing.

The singleton is lazy: it’s only constructed on first property access, so just importing the symbol doesn’t create a bridge.

Use createSdk() when#

• You’re writing tests. Tests need a fresh SDK each run; the singleton’s state would leak across tests.
• You need to pass SdkOptions (origins, timeouts, custom bridge).
• You’re building an emulator/platform that needs to instantiate multiple SDKs against different bridges.

beforeEach(() => {
  const mock = new MockBridge();
  sdk = createSdk({ bridge: mock });
});

Reading runtime info#

A few read-only properties are useful for diagnostics:

import { gamee, SDK_VERSION, ALL_CAPABILITIES } from '@gamee/sdk';

gamee.version; // → SDK version (string)
gamee.getPlatform(); // → 'web' | 'mobile_web' | 'ios' | 'android'
gamee.initResponse; // → GameInitResponse | null  (after init())

SDK_VERSION; // → same as gamee.version, but available pre-init
ALL_CAPABILITIES; // → readonly Capability[]

dispose()#

Releases bridge resources and rejects every in-flight Promise with INVALID_STATE. You almost never want this in production — it’s there for tests and for platforms that mount multiple games per page.

afterEach(() => sdk.dispose());