Skip to main content
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

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
        )
        
        Gameball.shared.initialize(with: config)
        
        return true
    }
}

import SwiftUI
import Gameball

@main
struct YourApp: App {
    
    init() {
        let config = GameballConfig(
            apiKey: "your-api-key",
            lang: "en"
        )
        
        Gameball.shared.initialize(with: 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.
​
apiPrefix
String
Custom API domain for advanced enterprise configurations.

​
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"
)

Gameball.shared.initialize(with: config)

​
Multi-Shop Configuration

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

Gameball.shared.initialize(with: config)

​
Using Session Token (v4.1 Routing)

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

Gameball.shared.initialize(with: config)

​
Custom API Prefix

let config = GameballConfig(
    apiKey: "your-api-key",
    lang: "en",
    apiPrefix: "https://custom-api.yourcompany.com"
)

Gameball.shared.initialize(with: config)
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

Gameball.shared.initialize(with: 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() {
    Gameball.shared.initialize(with: 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.