> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Notes

> Migrate from v2 to v3.1.1

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

## What's New in v3.1.1

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

### 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

<CardGroup cols={2}>
  <Card title="Improved API" icon="code">
    Streamlined API with better Kotlin support and cleaner method names
  </Card>

  <Card title="Better Performance" icon="gauge-high">
    Optimized SDK initialization and reduced memory footprint
  </Card>

  <Card title="Enhanced Type Safety" icon="shield">
    Stronger typing and better compile-time checks
  </Card>

  <Card title="Simplified Configuration" icon="sliders">
    Easier configuration with builder pattern throughout
  </Card>
</CardGroup>

## Breaking Changes

### 1. SDK Initialization

**v2:**

```kotlin theme={null}
GameballApp.getInstance(context).init(
    "api-key",
    "en",
    "android",
    "shop-id"
)
```

**v3.1.1:**

```kotlin theme={null}
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:**

```kotlin theme={null}
gameballApp.registerCustomer(
    customerId,
    customerAttributes,
    referralCode,
    isGuest,
    callback
)
```

**v3.1.1:**

```kotlin theme={null}
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:**

```kotlin theme={null}
val event = Event.Builder()
    .AddUniquePlayerId("customer-123")
    .AddEventName("purchase")
    .build()
```

**v3.1.1:**

```kotlin theme={null}
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.1.1                       |
| ------------------------ | ---------------------------- |
| `registerCustomer()`     | `initializeCustomer()`       |
| `AddUniquePlayerId()`    | `customerId()`               |
| `AddEventName()`         | `eventName()`                |
| `AddEventMetaData()`     | `eventMetaData()`            |
| `PlayerAttributes`       | `CustomerAttributes`         |
| `PlayerRegisterResponse` | `InitializeCustomerResponse` |

### 5. Push Notifications

**v2:**

```kotlin theme={null}
gameballApp.initializeFirebase()
```

**v3.1.1:**

```kotlin theme={null}
// 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)

<Info>
  v3.1.1 is fully backward compatible. Simply update the dependency version. Session Token is optional.
</Info>

<Steps>
  <Step title="Update Dependency">
    Update your `build.gradle` to use SDK v3.1.1:

    ```groovy theme={null}
    dependencies {
        implementation 'com.gameball:gameball-sdk:3.1.1'
    }
    ```
  </Step>

  <Step title="(Optional) Add Session Token">
    If enhanced security is needed, add session token to your configuration:

    ```kotlin theme={null}
    val config = GameballConfig.builder()
        .apiKey("api-key")
        .lang("en")
        .sessionToken("your-session-token")
        .build()
    ```
  </Step>

  <Step title="Test">
    Test your integration. All existing code should work unchanged.
  </Step>
</Steps>

### From v2.x to v3.1.1

<Steps>
  <Step title="Update Dependency">
    Update your `build.gradle` to use SDK v3.1.1:

    ```groovy theme={null}
    dependencies {
        implementation 'com.gameball:gameball-sdk:3.1.1'
    }
    ```
  </Step>

  <Step title="Update Initialization">
    Replace your SDK initialization code with the new `GameballConfig` builder pattern.
  </Step>

  <Step title="Update Customer Registration">
    Replace `registerCustomer()` with `initializeCustomer()` using the new request builder.
  </Step>

  <Step title="Update Event Tracking">
    Update event creation to use lowercase builder methods (e.g., `.customerId()` instead of `.AddUniquePlayerId()`).
  </Step>

  <Step title="Update Push Notifications">
    Move device token registration to customer initialization instead of separate `initializeFirebase()` call.
  </Step>

  <Step title="Test Thoroughly">
    Test all Gameball functionality to ensure the migration is successful.
  </Step>
</Steps>

## 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](https://github.com/gameballers/gb-mobile-android)
* Changelog: [https://github.com/gameballers/gb-mobile-android/blob/main/CHANGELOG.md](https://github.com/gameballers/gb-mobile-android/blob/main/CHANGELOG.md)
* Migration Guide: [https://github.com/gameballers/gb-mobile-android/blob/main/MIGRATION.md](https://github.com/gameballers/gb-mobile-android/blob/main/MIGRATION.md)
* Release Notes: [https://github.com/gameballers/gb-mobile-android/blob/main/RELEASE\_NOTES.md](https://github.com/gameballers/gb-mobile-android/blob/main/RELEASE_NOTES.md)
* Developer Docs: [https://developer.gameball.co](https://developer.gameball.co)

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

## Next Steps

* [Getting Started](/installation-guides/v3/android/getting-started)
* [Go-Live Checklist](/installation-guides/v3/android/go-live-checklist)