Engine Bridge Installation

alogame-sdk is a TypeScript bridge that lets a Cocos Creator or Egret game call the real native Android/iOS Alogame SDK from game script — login, payment, analytics, push, and account management — without writing any native code yourself.

This is not the Web SDK

alogame-sdk is for games that compile to a native Android/iOS app (Cocos Creator, Egret, and similar engines that build through a native shell). If your game runs directly in a browser (HTML5/H5), use @alogame/web-sdk instead — different package, different transport, no native project changes required.

How it works

Game script (TS/JS)
   │  AlogameAuth.login(...) / AlogamePayment.purchase(...) / ...
   ▼
alogame-sdk  (this package — engine detection + JSON method-string protocol)
   │  native.bridge.sendToNative(...)   [Cocos]
   │  egret.ExternalInterface.call(...) [Egret]
   ▼
Native bridge glue — OEGBridge.kt (Android) / OEGBridge.swift (iOS)
   ▼
Real native OEG SDK (OEGAuth, OEGPayment, OEGAnalytics, OEGPush, OEGAccount)

The npm package only handles the JS side. Because your game ultimately compiles into a real Android/iOS app, the native side also needs one-time setup — see Native project setup below. Skipping it means every call will fail (or silently no-op in browser preview).

1. Install the package

npm install alogame-sdk

Or copy the built UMD bundle into your engine's libs/ folder:

libs/alogame-sdk/
├── alogame-sdk.js       ← UMD build, exposes global `Alogame`
└── alogame-sdk.d.ts     ← type declarations for the editor

Cocos Creator / Egret — ES module

import { AlogameSdk, AlogameAuth } from 'alogame-sdk';

UMD (no bundler)

// Everything is exposed under the global `Alogame`
const { AlogameSdk, AlogameAuth } = window.Alogame;

2. Initialize on game boot

main.ts

import { AlogameSdk } from 'alogame-sdk';

async function boot() {
  await AlogameSdk.init();   // handshake with the native bridge
  // Now safe to call AlogameAuth / AlogamePayment / ... on any user action
}

AlogameSdk.init() also runs engine auto-detection the first time you touch AlogameSdk.bridge:

Environment	Detected as	Behavior
Cocos Creator v3 native build	CocosBridge	Calls the real native SDK
Egret native build	EgretBridge	Calls the real native SDK
Browser preview (Cocos/Egret web preview, no native shell)	MockBridge	Returns canned mock responses — lets you build/test UI flow without a device

You don't select the bridge yourself — it's chosen automatically based on what globals exist at runtime (native.bridge for Cocos, egret for Egret).

Native project setup

Do this once, in the native Android/iOS project your engine generates when you build for device. Native template layout differs per engine — the paths below are the Cocos/Egret convention; adjust to your project.

Android

1. Copy the native SDK and bridge glue .aar files into your native project's libs/ folder: oeg-sdk.aar (the core SDK) and the bridge glue .aar (vn.oeg.sdk.bridge.OEGBridge).
2. Add oeg_config.json to app/src/main/assets/ — same file shape as the native Android SDK:
   app/src/main/assets/oeg_config.json

   {
     "core": {
       "game_id": YOUR_GAME_ID
     }
   }

3. Call OEGBridge.setup(...) once, in your main Activity, after your native engine wrapper (EgretNativeAndroid/equivalent) is created:
   MainActivity.kt

   OEGBridge.setup(this, nativeAndroid)

   This reads oeg_config.json, boots the full native SDK (auth, payment, analytics, push, account), and wires the JS↔native message channel.

Native billing/coroutines dependencies

The bridge glue module declares Google Play Billing and Kotlin coroutines as compileOnly — your native project's own build.gradle must provide them at runtime (same as the native Android SDK does).

iOS

1. Add OegSdkV2.xcframework and the bridge glue source (OEGBridge.swift) to your native Xcode project.
2. Add oeg_config.json to your app bundle (same shape as above, same as the native iOS SDK).
3. Call OEGBridge.setup(with:) once, wherever your native template wires up EgretNativeIOS:
   AppDelegate.swift

   OEGBridge.setup(with: nativeIOS)

   This loads oeg_config.json, boots the full native SDK, and wires the JS↔native message channel.

3. Try it

import { AlogameSdk, AlogameAuth } from 'alogame-sdk';

await AlogameSdk.init();

const result = await AlogameAuth.showLoginUI();
if (result.success) {
  console.log('Logged in:', result.user?.username);
}

In browser preview (no native shell), this resolves against MockBridge canned data — useful for iterating on your game's login/purchase UI flow before testing on a real device.

Next step

→ Authentication