How Do I Migrate to the Android SDK v3?

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.

Update Dependency

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

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

Rename capturedLinkCallback

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

(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("+201234567890")                    // Channel merging
    .email("customer@example.com")
    .build()

GameballApp.getInstance(this).hideProfile()     // Dismiss the widget programmatically

See Show Profile Widget for the full reference.

(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()

Test

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

From v2.x to v3.2.1

Update Dependency

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

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

Update Initialization

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

Update Customer Registration

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

Update Event Tracking

Update event creation to drop the with prefix on builder methods (e.g., .customerId() instead of .withCustomerId()).

Update Push Notifications

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

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.

Overview

Web & POS Integration

Mobile Integration

How Do I Migrate to the Android SDK v3?

What’s New in v3.2.1

New in v3.2.1

New in v3.2.0

New in v3.1.x

Improved API

Better Performance

Enhanced Type Safety

Simplified Configuration

Breaking Changes

1. SDK Initialization

2. Customer Registration

3. Event Tracking

4. Method Name Changes

5. Push Notifications

Migration Steps

From v3.1.x to v3.2.1

From v2.x to v3.2.1

Compatibility

Additional Resources

Next Steps

​What’s New in v3.2.1

​New in v3.2.1

​New in v3.2.0

​New in v3.1.x

Improved API

Better Performance

Enhanced Type Safety

Simplified Configuration

​Breaking Changes

​1. SDK Initialization

​2. Customer Registration

​3. Event Tracking

​4. Method Name Changes

​5. Push Notifications

​Migration Steps

​From v3.1.x to v3.2.1

​From v2.x to v3.2.1

​Compatibility

​Additional Resources

​Next Steps

What’s New in v3.2.1

New in v3.2.1

New in v3.2.0

New in v3.1.x

Breaking Changes

1. SDK Initialization

2. Customer Registration

3. Event Tracking

4. Method Name Changes

5. Push Notifications

Migration Steps

From v3.1.x to v3.2.1

From v2.x to v3.2.1

Compatibility

Additional Resources

Next Steps