> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# How Do I Migrate to the React Native SDK v4?

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

# Migration Notes & Changelog

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

## What's New in v4.0.0

> [!WARNING]
>
> **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](https://docs.gameball.co/installation-guides/v4/react-native/in-app-messaging.md)
* **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](https://docs.gameball.co/installation-guides/v4/react-native/in-app-messaging.md).
* (Optional) If you build `purchase` events yourself, replace them with `logPurchase` rather than sending both.

> [!NOTE]
>
> **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](https://github.com/gameballers/gameball-react-native/releases).

***

## What's New in v3.1.2

> [!NOTE]
>
> **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

> [!NOTE]
>
> **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

> [!NOTE]
>
> **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

> [card] TypeScript Support
>
> Full TypeScript support with type definitions and interfaces

> [card] Async/Await
>
> Modern async/await support alongside callback pattern

> [card] Better Error Handling
>
> Improved error messages and validation

> [card] Simplified API
>
> Cleaner API design with consistent patterns

## Breaking Changes

### 1. SDK Initialization

**v2:**

```typescript theme={null}
import {GameballSDK} from 'react-native-gameball';

GameballSDK.init("api-key", "en", "platform", "shop");
```

**v3.1.2:**

```typescript theme={null}
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:**

```typescript theme={null}
GameballSDK.registerPlayer({
  playerUniqueId: "customer-123",
  deviceToken: "token",
  referrerCode: "ref",
  playerAttributes: {...}
});
```

**v3.1.2:**

```typescript theme={null}
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:**

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

**v3.1.2:**

```typescript theme={null}
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:**

```typescript theme={null}
import {GameballWidget} from 'react-native-gameball';

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

**v3.1.2:**

```typescript theme={null}
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:

```ruby theme={null}
# 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:

```json theme={null}
{
  "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:

```bash theme={null}
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](https://docs.gameball.co/installation-guides/v4/react-native/in-app-messaging.md).

**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)

> [!NOTE]
>
> 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:

```json theme={null}
{
  "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)

> [!NOTE]
>
> 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:

```json theme={null}
{
  "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)

> [!NOTE]
>
> 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:

```json theme={null}
{
  "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:

```typescript theme={null}
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 v4.0.0

**1. Raise Platform Minimums**

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

```ruby theme={null}
# 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:

```json theme={null}
{
  "dependencies": {
    "react-native-gameball": "^4.0.0"
  }
}
```

**3. Install Peer Dependencies**

Install the peer dependencies the SDK requires:

```bash theme={null}
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. Update Imports**

Update all Gameball imports to use `react-native-gameball`:

```typescript theme={null}
import { GameballApp } from 'react-native-gameball';
```

**5. Update Initialization**

Replace SDK initialization with the new config object pattern.

**6. Update Customer Registration**

Replace `registerPlayer` with `initializeCustomer` using the new request structure.

**7. Update Event Tracking**

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

**8. Update Profile Widget**

Replace `GameballWidget` component with `showProfile` method calls.

**9. Add Type Definitions**

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

**10. 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](https://github.com/gameballers/gameball-react-native/blob/release-4.0.0/CHANGELOG.md) for detailed version history
* Review [MIGRATION.md](https://github.com/gameballers/gameball-react-native/blob/release-4.0.0/MIGRATION.md) in the repository for more migration details
* View [RELEASE\_NOTES.md](https://github.com/gameballers/gameball-react-native/blob/release-4.0.0/RELEASE_NOTES.md) for v4.0.0 release details
* Visit [Gameball Docs](https://docs.gameball.co/) for the latest documentation

> [!WARNING]
>
> For version-specific details, refer to the [gameball-react-native repository](https://github.com/gameballers/gameball-react-native/tree/release-4.0.0) on branch `release-4.0.0`.

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

## Next Steps

* [Getting Started](https://docs.gameball.co/installation-guides/v4/react-native/getting-started.md)
* [Initialize SDK](https://docs.gameball.co/installation-guides/v4/react-native/initialize-sdk.md)
* [Go-Live Checklist](https://docs.gameball.co/installation-guides/v4/react-native/go-live-checklist.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.