Installation and configuration (React Native)

In this article, you will find out how to install and initialize the Synerise SDK in a React Native mobile application. While performing the actions from this guide, keep the presented order presented.

Important: The Settings article contains additional information about SDK behaviors you may need prior to configuration.


You need:

  • Access to a workspace
  • A Profile API Key
    When creating the API key, use allowlisting or denylisting to only allow the events you intend to use.


  • Recommended environment:
    • Minimum Android SDK version - 21
    • Supported targetSDKVersion - 33


  • Recommended environment:
    • Xcode 15
    • iOS SDK 17
  • Target deployment: iOS 9.0+


Installing the React Native module

  1. Install the module with npm:
       npm install react-native-synerise-sdk --save
  2. Follow the rest of the instruction depending on the React Native version you use:
    0.60 or lower

    1. Install the native dependencies by using CocoaPods from your ios directory:
      pod install
    2. In your android build.gradle top-level build file, add:
    maven {
      url ""

    Higher than 0.60

    1. Link the native dependency.
      react-native link react-native-synerise-sdk
    2. Install from your iOS:
      pod install --repo-update

Setting up Android

  1. In your app’s build.gradle file, add the following dependency: implementation 'com.synerise.sdk.react:react-native-synerise-sdk:RN_SDK_VERSION'
    where RN_SDK_VERSION is the SDK version. You can check the latest version in our Github repository.
  2. In the app’s main class, to your list of packages, add RNSyneriseSdkPackage
protected List<ReactPackage> getPackages() {
  List<ReactPackage> packages = new PackageList(this).getPackages();
  packages.add(new RNSyneriseSdkPackage());;

  return packages;

Setting up iOS

Note: Starting from React Native 0.60, CocoaPods is the default integration approach for React Native iOS projects.
  1. In your ios/Podfile, add the following dependency: pod 'react-native-synerise-sdk', :path => '../node_modules/react-native-synerise-sdk'
    Result: Your Podfile looks as follows:
        target 'YourTarget' do
        # Pods for your target
        pod 'React', :path => '../node_modules/react-native/'
        pod 'React-Core', :path => '../node_modules/react-native/React'
        # ... other React dependencies
        # Add react-native-synerise-sdk
        pod 'react-native-synerise-sdk', :path => '../node_modules/react-native-synerise-sdk'
  2. From your ios directory, run pod install
Note: If you prefer linking manually, check React Native - Linking Libraries to link your libraries that contain native code.


When you use the react-native-synerise-sdk module, use the following native Synerise SDK frameworks:

Importing Synerise SDK

You will need to import the Synerise object from the react-native-synerise-sdk module.

import { Synerise } from 'react-native-synerise-sdk';
Note: You must always import suitable objects from the react-native-synerise-sdk module into the files that contain the code that relates to the Synerise SDK.

Basic initialization

Initialize the Synerise SDK and provide the Profile API Key.

You may initialize it wherever you want and when you need.

  .withClientApiKey('YOUR_PROFILE_API_KEY') // 1
  .withRequestValidationSalt('YOUR_REQUEST_VALIDATION_SALT') // 2
  .withDebugModeEnabled(false) // 3
  .withCrashHandlingEnabled(true) // 4
  1. .withClientApiKey('YOUR_PROFILE_API_KEY') - Sets Profile API Key for Synerise SDK initialization.
  2. .withRequestValidationSalt('YOUR_REQUEST_VALIDATION_SALT') - Sets salt string for request validation.
  3. .withDebugModeEnabled(false) - Enables debug mode. See Debug mode section for more information.
  4. .withCrashHandlingEnabled(true) - Enables crash handling. Synerise SDK sends a crash event automatically when an uncaught exception occurs.

Initialization with custom API environment

You can change the base URL of the API for on-premise installations.

Use the following initialization method:


Advanced initialization

This is an example of advanced initialization with:

  • custom API base URL for on-premise installations
  • request validation salt configured
  • debug mode enabled
  • crash handling enabled
  • most settings options available
  • initialization listeners set
Important: Secure sensitive keys (for example, clientApiKey and requestValidationSalt) with mechanisms like string obfuscation or encryption.
    sdk: {
      enabled: true,
      minTokenRefreshInterval: 5000,
      shouldDestroySessionOnApiKeyChange: true
    notifications: {
      enabled: true,
      encryption: false,
    injector: {
      automatic: true,
    tracker: {
      isBackendTimeSyncRequired: true,
      minBatchSize: 20,
      maxBatchSize: 30,
      autoFlushTimeout: 60

Synerise.onReady(function() {
  // This function is called when Synerise is fully initialized and ready.

Synerise.onError(function(error) {
  // This function is called when an error occurs during Synerise initialization.

Debug mode

You can enable debug logs for Synerise SDK by using the .withDebugModeEnabled(true) method in Synerise.Initializer when you initialize the SDK.

WARNING: Do not use debug mode in a release version of your application.

You can receive logs about:

  • Core: push notifications
  • Tracker: auto-tracked events, declarative events, sending process
  • Client: customer state, authorization
  • Injector: campaigns
  • Promotions: promotions, vouchers
  • Content: content widget, documents, recommendations

Main Synerise listeners

You can handle Synerise SDK initialization result by two listener methods:

  • Synerise.onReady() - This method is called when Synerise is initialized.
  • Synerise.onError(error: Error) - This method is called when an error occurs during Synerise initialization.

You can specify your custom action when a customer clicks a simple push, banner or walkthrough. Synerise SDK implements two main actions that a customer may invoke - open URL and Deeplink:

  • IInjectorListener.onOpenUrl(url: string) - This method is called when Synerise handles the open URL action from campaign activities.
  • IInjectorListener.onDeepLink(deepLink: string) - This method is called when Synerise handles the deeplink action from campaign activities.
Note: For more information about handling actions from the Synerise SDK, see the Campaigns section.

When you want to deal with Push Notifications:

  • INotificationsListener.onRegistrationToken?(token: string) - This method is called when a native part of the application passes a registration token.
  • INotificationsListener.onRegistrationRequired?() - This method is called when Synerise needs registration for Push Notifications.
  • INotificationsListener.onNotification(payload: object) - This method is called when a native part of the application passes a notification payload.

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.



Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker