Skip to main content

iOS SDK V2 Installation

Requirements​

  • iOS 14.0+
  • Xcode 15+

Installation via Swift Package Manager​

In Xcode: File → Add Package Dependencies

Enter the package URL:

https://gitlab.oeg.vn/release/oeg-ios-sdk-v2

Select the version you want (e.g. 1.4.1), then add OegSdkV2 to your app target.

Initialize the SDK​

Initialize once, at app launch — just a Game ID, no config file needed. All other behaviour (feature flags, user info requirements, tracking config) is loaded from the server at runtime.

Objective-C (AppDelegate.mm)​

For Egret, Cocos Creator, or any Objective-C game template using the SDK's built-in UI, call Builder before handleDidFinishLaunchingWithOptions: (which calls OegSdkCore.shared.initialize() internally — initialization only runs once, so whichever call reaches it first wins):

AppDelegate.mm
@import OegSdkV2;

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[[Builder new] setGameId:53] build];
    [AlogameManager handleDidFinishLaunchingWithOptions:launchOptions];
    // ... rest of your setup
    return YES;
}
New vs. existing games

AlogameManager is the Alogame-branded entry point for new integrations — it's identical to OEGManager (a thin subclass, nothing reimplemented), so behavior never drifts between the two. Existing games already integrated against OEGManager keep working unchanged; there's no need to migrate. Every method below (showLoginWithCallback:, getAPIToken, etc.) works the same on both names.

Swift — UIKit (AppDelegate)​

AppDelegate.swift
import UIKit
import OegSdkV2

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        OegSdkCore.Builder()
            .setGameId(53)
            .build()
        return true
    }
}

Swift — SwiftUI​

YourApp.swift
import SwiftUI
import OegSdkV2

@main
struct YourApp: App {
    init() {
        OegSdkCore.Builder()
            .setGameId(53)
            .build()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Builder also has setApiBaseUrl, setDebugEnv, setSentryDsn, setAdjustConfig(appToken:environment:), and setMaintainPollingInterval — all optional, matching the equivalent keys in the full config reference below.

note

Builder is exposed to Objective-C as a plain, unprefixed class. If another SDK in your app also defines a class literally named Builder, watch for symbol clashes.

Alternative: oeg_config.json​

Prefer a config file (e.g. to vary game_id per build scheme, or to set advanced options without a code change)? Create oeg_config.json and add it to your app target (make sure it's included in Copy Bundle Resources), then call plain initialize()/handleDidFinishLaunchingWithOptions: with no Builder call first:

AppDelegate.mm
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [AlogameManager handleDidFinishLaunchingWithOptions:launchOptions]; // reads oeg_config.json
    return YES;
}
AppDelegate.swift / YourApp.swift
OegSdkCore.shared.initialize() // reads oeg_config.json
oeg_config.json
{
  "core": {
    "game_id": YOUR_GAME_ID
  }
}
Full reference (all optional local keys)
oeg_config.json
{
  "core": {
    "game_id": YOUR_GAME_ID
  }
}

The sns block supplements server-delivered config. Values in Info.plist (required by Facebook/TikTok SDKs) take precedence over this block.

Forward app delegate callbacks​

Required for social login (Facebook, Google, TikTok) and push notifications:

Swift​

AppDelegate.swift
// Custom URL schemes — Facebook, Google
func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    return AlogameManager.handleOpenURL(url, options: options)
}

// Universal Links — required for TikTok login callback
func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    return AlogameManager.handleContinueUserActivity(userActivity)
}

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    AlogameManager.handleDidRegisterForRemoteNotifications(deviceToken: deviceToken)
}

Objective-C​

AppDelegate.mm
// Custom URL schemes — Facebook, Google
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    return [AlogameManager handleOpenURL:url options:options];
}

// Universal Links — required for TikTok login callback
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
    return [AlogameManager handleContinueUserActivity:userActivity];
}

- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [AlogameManager handleDidRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

// Push notification delivery (required for SDK internal handling)
- (void)application:(UIApplication *)application
didReceiveRemoteNotification:(NSDictionary *)userInfo
fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [AlogameManager handleRemoteNotification:userInfo];
    completionHandler(UIBackgroundFetchResultNewData);
}

Objective-C — App lifecycle callbacks​

The SDK needs these to manage session state correctly. Add to AppDelegate.mm:

AppDelegate.mm
- (void)applicationWillResignActive:(UIApplication *)application {
    [AlogameManager handleWillResignActive];
}
- (void)applicationDidEnterBackground:(UIApplication *)application {
    [AlogameManager handleDidEnterBackground];
}
- (void)applicationWillEnterForeground:(UIApplication *)application {
    [AlogameManager handleWillEnterForeground];
}
- (void)applicationDidBecomeActive:(UIApplication *)application {
    [AlogameManager handleDidBecomeActive];
}
- (void)applicationWillTerminate:(UIApplication *)application {
    [AlogameManager handleWillTerminate];
}
warning

continueUserActivity is required for TikTok login. TikTok SDK 2.x uses Universal Links for the auth callback — even when the TikTok app is installed. Without this method, TikTok redirects back to the app but the auth code is silently dropped and the login screen stays open.

Show login​

Objective-C​

[[AlogameManager sharedManager] showLoginWithCallback:^(OEGActionType type, id response, BOOL success, NSError *error) {
    if (success) {
        NSString *token = [AlogameManager getAPIToken];
        NSString *uuid  = [AlogameManager getAPIUUID];
        // send token to your game server
    }
    if (type == OEGActionTypeLogout) {
        // handle logout — navigate back to your game's login screen
    }
}];

Swift​

AlogameManager.sharedManager.showLogin(callback: { action, response, success, error in
    if success {
        let token = AlogameManager.getAPIToken()
        // send token to your game server
    }
    if action == .logout {
        // handle logout — navigate back to your game's login screen
    }
})

Firebase Analytics​

FirebaseAnalytics is a hard dependency of OegSdkV2 — it is automatically added when you add the SDK package. No separate SPM step is needed.

To activate data collection, add a GoogleService-Info.plist (downloaded from the Firebase console) to your app target. Without it, the SDK still initialises cleanly — Firebase simply no-ops and no data is sent.

Event routing is controlled by the CMS per-game/per-platform configuration:

  • firebase_enabled (default true) — master switch
  • firebase_events — CMS-compiled allow-list of event names that should be forwarded to Firebase (matches entries in event_token_mapping with the "→ Firebase" toggle on)

sdk_* lifecycle events (sdk_show_login, sdk_register_success, sdk_login_success, sdk_logout, sdk_recharge) and their derived purchase event are always listed in CMS production configs.

Google Login​

Auto-installed — GoogleSignIn-iOS is a transitive dependency of OegSdkV2. No SPM step needed.

Add a GoogleService-Info.plist to the app target with the iOS client (CLIENT_ID / REVERSED_CLIENT_ID), then register the URL scheme in Info.plist:

note

The same GoogleService-Info.plist file activates both Google Sign-In and Firebase Analytics. You only need one file.

Info.plist
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YOUR_REVERSED_CLIENT_ID</string>
        </array>
    </dict>
</array>

The iOS CLIENT_ID is the iOS-specific OAuth client. The web client ID (google_web_client_id in server config) is set as serverClientID so the returned idToken is verifiable by the backend.

Optional: Facebook Login​

Add the Facebook SDK via SPM if your game enables Facebook login.

1. Add the package​

File → Add Package Dependencies, enter:

https://github.com/facebook/facebook-ios-sdk

Add FacebookLogin to your app target.

2. Register the URL scheme (required)​

Facebook uses a custom URL scheme to redirect back to your app after login. Without this, the OAuth flow silently fails.

