How Do I Migrate to the React Native SDK v4?

Upgrade from v3 to v4.0.0, or migrate from v2 to v3

Migration Notes & Changelog

This guide helps you upgrade from Gameball React Native SDK v3 to v4.0.0, and migrate from v2 to v3.

What’s New in v4.0.0

Breaking change: iOS 15.0 and Android API 24 minimums. v4.0.0 raises the minimum supported platform versions to iOS 15.0 and Android API 24 (Android 7.0). Every v3.x call keeps its signature and behavior, so no TypeScript code changes are required.

New Features in v4.0.0

• In-App Messaging: mount <GameballInAppMessages /> once, then startInAppMessaging() displays the slide-up, modal, and full-screen campaigns you create in the Gameball dashboard, and stopInAppMessaging() stops it on logout. Nothing runs until you call startInAppMessaging, so upgrading without it changes nothing. See In-App Messaging
• In-App Messaging Hooks: beforeDisplay, onAction, onNavigate, openUrl, and requestPushPermission, plus onInAppMessage(listener) and setOverlayOpen(open)
• Purchase Logging: logPurchase() sends a purchase event to Gameball that campaigns can target and filter on
• Optional Peer Dependency: when your app has react-native-safe-area-context, in-app messages sit exactly clear of the notch and the home indicator

Migrate v3.x → v4.0.0 (Breaking)

• Set minSdkVersion to 24 in android/build.gradle.
• Set the iOS deployment target to 15.0 in ios/Podfile (platform :ios, '15.0') and in Xcode, then run pod install.
• Update to react-native-gameball@^4.0.0.
• Coming from v3.1.x or earlier, install the peer dependencies the SDK has required since v3.3.1. The Install Peer Dependencies step below lists them.
• (Optional) Adopt in-app messaging. See In-App Messaging.
• (Optional) If you build purchase events yourself, replace them with logPurchase rather than sending both.

Coming from v3.1.x? v4.0.0 also includes v3.3.1, which brought the React Native SDK level with the other SDKs’ 3.3.x releases: widget events and dismissal (widgetEventCallback and hideProfile()), external link handling (externalLinkCallback), per-call and global widget language (lang and setLanguage), and push notification click tracking (handlePushClick). initializeCustomer now always registers customers, with isGuest ignored, and changeLanguage is deprecated in favor of setLanguage. See the release history.

---

What’s New in v3.1.2

Widget Loading Fix & Custom Modal — v3.1.2 fixes a widget loading delay caused by srcdoc iframe blocking and replaces the profile widget’s modal with a custom animated implementation.

• Fixed widget loading delay caused by about:blank iframe origin not being whitelisted
• Widget WebView now reloads on re-open to ensure fresh content
• Replaced react-native-modal in profile widget with a custom Animated slide-up modal
• Lazy WebView rendering — widget is not rendered until first open, improving initial load performance
• Existing v3.1.1/v3.1.0/v3.0.0 code continues to work without changes

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.2:

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.2:

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, 'customer-token');

3. Event Tracking

v2:

GameballSdk.sendEvent({"review": {}})
    .then(response => console.log(response))
    .catch(error => console.log(error));

v3.1.2:

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, 'customer-token');

4. Show Profile Widget

v2:

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

<GameballWidget 
  modal={true}
  ref={ref}
/>

v3.1.2:

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, 'customer-token');

5. Key Naming Changes

v2	v3.1.x
playerUniqueId	customerId
playerAttributes	customerAttributes
referrerCode	referralCode
GameballSDK	GameballApp.getInstance()
GameballSdk.sendEvent	GameballApp.getInstance().sendEvent

Migration Steps

From v3.x to v4.0.0

1. Raise Platform Minimums

   Set minSdkVersion to 24 in android/build.gradle, and the iOS deployment target to 15.0:

   # ios/Podfile
   platform :ios, '15.0'
   

   Also set IPHONEOS_DEPLOYMENT_TARGET to 15.0 for your app target in Xcode.

2. Update Dependency

   Update your package.json to use SDK v4.0.0:

   {
     "dependencies": {
       "react-native-gameball": "^4.0.0"
     }
   }
   
3. Install Peer Dependencies

   Coming from v3.1.x or earlier, install the peer dependencies the SDK requires:

   npm install @react-native-async-storage/async-storage react-native-device-info react-native-modal react-native-push-notification-popup react-native-webview
   

   Run npm install or yarn install, then cd ios && pod install.

4. (Optional) Adopt In-App Messaging

   Mount <GameballInAppMessages /> once near the root of your app, call startInAppMessaging() once the customer is known, and call stopInAppMessaging() on logout. See In-App Messaging.

5. Test

   Verify that initializeCustomer, sendEvent, and showProfile behave as before on both iOS and Android. Unable to resolve module react-native-webview or a similar error means a peer dependency is missing.

From v3.1.1 to v3.1.2 (No Breaking Changes)

v3.1.2 is a patch release (widget loading fix + custom modal). Update the dependency version; no code changes required.

1. Update Dependency

   Update your package.json to use SDK v3.1.2:

   {
     "dependencies": {
       "react-native-gameball": "^3.1.2"
     }
   }
   

   Run npm install or yarn install, then cd ios && pod install.

2. Test

   Test your integration. All existing code should work unchanged. The profile widget no longer uses react-native-modal internally, but the dependency is still required by in-app notifications.

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.2:

   {
     "dependencies": {
       "react-native-gameball": "^3.1.2"
     }
   }
   

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

1. Update Dependency

   Update your package.json to use SDK v3.1.2:

   {
     "dependencies": {
       "react-native-gameball": "^3.1.2"
     }
   }
   

   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 15.0+ as of v4.0.0
• Android: API level 24+ (Android 7.0) as of v4.0.0

Additional Resources

• Check the SDK repository’s CHANGELOG.md for detailed version history
• Review MIGRATION.md in the repository for more migration details
• View RELEASE_NOTES.md for v4.0.0 release details
• Visit Gameball Docs for the latest documentation

For version-specific details, refer to the gameball-react-native repository on branch release-4.0.0.

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

Next Steps

• Getting Started
• Initialize SDK
• Go-Live Checklist