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

# How Do I Initialize the Android SDK (v4)?

> Configure and initialize Gameball Android SDK v4.0.0

Before you can register customers, track events, or show the profile widget, you must initialize the **Gameball Android SDK** with your configuration.

Initialization is typically done once in your `Application` class.

***

## Application-Level Initialization

Create (or update) your `Application` class and initialize Gameball in `onCreate`.

🔒

**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 →](https://docs.gameball.co/api-reference/introduction-v4.1.md)

```kotlin Kotlin theme={null}
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        val config = GameballConfig.builder()
            .apiKey("your-api-key")            // Required
            .lang("en")                        // Required
            .platform("android")               // Optional
            .shop("your-shop-id")              // Optional
            .sessionToken("your-session-token")// Optional - enables v4.1 endpoints
            .build()

        GameballApp.getInstance(this).init(config)
    }
}
```

```java Java theme={null}
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        GameballConfig config = GameballConfig.builder()
            .apiKey("your-api-key")             // Required
            .lang("en")                         // Required
            .platform("android")                // Optional
            .shop("your-shop-id")               // Optional
            .sessionToken("your-session-token") // Optional - enables v4.1 endpoints
            .build();

        GameballApp.getInstance(this).init(config);
    }
}
```

> [!TIP]
>
> Make sure your `Application` class is registered in your `AndroidManifest.xml`:
>
> \<application
>
> android:name=".MyApplication"
>
> ... >

***

## Configuration Parameters

**apiKey** `string` *required*

Your Gameball API key from the dashboard. Required.

**lang** `string` *required*

Language code for SDK localization (for example, "en", "ar", "fr"). Required.

**platform** `string`

Platform identifier. Defaults to `"android"`.

**shop** `string`

Your Gameball shop identifier for multi-shop setups.

**sessionToken** `string`

Optional Session Token used for secure authentication and automatic v4.1 endpoint routing. Required in upcoming SDK v4.

### Validation Rules

**GameballConfig requires:**

* apiKey cannot be null
* lang cannot be null

If either is missing, initialization will fail and API calls will not succeed.

***

## Environment Configuration (Test vs Production)

You can switch between Test and Production keys based on your build type:

```kotlin theme={null}
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        val apiKey = if (BuildConfig.DEBUG) {
            "gb_test_your-key"      // Test key
        } else {
            "gb_live_your-key"      // Production key
        }

        val config = GameballConfig.builder()
            .apiKey(apiKey)
            .lang("en")
            .build()

        GameballApp.getInstance(this).init(config)
    }
}
```

> [!NOTE]
>
> Always use your **Test Key** in development and staging builds, and your **Production Key** only in live builds.

***

## Common Initialization Issues

> [accordion] SDK Not Initialized Error
>
> **Error:** `API key is required for customer initialization` **Cause:** `GameballApp.getInstance(context).init(config)` was not called before other SDK methods.
>
> **Solution:** Ensure initialization happens in your `Application.onCreate()` and that the Application class is correctly registered in `AndroidManifest.xml`.

> [accordion] Invalid API Key
>
> **Symptoms:** Requests failing with authentication or 4xx errors. **Solution:** Verify the API key used in `GameballConfig` matches the key shown in your Gameball dashboard (and that you are using the correct environment key: Test vs Production).

***

## Next Steps

Once the SDK is initialized, you can proceed with:

* [Initialize Customer Profile](https://docs.gameball.co/installation-guides/v4/android/initialize-profile.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.