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.

Requirements

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.

Android

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

iOS

• Recommended environment:

  • Xcode 16
  • iOS SDK 18

• Target deployment:

  • iOS 13.0+ for SDK versions 1.0.0 and higher
  • iOS 9.0+ for SDK versions lower than 1.0.0
  Bitcode is not supported in SDK version 1.0.0 and higher. Xcode ignores bitcode.

Setting up Android

1. Install the module with npm:
   

   npm install react-native-synerise-sdk --save

2. Install dependencies:

   • React Native 0.60 or lower: In your android build.gradle top-level build file, add:

     ...
         allprojects {
             repositories {
                 google()
                 jcenter()
                 maven { url 'https://pkgs.dev.azure.com/Synerise/AndroidSDK/_packaging/prod/maven/v1' }
             }
         }

   • React Native newer than 0.60: Link the native dependency:
     

     react-native link react-native-synerise-sdk

3. If you DON'T use autolinking: 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.
   Doing this together with autolinking causes a build error.
4. In the app's main class, to your list of packages, add RNSyneriseSdkPackage
   
   Java

   @Override
   protected List<ReactPackage> getPackages() {
     @SuppressWarnings("UnnecessaryLocalVariable")
     List<ReactPackage> packages = new PackageList(this).getPackages();
     packages.add(new RNSyneriseSdkPackage());;
   
     return packages;
   }
   

Setting up iOS

1. Install the module with npm:
   

   npm install react-native-synerise-sdk --save

2. Install dependencies:

   • React Native 0.60 or lower: Install the native dependencies by using CocoaPods from your ios directory:

     pod install

   • React Native newer than 0.60:

     1. Link the native dependency.

        react-native link react-native-synerise-sdk

     2. Install from your iOS:
        

        pod install --repo-update

3. 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'
   
       use_native_modules!
   
       end

4. From your ios directory, run pod install
   
   If you prefer linking manually, check React Native - Linking Libraries to link your libraries that contain native code.
   

Initialization

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

• Android
• iOS

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';

Basic initialization

Initialize the Synerise SDK and provide the Profile API Key.

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

Synerise.Initializer()
  .withApiKey('YOUR_PROFILE_API_KEY') // 1
  .withRequestValidationSalt('YOUR_REQUEST_VALIDATION_SALT') // 2
  .withDebugModeEnabled(false) // 3
  .withCrashHandlingEnabled(true) // 4
  .init();

1. .withApiKey('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:

Synerise.Initializer()
  .withApiKey('YOUR_PROFILE_API_KEY')
  .withBaseUrl("YOUR_API_BASE_URL")
  .init();

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
  
  Secure sensitive keys (for example, clientApiKey and requestValidationSalt) with mechanisms like string obfuscation or encryption.
  

Synerise.Initializer()
  .withBaseUrl("YOUR_API_BASE_URL")
  .withApiKey('YOUR_PROFILE_API_KEY')
  .withRequestValidationSalt('YOUR_REQUEST_VALIDATION_SALT')
  .withDebugModeEnabled(true)
  .withCrashHandlingEnabled(true)
  .withSettings({
    sdk: {
      enabled: true,
      minTokenRefreshInterval: 5000,
      shouldDestroySessionOnApiKeyChange: true
    },
    notifications: {
      enabled: true,
      encryption: false,
    },
    injector: {
      automatic: true,
    },
    tracker: {
      isBackendTimeSyncRequired: true,
      minBatchSize: 20,
      maxBatchSize: 30,
      autoFlushTimeout: 60
    }
  })
  .init();

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.

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

  • For more information about notifications in Android SDK, see Configuring push notifications section.
  • For more information about notifications in iOS SDK, see Configuring push notifications section.
  • For more information about SDK listeners and delegates, see Listeners and delegates section.