React Native 4.+ migration guide

Upgrading version

Increase the dependency version in your package.json file to upgrade your Qonversion SDK to the latest

"react-native-qonversion": "^4.0.0"


Qonversion React Native SDK 4 contains significant changes in how the library is initialized. We are moving from a static class approach to an instance-based one. Before, you initialized Qonversion using the launchWithKey call:

Qonversion.launchWithKey('projectKey', true);

Now, instead, you should create a QonversionConfig object using QonversionConfigBuilder and provide it to the initialization method as follows:

const config = new QonversionConfigBuilder(

Note that instead of providing the observeMode flag to the launchWithKey call, you now should provide a concrete value from the LaunchMode enum depending on which mode you use Qonversion. Also, we've renamed our modes to make them clearer for users:

  • "Observe" mode becomes "Analytics" mode,
  • "Infrastructure" mode becomes "Subscription Management" mode.

After the initialization, you can access the Qonversion instance whenever you want as follows:


So you should replace all your Qonversion calls with the construction above.

Also, if you were using Qonversion.setDebugMode() for testing purposes, you should now call the setEnvironment(Environment.SANDBOX) method of the QonversionConfigBuilder.

As no launchWithKey method is available anymore, you won't get LaunchResult as a result. The good news is that there are analogues for all the fields you might have been using from there:

  • for uid, call userInfo() and get the User.qonversionId from the result,
  • for products call products(),
  • for offerings call offerings(),
  • for permissions, call checkEntitlements().


We are on the way to renaming permissions to entitlements as this naming suits more what it is used for. So, the following objects and methods were renamed in this release:

Version <4Version 4+

The Entitlement class contains the same information as the Permission with a renaming of the permissionId field - now it's named simply id. Also, the startedDate and expirationDate fields were converted from number to Date.

There is no setPermissionsCacheLifetime method in Qonversion. You should provide EntitlementsCacheLifetime to QonversionConfigBuilder during the initialization using the setEntitlementsCacheLifetime method.

const config = new QonversionConfigBuilder(

Automation changes

We've also changed the way the Automations is used. As in Qonversion, you should use Automations via the shared instance. On the first access, it will be initialized and returned. Then the initialized instance will be used.


You should access the shared instance of Automations strictly after you initialize Qonversion, else an exception will be thrown.

const config = new QonversionConfigBuilder(

Also, the methods for working with push notifications were moved from Qonversion to Automations, so if you were using the following methods:

  • setNotificationsToken,
  • handleNotification,
  • getNotificationCustomPayload,
    make sure to make calls from the Automations instance instead of the Qonversion one.

Rest of the changes

Along with the changes described above, there are several technical improvements and other changes in the new major release:

  • all the internal classes were moved to the internal package, and DTO classes were moved to the dto package to make the library file structure more readable;
  • the deprecated methods resetUser and setUserId were removed.
    resetUser was deprecated for a long time, and it did nothing, so there is nothing to replace this call with, remove the call if you were still using it for some reason. setUserId should be replaced with the setProperty call with UserProperty.CUSTOM_USER_ID parameter.
  • the experiments method was removed along with the ExperimentInfo and ExperimentGroup classes - we are now working on a new design of A/B experiments;
  • added the new method userInfo, which returns the information about the current Qonversion user. Now it contains internal Qonversion and identity identifiers. The user info may be extended in future releases;
  • added new enum values - OfferingTag.UNKNOWN and TrialDuration.UNKNOWN, which are used when parsing fails;
  • the Property and Provider enum values were changed from numbers to strings;
  • the deprecated Provider.APPLE value was removed, consider using Provider.APPLE_SEARCH_ADS instead;
  • the following methods, classes, and values renamings took place:
Old nameNew name