> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Initialization

> 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

<div className="security-banner">
  <div className="security-banner-icon">🔒</div>

  <div className="security-banner-content">
    <strong>Secure API Access:</strong> To benefit from v4.1 secure API endpoints, pass the <code>sessionToken</code> parameter during SDK initialization (required in upcoming SDK v4). This enables automatic routing to v4.1 secure endpoints. <a href="/api-reference/introduction-v4.1">Learn more about v4.1 →</a>
  </div>
</div>

```swift theme={null}
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
    }
}
```

```swift theme={null}
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.

<ParamField body="apiKey" type="String" required>
  Your Gameball project API key from the dashboard.
</ParamField>

<ParamField body="lang" type="String" required>
  Language code, e.g., "en" or "ar".
</ParamField>

<ParamField body="platform" type="String">
  Platform identifier. Defaults to `"ios"`.
</ParamField>

<ParamField body="shop" type="String">
  Shop identifier used in multi-shop setups.
</ParamField>

<ParamField body="sessionToken" type="String">
  Optional Session Token for secure authentication, enables automatic routing to Gameball v4.1 APIs. Required in upcoming SDK v4.
</ParamField>

## 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

```swift theme={null}
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

```swift theme={null}
let config = GameballConfig(
    apiKey: "your-api-key",
    lang: "en",
    shop: "shop_us"
)

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

***

### Using Session Token (v4.1 Routing)

```swift theme={null}
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.

```swift theme={null}
#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:**

```swift theme={null}
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)
}
```

<Tip>
  Initialize the SDK as early as possible so tracking and profile features are ready immediately.
</Tip>

<Warning>
  Always use **test keys** in development.\
  Never commit **live API keys** to version control.
</Warning>