How Do I Initialize the iOS SDK (v3)?

Initialize the Gameball iOS SDK with your project configuration

After installing the SDK, the next step is to initialize Gameball when your app launches.
This prepares the SDK to track events, register customers, and display widgets.

You should initialize Gameball as early as possible—typically in your AppDelegate, SceneDelegate, or SwiftUI App initializer.

---

1. Basic Initialization

🔒

Secure API Access: To benefit from v4.1 secure API endpoints, pass the sessionToken parameter during SDK initialization (required in upcoming SDK v4). This enables automatic routing to v4.1 secure endpoints. Learn more about v4.1 →

import UIKit
import Gameball

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        
        let config = GameballConfig(
            apiKey: "your-api-key",          // Required
            lang: "en"                       // Required
        )
        
        GameballApp.getInstance().`init`(config: config) { error in
            if let error = error {
                print("Gameball init failed: \(error.localizedDescription)")
            }
        }
        
        return true
    }
}

import SwiftUI
import Gameball

@main
struct YourApp: App {
    
    init() {
        let config = GameballConfig(
            apiKey: "your-api-key",
            lang: "en"
        )
        
        GameballApp.getInstance().`init`(config: config)
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

---

2. Configuration Parameters

Below are all supported fields of GameballConfig.

apiKey · String · required

Your Gameball project API key from the dashboard.

lang · String · required

Language code, e.g., “en” or “ar”.

platform · String

Platform identifier. Defaults to "ios".

shop · String

Shop identifier used in multi-shop setups.

sessionToken · String

Optional Session Token for secure authentication, enables automatic routing to Gameball v4.1 APIs. Required in upcoming SDK v4.

3. Validation Rules

GameballConfig enforces:

• apiKey must not be empty
• lang must not be empty

If any required parameter is missing, initialization will fail silently and SDK methods will not be available.

---

4. Configuration Examples

Basic Setup

let config = GameballConfig(
    apiKey: "gb_live_xxxxxxx",
    lang: "en",
    platform: "ios",
    shop: "your-shop-id",
    sessionToken: "your-session-token"
)

GameballApp.getInstance().`init`(config: config)

---

Multi-Shop Configuration

let config = GameballConfig(
    apiKey: "your-api-key",
    lang: "en",
    shop: "shop_us"
)

GameballApp.getInstance().`init`(config: config)

---

Using Session Token (v4.1 Routing)

let config = GameballConfig(
    apiKey: "your-api-key",
    lang: "en",
    sessionToken: "your-session-token"
)

GameballApp.getInstance().`init`(config: config)

Custom API Prefix

5. Environment-Specific Configuration (Recommended)

Use your test key during development and live key in production.

#if DEBUG
let config = GameballConfig(
    apiKey: "gb_test_xxxxxxxxx",
    lang: "en"
)
#else
let config = GameballConfig(
    apiKey: "gb_live_xxxxxxxxx",
    lang: "en"
)
#endif

GameballApp.getInstance().`init`(config: config)

---

6. Loading Configuration From a File (Optional)

If you prefer not to embed keys directly in code, you can store them in a .plist.

GameballConfig.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>APIKey</key>
    <string>your-api-key</string>
    <key>Language</key>
    <string>en</string>
    <key>Shop</key>
    <string>your-shop-id</string>
</dict>
</plist>

Load configuration in code:

func loadGameballConfig() -> GameballConfig? {
    guard let path = Bundle.main.path(forResource: "GameballConfig", ofType: "plist"),
          let dict = NSDictionary(contentsOfFile: path) as? [String: Any],
          let apiKey = dict["APIKey"] as? String,
          let lang = dict["Language"] as? String else {
        return nil
    }
    
    return GameballConfig(
        apiKey: apiKey,
        lang: lang,
        shop: dict["Shop"] as? String,
        platform: "ios"
    )
}

if let config = loadGameballConfig() {
    GameballApp.getInstance().`init`(config: config)
}

Initialize the SDK as early as possible so tracking and profile features are ready immediately.

Always use test keys in development.
Never commit live API keys to version control.