In Xcode: Target → Info → URL Types → +

  • Identifier: com.facebook
  • URL Schemes: fbYOUR_FACEBOOK_APP_ID (e.g. fb1234567890)

Or add directly to Info.plist:

Info.plist
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>fbYOUR_FACEBOOK_APP_ID</string>
        </array>
    </dict>
</array>

3. App ID and Client Token​

The SDK reads these from server config automatically — no Info.plist entries needed. If you want a local fallback (e.g. for offline/first-launch before server config loads):

Info.plist
<key>FacebookAppID</key>
<string>YOUR_FACEBOOK_APP_ID</string>
<key>FacebookClientToken</key>
<string>YOUR_FACEBOOK_CLIENT_TOKEN</string>

Optional: TikTok Login​

Add the TikTok Open SDK via SPM if your game enables TikTok login.

1. Add the package​

File → Add Package Dependencies, enter:

https://github.com/tiktok/tiktok-opensdk-ios

Add TikTokOpenSDKCore and TikTokOpenAuthSDK to your app target.

2. Register the URL scheme (required)​

In Xcode: Target → Info → URL Types → +

  • Identifier: com.tiktok
  • URL Schemes: your TikTok Client Key value directly (e.g. aw1234abcd)

Or add directly to Info.plist:

Info.plist
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YOUR_CLIENT_KEY</string>
        </array>
    </dict>
</array>

Also add TikTok app schemes so iOS allows querying whether the TikTok app is installed:

Info.plist
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>tiktokopensdk</string>
    <string>tiktoksharesdk</string>
    <string>snssdk1180</string>
    <string>snssdk1233</string>
</array>

3. Client Key​

The SDK reads this from server config automatically. Optional local fallback:

Info.plist
<key>TikTokClientKey</key>
<string>YOUR_CLIENT_KEY</string>

4. Associated Domains capability (required)​

TikTok login uses Universal Links for the OAuth callback. iOS requires the host app to declare the associated domain — the SDK framework cannot inject this for you.

In Xcode: Target → Signing & Capabilities → + Capability → Associated Domains, then add:

applinks:dev-api-sdk.oeg.vn
applinks:api-sdk.oeg.vn

Or directly in your .entitlements file:

YourApp.entitlements
<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:dev-api-sdk.oeg.vn</string>
    <string>applinks:api-sdk.oeg.vn</string>
</array>

The Alogame backend serves /.well-known/apple-app-site-association on both domains. iOS verifies at install time and will open your app directly when TikTok redirects to the callback URL — no browser handoff needed.

note

Without this capability, iOS falls back to opening the callback URL in Safari, which breaks the TikTok login flow.

Optional: Apple Sign In​

Apple Sign In is built into iOS — no additional SPM package needed. However, the capability must be explicitly enabled in your app target.

1. Enable the capability (required)​

In Xcode: Target → Signing & Capabilities → + Capability → Sign in with Apple

This adds the entitlement automatically. Or add it manually to your .entitlements file:

YourApp.entitlements
<key>com.apple.developer.applesignin</key>
<array>
    <string>Default</string>
</array>
danger

Without this entitlement, Apple Sign In fails immediately with error ASAuthorizationError 1000 — iOS blocks the request before it even reaches Apple's servers.

2. Enable Sign in with Apple on the App ID (Apple Developer Portal)​

In developer.apple.com → Certificates, Identifiers & Profiles → Identifiers → [your App ID]:

  • Enable capability: Sign in with Apple
  • Regenerate and re-download your provisioning profile after enabling (or use Xcode's "Automatically manage signing")

3. No Info.plist changes needed​

Unlike Facebook and TikTok, Apple Sign In requires no URL scheme or Info.plist entries. The capability entitlement above is sufficient.

Push notifications​

OEGPush.shared.requestAuthorization { granted, error in
    print("Push granted: \(granted)")
}