Skip to main content

​
title: “Migration Notes” description: “Migrate from v2 to v3.1.1”

​
Migration Notes & Changelog

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

​
What’s New in v3.1.1

Guest Mode & Easier Widget Init — v3.1.1 makes ShowProfileRequest non-throwing and allows customerId to be optional so you can launch the profile widget in guest mode.
  • customerId optional on profile widget (guest mode supported)
  • Existing v3.1.0/v3.0.0 code continues to work without changes

​
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

TypeScript Support

Full TypeScript support with type definitions and interfaces

Async/Await

Modern async/await support alongside callback pattern

Better Error Handling

Improved error messages and validation

Simplified API

Cleaner API design with consistent patterns

​
Breaking Changes

​
1. SDK Initialization

v2: 
import {GameballSDK} from 'react-native-gameball';

GameballSDK.init("api-key", "en", "platform", "shop");
v3.1.1: 
import { GameballApp, GameballConfig } from 'react-native-gameball';

const config: GameballConfig = {
  apiKey: 'api-key',
  lang: 'en',
  platform: 'react-native',
  shop: 'shop-id',
  sessionToken: 'session-token',  // Optional - New in v3.1.0
};

GameballApp.getInstance().init(config);

​
2. Customer Registration

v2: 
GameballSDK.registerPlayer({
  playerUniqueId: "customer-123",
  deviceToken: "token",
  referrerCode: "ref",
  playerAttributes: {...}
});
v3.1.1: 
const request: InitializeCustomerRequest = {
  customerId: 'customer-123',
  deviceToken: 'token',
  referralCode: 'ref',
  customerAttributes: {...},
};

await GameballApp.getInstance().initializeCustomer(request);

// Optional: Override session token for this request (updates global token)
await GameballApp.getInstance().initializeCustomer(request, undefined, 'custom-token');

​
3. Event Tracking

v2: 
GameballSdk.sendEvent({"review": {}})
    .then(response => console.log(response))
    .catch(error => console.log(error));
v3.1.1: 
const event: Event = {
  customerId: 'customer-123',
  events: {
    review: {
      rating: 5
    }
  },
};

await GameballApp.getInstance().sendEvent(event);

// Optional: Override session token for this request (updates global token)
await GameballApp.getInstance().sendEvent(event, undefined, 'custom-token');

​
4. Show Profile Widget

v2: 
import {GameballWidget} from 'react-native-gameball';

<GameballWidget 
  modal={true}
  ref={ref}
/>
v3.1.1: 
import { GameballApp, ShowProfileRequest } from 'react-native-gameball';

const profileRequest: ShowProfileRequest = {
  customerId: 'customer-123', // Optional (omit for guest mode)
  showCloseButton: true,
};

await GameballApp.getInstance().showProfile(profileRequest);

// Optional: Override session token for this request (updates global token)
await GameballApp.getInstance().showProfile(profileRequest, undefined, 'custom-token');

​
5. Key Naming Changes

v2v3.1.x
playerUniqueIdcustomerId
playerAttributescustomerAttributes
referrerCodereferralCode
GameballSDKGameballApp.getInstance()
GameballSdk.sendEventGameballApp.getInstance().sendEvent

​
Migration Steps

​
From v3.1.0 to v3.1.1 (No Breaking Changes)

v3.1.1 is a patch release (guest mode support). Update the dependency version; no code changes required.
1

Update Dependency

Update your package.json to use SDK v3.1.1:
{
  "dependencies": {
    "react-native-gameball": "^3.1.1"
  }
}
Run npm install or yarn install, then cd ios && pod install.
2

Test Guest Mode (Optional)

If you plan to use guest mode, verify that showProfile works without a customerId.
3

Test

Test your integration. All existing code should work unchanged.

​
From v3.0.0 to v3.1.x (No Breaking Changes)

v3.1.x is fully backward compatible. Simply update the dependency version. Session Token is optional.
1

Update Dependency

Update your package.json to use SDK v3.1.1:
{
  "dependencies": {
    "react-native-gameball": "^3.1.1"
  }
}
Run npm install or yarn install, then cd ios && pod install.
2

(Optional) Add Session Token

If enhanced security is needed, add session token to your configuration:
const config: GameballConfig = {
  apiKey: 'api-key',
  lang: 'en',
  sessionToken: 'your-session-token',
};
Important: In React Native SDK, the sessionToken parameter updates the global token when passed to any method.
3

Test

Test your integration. All existing code should work unchanged.

​
From v2.x to v3.1.1

1

Update Dependency

Update your package.json to use SDK v3.1.1:
{
  "dependencies": {
    "react-native-gameball": "^3.1.1"
  }
}
Run npm install or yarn install, then cd ios && pod install.
2

Update Imports

Update all Gameball imports to use react-native-gameball:
import { GameballApp } from 'react-native-gameball';
3

Update Initialization

Replace SDK initialization with the new config object pattern.
4

Update Customer Registration

Replace registerPlayer with initializeCustomer using the new request structure.
5

Update Event Tracking

Update event structure to use events object with nested properties.
6

Update Profile Widget

Replace GameballWidget component with showProfile method calls.
7

Add Type Definitions

If using TypeScript, add type annotations to leverage full type safety.
8

Test on Both Platforms

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

​
Compatibility

  • React Native: 0.70+
  • Node.js: 18+
  • TypeScript: 4.0+ (optional)
  • iOS: iOS 12.0+
  • Android: API level 21+

​
Additional Resources

For version-specific details, refer to the gameball-react-native repository on branch release-3.1.1.
If you encounter any issues during migration, check the GitHub repository for known issues and solutions, or contact Gameball support.

​
Next Steps