Skip to main content
This guide helps you migrate from Gameball Android SDK v2 to v3.1.1.

​
What’s New in v3.1.1

Guest Mode & Easier Widget Init — v3.1.1 keeps v3.x code compatible and fixes the profile widget to support guest mode (customerId optional).

​
New Features in v3.1.1

  • Guest Mode Support: Show profile widget without customer authentication
  • Non-Throwing ShowProfileRequest: Customer ID optional for guest mode
  • Session Token Support: Optional token-based authentication (from 3.1.0)
  • Automatic Endpoint Versioning: Routes to v4.1 API when token is present
  • Per-Request Token Override: Override global token on individual API calls
  • Backward Compatible: All v3.0.0 code works unchanged

Improved API

Streamlined API with better Kotlin support and cleaner method names

Better Performance

Optimized SDK initialization and reduced memory footprint

Enhanced Type Safety

Stronger typing and better compile-time checks

Simplified Configuration

Easier configuration with builder pattern throughout

​
Breaking Changes

​
1. SDK Initialization

v2: 
GameballApp.getInstance(context).init(
    "api-key",
    "en",
    "android",
    "shop-id"
)
v3.1.1: 
val config = GameballConfig.builder()
    .apiKey("api-key")
    .lang("en")
    .platform("android")
    .shop("shop-id")
    .sessionToken("session-token")  // Optional
    .build()

GameballApp.getInstance(context).init(config)

​
2. Customer Registration

v2: 
gameballApp.registerCustomer(
    customerId,
    customerAttributes,
    referralCode,
    isGuest,
    callback
)
v3.1.1: 
val customerRequest = InitializeCustomerRequest.builder()
    .customerId(customerId)
    .customerAttributes(customerAttributes)
    .referralCode(referralCode)
    .build()

GameballApp.getInstance(context).initializeCustomer(
    customerRequest,
    callback
)

// Optional: Override session token for this request
GameballApp.getInstance(context).initializeCustomer(
    customerRequest,
    callback,
    sessionToken = "custom-token"
)

​
3. Event Tracking

v2: 
val event = Event.Builder()
    .AddUniquePlayerId("customer-123")
    .AddEventName("purchase")
    .build()
v3.1.1: 
val event = Event.builder()
    .customerId("customer-123")
    .eventName("purchase")
    .build()

GameballApp.getInstance(context).sendEvent(event, callback)

// Optional: Override session token for this request
GameballApp.getInstance(context).sendEvent(
    event,
    callback,
    sessionToken = "custom-token"
)

​
4. Method Name Changes

v2v3.1.1
registerCustomer()initializeCustomer()
AddUniquePlayerId()customerId()
AddEventName()eventName()
AddEventMetaData()eventMetaData()
PlayerAttributesCustomerAttributes
PlayerRegisterResponseInitializeCustomerResponse

​
5. Push Notifications

v2: 
gameballApp.initializeFirebase()
v3.1.1: 
// Token is provided during customer initialization
val customerRequest = InitializeCustomerRequest.builder()
    .customerId("customer-123")
    .deviceToken(fcmToken)
    .pushProvider(PushProvider.Firebase)
    .build()

​
Migration Steps

​
From v3.0.0 to v3.1.1 (No Breaking Changes)

v3.1.1 is fully backward compatible. Simply update the dependency version. Session Token is optional.
1

Update Dependency

Update your build.gradle to use SDK v3.1.1:
dependencies {
    implementation 'com.gameball:gameball-sdk:3.1.1'
}
2

(Optional) Add Session Token

If enhanced security is needed, add session token to your configuration:
val config = GameballConfig.builder()
    .apiKey("api-key")
    .lang("en")
    .sessionToken("your-session-token")
    .build()
3

Test

Test your integration. All existing code should work unchanged.

​
From v2.x to v3.1.1

1

Update Dependency

Update your build.gradle to use SDK v3.1.1:
dependencies {
    implementation 'com.gameball:gameball-sdk:3.1.1'
}
2

Update Initialization

Replace your SDK initialization code with the new GameballConfig builder pattern.
3

Update Customer Registration

Replace registerCustomer() with initializeCustomer() using the new request builder.
4

Update Event Tracking

Update event creation to use lowercase builder methods (e.g., .customerId() instead of .AddUniquePlayerId()).
5

Update Push Notifications

Move device token registration to customer initialization instead of separate initializeFirebase() call.
6

Test Thoroughly

Test all Gameball functionality to ensure the migration is successful.

​
Compatibility

  • Minimum SDK: Android API 21 (Android 5.0)
  • Target SDK: Android API 34
  • Kotlin: 2.0.0+
  • AndroidX: Required
  • Gradle: 7.0+

​
Additional Resources

If you encounter any issues during migration, check the GitHub repository for known issues and solutions, or contact Gameball support.

​
Next Steps