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

# Migration Notes & Changelog

This guide helps you migrate from Gameball Flutter 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 adds guest-mode support for the profile widget (customerId optional). Session tokens from 3.1.0 remain supported.
</Info>

### New Features in v3.1.1

* **Guest Mode Support**: Profile widget can open without customerId
* **Non-Throwing ShowProfileRequest**: customerId 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
* **Global Token Management**: Token updates globally when passed to any method
* **Backward Compatible**: All v3.0.0 code works unchanged

<CardGroup cols={2}>
  <Card title="Improved API" icon="code">
    Cleaner API design with better error handling and null safety
  </Card>

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

  <Card title="Flutter 3.x Support" icon="flutter">
    Full compatibility with Flutter 3.x and latest Firebase plugins
  </Card>

  <Card title="Enhanced Type Safety" icon="shield">
    Better Dart null safety support and compile-time checks
  </Card>
</CardGroup>

## Breaking Changes

### 1. SDK Initialization

**v2:**

```dart theme={null}
Gameball.init(
  "api-key",
  "en",
  "flutter",
  "shop-id"
);
```

**v3.1.1:**

```dart theme={null}
final config = GameballConfigBuilder()
    .apiKey("api-key")
    .lang("en")
    .platform("flutter")
    .shop("shop-id")
    .sessionToken("session-token")  // Optional
    .build();

final gameballApp = GameballApp.getInstance();
gameballApp.init(config);
```

### 2. Customer Registration

**v2 (legacy):**

```dart theme={null}
Gameball.registerPlayer(
  playerId,
  email,
  mobile,
  attributes,
);
```

**v3.1.1:**

```dart theme={null}
final attributes = CustomerAttributesBuilder()
    .displayName("John Doe")
    .email(email)
    .mobile(mobile)
    .build();

final request = InitializeCustomerRequestBuilder()
    .customerId(playerId)
    .customerAttributes(attributes)
    .build();

GameballApp.getInstance().initializeCustomer(request, (response, error) {
  // Handle response
});

// Optional: Override session token for this request (updates global token)
GameballApp.getInstance().initializeCustomer(
  request,
  (response, error) {
    // Handle response
  },
  sessionToken: "customer-token"
);
```

### 3. Event Tracking

**v2:**

```dart theme={null}
Gameball.sendEvent({
  "playerId": "player-123",
  "event": "purchase",
  "metadata": {...}
});
```

**v3.1.1:**

```dart theme={null}
final event = EventBuilder()
    .customerId("customer-123")
    .eventName("purchase")
    .eventMetaData("amount", 99.99)
    .eventMetaData("currency", "USD")
    .build();

GameballApp.getInstance().sendEvent(event, (success, error) {
  // Handle response
});
```

### 4. Show Profile Widget

**v2:**

```dart theme={null}
Gameball.showProfile(context, "player-123");
```

**v3.1.1:**

```dart theme={null}
final profileRequest = ShowProfileRequestBuilder()
    .customerId("customer-123")
    .showCloseButton(true)
    .build();

GameballApp.getInstance().showProfile(context, profileRequest);
```

## Migration Steps

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

    ```yaml theme={null}
    dependencies:
      gameball_sdk: ^3.1.1
    ```

    Run `flutter pub get` and `cd ios && pod install`.
  </Step>

  <Step title="Update Initialization">
    Replace initialization with `GameballConfigBuilder()` pattern:

    ```dart theme={null}
    final config = GameballConfigBuilder()
        .apiKey("your-api-key")
        .lang("en")
        .platform("flutter")
        .shop("your-shop-id")
        .build();

    final gameballApp = GameballApp.getInstance();
    gameballApp.init(config);
    ```
  </Step>

  <Step title="Update Customer Registration">
    Use `InitializeCustomerRequestBuilder` and `CustomerAttributesBuilder`:

    ```dart theme={null}
    final request = InitializeCustomerRequestBuilder()
        .customerId("id")
        .customerAttributes(attributes)
        .build();
    ```
  </Step>

  <Step title="Update Event Tracking">
    Use `EventBuilder` with chained methods:

    ```dart theme={null}
    final event = EventBuilder()
        .customerId("id")
        .eventName("purchase")
        .eventMetaData("key", value)
        .build();
    ```
  </Step>

  <Step title="Update Show Profile">
    Use `ShowProfileRequestBuilder` for showing profile:

    ```dart theme={null}
    final request = ShowProfileRequestBuilder()
        .customerId("id")
        .build();
    ```
  </Step>

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

## Compatibility

* **Minimum Flutter Version**: 1.17.0 (3.0+ recommended)
* **Dart**: 3.4.4+
* **Android**: API level 21+, targetSdkVersion 34
* **iOS**: iOS 12.0+

## Additional Resources

* Check the [SDK repository's CHANGELOG.md](https://github.com/gameballers/gameball-flutter/blob/main/CHANGELOG.md) for detailed version history
* Review [MIGRATION.md](https://github.com/gameballers/gameball-flutter/blob/main/MIGRATION.md) in the repository for more migration details
* View [RELEASE\_NOTES.md](https://github.com/gameballers/gameball-flutter/blob/main/RELEASE_NOTES.md) for v3.1.1 release details
* Visit [Gameball Developer Docs](https://developer.gameball.co) for the latest documentation

<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/flutter/getting-started)
* [Initialize SDK](/installation-guides/v3/flutter/initialize-sdk)
* [Go-Live Checklist](/installation-guides/v3/flutter/go-live-checklist)