Migration Notes & Changelog

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

What’s New in v3.2.0

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.

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.

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.

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.

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

Improved API

Cleaner API design with better error handling and null safety

Better Performance

Optimized SDK initialization and reduced package size

Flutter 3.x Support

Full compatibility with Flutter 3.x and latest Firebase plugins

Enhanced Type Safety

Better Dart null safety support and compile-time checks

Breaking Changes

1. SDK Initialization

v2:

gameballApp.init("api-key", "en", "flutter", "shop-id");

v3.2.0:

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:

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:

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:

Event eventBody = Event(
  customerId: "customerId",
  events: {
    "purchase": {"amount": "100.00"},
  },
);

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

v3.2.0:

final event = EventBuilder()
    .customerId("customer-123")
    .eventName("purchase")
    .eventMetaData("amount", 99.99)
    .eventMetaData("currency", "USD")
    .build();

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

v2:

gameballApp.showProfile(
  context,
  "customerId",
  "openDetail",
  hideNavigation,
  showCloseButton,
);

v3.2.0:

final profileRequest = ShowProfileRequestBuilder()
    .customerId("customer-123")
    .showCloseButton(true)
    .build();

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

Migration Steps

Update Dependency

Update your pubspec.yaml to use SDK v3.2.0:

dependencies:
  gameball_sdk: ^3.2.0

Run flutter pub get and cd ios && pod install.

Update Initialization

Replace initialization with GameballConfigBuilder() pattern:

final config = GameballConfigBuilder()
    .apiKey("your-api-key")
    .lang("en")
    .platform("flutter")
    .shop("your-shop-id")
    .build();

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

Update Customer Registration

Use InitializeCustomerRequestBuilder and CustomerAttributesBuilder:

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

Update Event Tracking

Use EventBuilder with chained methods:

final event = EventBuilder()
    .customerId("id")
    .eventName("purchase")
    .eventMetaData("key", value)
    .build();

Update Show Profile

Use ShowProfileRequestBuilder for showing profile:

final request = ShowProfileRequestBuilder()
    .customerId("id")
    .build();

Test Thoroughly

Test all Gameball functionality on both iOS and Android to ensure the migration is successful.

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 for version history and release notes
Visit Gameball Developer Docs for the latest documentation

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 Flutter SDK v3?

Migration Notes & Changelog

What’s New in v3.2.0

New Features in v3.2.0

Dependency Constraints in v3.2.0

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

New Features in v3.1.1

Improved API

Better Performance

Flutter 3.x Support

Enhanced Type Safety

Breaking Changes

1. SDK Initialization

2. Customer Registration

3. Event Tracking

4. Show Profile Widget

Migration Steps

Compatibility

Additional Resources

Next Steps

​Migration Notes & Changelog

​What’s New in v3.2.0

​New Features in v3.2.0

​Dependency Constraints in v3.2.0

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

​New Features in v3.1.1

Improved API

Better Performance

Flutter 3.x Support

Enhanced Type Safety

​Breaking Changes

​1. SDK Initialization

​2. Customer Registration

​3. Event Tracking

​4. Show Profile Widget

​Migration Steps

​Compatibility

​Additional Resources

​Next Steps

Migration Notes & Changelog

What’s New in v3.2.0

New Features in v3.2.0

Dependency Constraints in v3.2.0

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

New Features in v3.1.1

Breaking Changes

1. SDK Initialization

2. Customer Registration

3. Event Tracking

4. Show Profile Widget

Migration Steps

Compatibility

Additional Resources

Next Steps