Skip to main content

​
Initialize the Gameball SDK

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. 
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

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

        GameballApp.getInstance(this).init(config)
    }
}
Make sure your Application class is registered in your AndroidManifest.xml:<applicationandroid: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.
​
apiPrefix
string
Optional custom API endpoint prefix for advanced configurations.

​
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: 
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)
    }
}
Always use your Test Key in development and staging builds, and your Production Key only in live builds.

​
Common Initialization Issues

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