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 - 21
  • Supported targetSDKVersion - 33

iOS

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

Installation

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 "https://pkgs.dev.azure.com/Synerise/AndroidSDK/_packaging/prod/maven/v1"
     }

   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

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

  return packages;
}

Setting up iOS

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

2. From your ios directory, run pod install

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()
  .withClientApiKey('YOUR_PROFILE_API_KEY') // 1
  .withRequestValidationSalt('YOUR_REQUEST_VALIDATION_SALT') // 2
  .withDebugModeEnabled(false) // 3
  .withCrashHandlingEnabled(true) // 4
  .init();

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:

Synerise.Initializer()
  .withClientApiKey('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

Synerise.Initializer()
  .withBaseUrl("YOUR_API_BASE_URL")
  .withClientApiKey('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.

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.