Skip to main content

​
Migration Notes & Changelog

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

​
What’s New in v3.1.0

Session Token Authentication — v3.1.0 introduces optional Session Token authentication for enhanced security with automatic v4.1 endpoint routing.

​
New Features in v3.1.0

  • Session Token Support: Optional token-based authentication
  • 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 existing 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.0: 
final config = GameballConfig.builder()
    .apiKey("api-key")
    .lang("en")
    .platform("flutter")
    .shop("shop-id")
    .sessionToken("session-token")  // Optional - New in v3.1.0
    .build();

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

​
2. Customer Registration

v2: 
Gameball.registerPlayer(
  playerId,
  email,
  mobile,
  attributes,
);
v3.1.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: "custom-token");

​
3. Event Tracking

v2: 
Gameball.sendEvent({
  "playerId": "player-123",
  "event": "purchase",
  "metadata": {...}
});
v3.1.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
});

​
4. Show Profile Widget

v2: 
Gameball.showProfile(context, "player-123");
v3.1.0: 
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.0:
dependencies:
  gameball_flutter: ^3.1.0
Run flutter pub get and cd ios && pod install.
2

Update Initialization

Replace initialization with GameballConfig.builder() pattern:
final config = GameballConfig.builder()
    .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

For v3.1.0-specific details, refer to the gameball-flutter repository on branch release-3.1.0.
If you encounter any issues during migration, check the GitHub repository for known issues and solutions, or contact Gameball support.

​
Next Steps