Skip to main content

​
Migration Notes & Changelog

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

​
What’s New in v3.1.1

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.

​
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: 
Gameball.init(
  "api-key",
  "en",
  "flutter",
  "shop-id"
);
v3.1.1: 
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): 
Gameball.registerPlayer(
  playerId,
  email,
  mobile,
  attributes,
);
v3.1.1: 
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: "custom-token"
);

​
3. Event Tracking

v2: 
Gameball.sendEvent({
  "playerId": "player-123",
  "event": "purchase",
  "metadata": {...}
});
v3.1.1: 
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: 
Gameball.showProfile(context, "player-123");
v3.1.1: 
final profileRequest = ShowProfileRequestBuilder()
    .customerId("customer-123")
    .showCloseButton(true)
    .build();

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

​
Migration Steps

1

Update Dependency

Update your pubspec.yaml to use SDK v3.1.1:
dependencies:
  gameball_sdk: ^3.1.1
Run flutter pub get and cd ios && pod install.
2

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);
3

Update Customer Registration

Use InitializeCustomerRequestBuilder and CustomerAttributesBuilder:
final request = InitializeCustomerRequestBuilder()
    .customerId("id")
    .customerAttributes(attributes)
    .build();
4

Update Event Tracking

Use EventBuilder with chained methods:
final event = EventBuilder()
    .customerId("id")
    .eventName("purchase")
    .eventMetaData("key", value)
    .build();
5

Update Show Profile

Use ShowProfileRequestBuilder for showing profile:
final request = ShowProfileRequestBuilder()
    .customerId("id")
    .build();
6

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

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

​
Next Steps