How Do I Migrate to the Android SDK v3?

Migrate from v2 to v3.2.1

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

What’s New in v3.2.1

Widget Events, Dismissal & External Links — v3.2.x keeps all v3.x code compatible. Every new capability is opt-in, so an existing integration keeps working after a version bump.

New in v3.2.1

• Widget Header No Longer Under the Status Bar: widget content is padded by the status-bar and display-cutout height, so the header and close buttons stay tappable (previously seen on Pixel and Android 15)
• Status-Bar Icon Contrast: the widget uses a dedicated theme with dark status-bar icons, keeping them visible over the widget’s white top band

New in v3.2.0

• Widget Event Channel: widgetEventCallback on ShowProfileRequest receives events posted from the widget, such as gameCompleted
• Host-Initiated Dismiss: GameballApp.hideProfile() dismisses the widget programmatically
• Web-Initiated Close: the widget can dismiss itself via window.GameballWidget.closeWidget()
• External-Link Handling: links tagged gbExternalBrowser=true open in the system browser, or in your own handler via externalLinkCallback
• Channel Merging: ShowProfileRequest.builder() accepts optional mobile and email
• Diagnostic Logging: the SDK records internal diagnostic logs to aid troubleshooting. No integration changes required

Breaking change in v3.2.0: ShowProfileRequest.capturedLinkCallback was renamed to externalLinkCallback, and it now fires only for links the widget tags with gbExternalBrowser=true. If you used capturedLinkCallback, rename it:

// Before (v3.1.x)
.capturedLinkCallback(object : Callback<String> { /* … */ })

// After (v3.2.0+)
.externalLinkCallback(object : Callback<String> { /* … */ })

New in v3.1.x

• Widget URL Fix (3.1.2): eliminated a null customerId value from the widget URL
• 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.2.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.2.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 = "customer-token"
)

3. Event Tracking

v2:

val event = Event.Builder()
    .withCustomerId("customer-123")
    .withEventName("purchase")
    .withEventMetaData("total", 120)
    .build()

v3.2.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 = "customer-token"
)

4. Method Name Changes

v2	v3.2.1
registerCustomer()	initializeCustomer()
Event.Builder()	Event.builder()
withCustomerId()	customerId()
withEventName()	eventName()
withEventMetaData()	eventMetaData()
CustomerRegisterResponse	InitializeCustomerResponse
capturedLinkCallback	externalLinkCallback

CustomerAttributes is unchanged from v2 — no rename needed.

capturedLinkCallback survived v2 and v3.0–v3.1 unchanged and was renamed only in v3.2.0. If you are coming from v3.1.x rather than v2, this is the single rename you need — see the warning at the top of this page.

5. Push Notifications

v2:

gameballApp.initializeFirebase()

v3.2.1:

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

Migration Steps

From v3.1.x to v3.2.1

v3.2.x is backward compatible with v3.1.x, with one exception: if you used capturedLinkCallback, rename it to externalLinkCallback (see the warning above). Every other v3.2.x capability is opt-in, so an existing integration keeps working after a version bump.

1. Update Dependency

   Update your build.gradle to use SDK v3.2.1:

   dependencies {
       implementation 'com.github.gameballers:gb-mobile-android:3.2.1'
   }
   
2. Rename capturedLinkCallback

   If you passed capturedLinkCallback to ShowProfileRequest, rename it to externalLinkCallback. This is the only required code change.

3. (Optional) Adopt the New Widget Capabilities

   Handle widget events, dismiss the widget from your app, or intercept external links:

   val request = ShowProfileRequest.builder()
       .customerId("customer-123")
       .widgetEventCallback(widgetEventCallback)   // React to gameCompleted, etc.
       .externalLinkCallback(externalLinkCallback) // Handle gbExternalBrowser links yourself
       .mobile("[phone]")                    // Channel merging
       .email("[e-mail]")
       .build()
   
   GameballApp.getInstance(this).hideProfile()     // Dismiss the widget programmatically
   

   See Show Profile Widget for the full reference.

4. (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()
   
5. Test

   Test your integration. Aside from the capturedLinkCallback rename, existing code works unchanged.

From v2.x to v3.2.1

1. Update Dependency

   Update your build.gradle to use SDK v3.2.1:

   dependencies {
       implementation 'com.github.gameballers:gb-mobile-android:3.2.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 drop the with prefix on builder methods (e.g., .customerId() instead of .withCustomerId()).

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

• SDK Repository: https://github.com/gameballers/gb-mobile-android
• Release history: see the gb-mobile-android releases page
• Developer Docs: https://docs.gameball.co

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

Next Steps

• Getting Started
• Go-Live Checklist