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

# How Do I Migrate to the Flutter SDK v3?

> Migrate from v2 to v3.2.0

# Migration Notes & Changelog

This guide helps you migrate from Gameball Flutter SDK v2 to v3.2.0.

## What's New in v3.2.0

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

### New Features in v3.2.0

* **Widget Event Channel**: `ShowProfileRequestBuilder().widgetEventCallback(...)` receives events posted from the widget, such as `gameCompleted`
* **Host-Initiated Dismiss**: `GameballApp.getInstance().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**: `ShowProfileRequestBuilder` accepts optional `mobile` and `email`
* **Diagnostic Logging**: the SDK records internal diagnostic logs to aid troubleshooting. No integration changes required

### Dependency Constraints in v3.2.0

`share_plus`, `device_info_plus`, and `package_info_plus` constraints were widened. The lower bounds are unchanged, so existing apps resolve the same versions and nothing breaks on upgrade.

<Note>
  Apps that opt into `share_plus` 13.x require Flutter 3.38.1+ and Dart 3.10+. Staying on your current `share_plus` version needs no action.
</Note>

### Migrate v3.1.x → v3.2.0 (Non-Breaking)

* Update `pubspec.yaml` to `gameball_sdk: ^3.2.0`, then run `flutter pub get`.
* No code changes are required. Adopt the new widget capabilities only if you need them — see [Show Profile Widget](/installation-guides/v3/flutter/show-profile).

***

### 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}
gameballApp.init("api-key", "en", "flutter", "shop-id");
```

**v3.2.0:**

```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:**

```dart theme={null}
CustomerAttributes customerAttributes = CustomerAttributes(
  displayName: "John Doe",
  mobileNumber: "0123456789",   // Note: was mobileNumber
  customAttributes: {"city": "New York"},
);

gameballApp.registerCustomer(
  "customerId",
  "customer@example.com",
  "1234567890",
  "abc123",   // referralCode
  false,      // isGuest
  (response, error) {
    // Handle response
  },
);
```

**v3.2.0:**

```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}
Event eventBody = Event(
  customerId: "customerId",
  events: {
    "purchase": {"amount": "100.00"},
  },
);

gameballApp.sendEvent(eventBody, (success, error) {
  // Handle response
});
```

**v3.2.0:**

```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}
gameballApp.showProfile(
  context,
  "customerId",
  "openDetail",
  hideNavigation,
  showCloseButton,
);
```

**v3.2.0:**

```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.2.0:

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

    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 [gameball-flutter releases page](https://github.com/gameballers/gameball-flutter/releases) for version history and release notes
* Visit [Gameball Developer Docs](https://docs.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)