Skip to main content

​
Migration Notes & Changelog

This guide helps you migrate from Gameball Android SDK v2 to v3.1.0.

​
What’s New in v3.1.0

Session Token Authentication — v3.1.0 introduces optional Session Token authentication for enhanced security with automatic v4.1 endpoint routing.

​
New Features in v3.1.0

  • Session Token Support: Optional token-based authentication
  • Automatic Endpoint Versioning: Routes to v4.1 API when token is present
  • Per-Request Token Override: Override global token on individual API calls
  • Secure Token Storage: SharedPreferences-based token management
  • Backward Compatible: All existing 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.0: 
val config = GameballConfig.builder()
    .apiKey("api-key")
    .lang("en")
    .platform("android")
    .shop("shop-id")
    .sessionToken("session-token")  // Optional - New in v3.1.0
    .build()

GameballApp.getInstance(context).init(config)

​
2. Customer Registration

v2: 
gameballApp.registerCustomer(
    customerId,
    customerAttributes,
    referralCode,
    isGuest,
    callback
)
v3.1.0: 
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.0: 
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.0
registerCustomer()initializeCustomer()
AddUniquePlayerId()customerId()
AddEventName()eventName()
AddEventMetaData()eventMetaData()
PlayerAttributesCustomerAttributes
PlayerRegisterResponseInitializeCustomerResponse

​
5. Push Notifications

v2: 
gameballApp.initializeFirebase()
v3.1.0: 
// 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.0 (No Breaking Changes)

v3.1.0 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.0:
dependencies {
    implementation 'com.gameball:gameball-sdk:3.1.0'
}
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.0

1

Update Dependency

Update your build.gradle to use SDK v3.1.0:
dependencies {
    implementation 'com.gameball:gameball-sdk:3.1.0'
}
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

For v3.1.0-specific details, refer to the gb-mobile-android repository on branch release-3.1.0.
If you encounter any issues during migration, check the GitHub repository for known issues and solutions, or contact Gameball support.

​
Next Steps