Migrate to Playtime SDK v4

This guide explains how to migrate from older Playtime SDK versions to SDK v4. If you're starting a new integration, follow the SDK integration guide instead.

SDK v4 introduces a unified architecture and improved performance across all supported platforms.

---

Who Should Migrate

You should migrate if you are using:

• SDK ≤ v3.4.0 on Android, React Native, Flutter or Unity

• SDK 1.9.1 on iOS or React Native

Important Notice: SDK Version Deprecation

Starting August 2026, we will deprecate and fully remove support for the following SDK versions. Failure to upgrade in time may result in build failures for your app.

• Android: ≤ 3.4.0

• iOS ≤ v1.9.1

---

What Changed in v4

1. Unified SDK Architecture

SDK v4 introduces a more consistent structure across platforms.

This means:

• Similar method names

• Similar initialization flow

• Shared concepts

• Easier cross-platform support

• Unified versioning between iOS and Android

This affects:

• Android

• iOS

• Unity

• Flutter

• React Native

We've deprecated Support for Cordova and Capacitor Frameworks

---

2. Initialization Changes

Initialization has been simplified and standardized.

Before

Initialization often required:

• Multiple calls at app start and when foregrounding the app

• Conditional initialization before launching the catalog

• Manual state checks

Now

Initialization is:

• Validated by the SDK; no need to use isInitialized to check the SDK status

• Happens implicitly when PlaytimeOptions is used with showCatalog. No explicit initialization required.

• More consistent between platforms

Deprecated

Android / React Native / Flutter / Unity:

• All init functions and their overloads have been deprecated, including: Playtime.init(sdkHash, options)

iOS:

• Playtime.initialize(sdkHash, options)

New Method

• Only use this method to warm-up the SDK for faster execution of showCatalog. Otherwise, you can skip this step:

  • Playtime.setPlaytimeOptions(options: PlaytimeOptions)

---

3. Launching the Catalog

The catalog (offerwall) is now launched using a standardized method.

Before

• Multi-step process

• Dependent on an explicit initialization

Now

• Set-up reduced to two steps

• No explicit initialization required; initialization occurs implicitly when PlaytimeOptions is used with showCatalog.

New Methods

Android/iOS: Playtime.showCatalog(PlaytimeOptions: options)

Flutter /React Native / Unity: Playtime.showCatalogWithOptions(PlaytimeOptions: options)

Android only:

While getCatalogIntent is not yet deprecated, we strongly recommend using showCatalog as it supports a listener for improved error handling and crash prevention. See the implementation code here.

4. Improved Validation

SDK v4 adds stricter validation.

This means:

• (iOS only) Your Entitlements file must be set to Production .

• Your adjoe application must use the correct App ID and correct App Bundle ID for both Sandbox and Production environments.

---

Migration Steps

Most integrations can migrate in these steps.

Step 1: Update SDK Version

Update to the latest SDK version. Find the latest version here.

Step 2: Update minSdkVersion Version (Android Only)

• We've bumped our Android and minSdkVersion to 21+.

Step 3: Update Entitlements (iOS Only)

• Make sure your Entitlements file is set to Production .

Step 4: Update Initialization

• Safely remove additional and unnecessary calls to Playtime.init or Playtime.initialize at app start or when foregrounding the application.

Step 5: Update Catalog Launch

• Update code to use showCatalog or showCatalogWithOptions

• Ensure that you always pass in PlaytimeOptions with the userId and SDKHash when calling showCatalog or showCatalogWithOptions .

• Ensure the catalog launches correctly.

When you pass a parameter like uaNetwork in one request and nil in the next, the SDK retains the last set value. Ensure PlaytimeOptions is always constructed with all necessary parameters.

Step 6: Deployment & Versioning

Release a full native binary update to the Google Play Store or Apple App store.

• Ensure all users are prompted to update to the latest app version containing the new native SDK code.

• Do not use Over-the-Air (OTA) updates (e.g. CodePush, Expo Updates) for this migration. OTA updates only refresh the JS layer, leaving the old v3 native bridge behind. Attempting to use the v4 JS wrapper with a v3 native layer will result in initialization errors and app crashes.

Step 7: Test the Integration

• Check that old and new users can access the catalog without any issues.

• Check that users are able to install games and get rewards.

---

Integration Guides

For a full example, check the implementation code in the Integration Guides:

• iOS

• Android

• React Native

• Flutter

• Unity

---