react-native-verint-xm-sdk

React Native Verint SDK is a wrapper around the Verint-XM iOS and Android SDKs, providing Verint-XM integration in React Native apps. Access to native functions is provided through documented JavaScript modules, so you don't have to call any native functions directly.

Functionality is provided by a single npm package. Follow this guide to use react-native-verint-xm-sdk in your React Native app.

API Docs

Full API Docs can be found here

Requirements

• react: *
• react-native: *
• Android: 21+
• iOS: 12.0+
• Verint-XM SDK
  • iOS 7.4.0
  • Android 7.4.1

Prerequisites

Make sure React Native and required Environment configured on your machine. See: https://reactnative.dev/docs/environment-setup

Authenticating with the package repository (Android)

You will need to authenticate with GitHub Packages to download our native Android library. To do so, you'll need a personal key which can be generated from your GitHub account by following the instructions. The token will need the read:packages permission.

Once you have that key, you should set two environment variables on your machine: GITHUB_USERNAME for your username, and GITHUB_PERSONAL_KEY for your personal key. Those environment variables will be picked up by the following lines in the project's /build.gradle file:

[!IMPORTANT] Ensure to add this snippet to your Android project's /build.gradle file.

allprojects {
    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/foreseecode/public-packages")
            credentials {
                username = System.getenv("GITHUB_USERNAME")
                password = System.getenv("GITHUB_PERSONAL_KEY")
            }
        }
    }
}

See Getting Started guide for more information.

Installation

npm install react-native-verint-xm-sdk

Usage

Import the module:

import { VerintXM } from 'react-native-verint-xm-sdk'

Configuration and instrumentation

In order to use the SDK in your project you'll need a valid SDK configuration. The SDK configuration includes the required credentials to use the SDK and specifies the criteria for showing an invitation. For the most part, configuration is the same for both platforms (i.e. you'll have just one configuration that can be used on both iOS and Android). Any differences are documented on the Verint Developer Portal.

The recommended way to start the SDK is with a Verint-hosted configuration, which can be accessed using your site key. If you don’t have a site key, please contact your Verint Account Manager to have a sitekey and configuration set up. You will need to let them know the trigger conditions and invitation mode you would like to use.

Once you have your Site Key, you can start the SDK by calling VerintXM.startWithSiteKey:

class App extends Component {
    constructor(props) {
        super(props);

        // ..other code..
    
        VerintXM.startWithSiteKey("<YOUR_SITE_KEY>")
    }

    // ..other code..

}

Alternate container

By default the SDK loads your config from the production container. For testing, you may sometimes want to set an alternate configuration container, which can be done using:

VerintXM.setConfigurationContainer("draft")

The method must be called before starting the SDK.

Legacy configuration

Previous versions of the SDK loaded configurations from a legacy tool called FCP. Once you have your App ID, you can start the SDK by calling VerintXM.startWithAppId:

class App extends Component {
    constructor(props) {
        super(props);

        // ..other code..
    
        VerintXM.startWithAppId("<YOUR_APP_ID>")
    }

    // ..other code..

}

All new implementations should use the "site key" startup method described above. If you're unsure which applies to you, please check with your account manager.

Local configuration

Alternatively, you can configure your app locally and pass your config directly in JavaScript. Here's an example with a minimal sample configuration:

const sdkConfig = {
  "notificationType": "IN_SESSION",
  "invite": {
    "logo": "verint_logo",
    "baseColor": [0, 122, 255]
  },
  "survey": {
    "closeButtonColor": [255, 255, 255],
    "closeButtonBackgroundColor": [0, 122, 255],
    "headerColor": [0, 122, 255]
  },
  "surveyManagement": {
    "surveys": [
      {
        "url": "https://survey.vovici.com/se/705E3F053FB8395201",
        "name": "SampleSurvey",
        "launchCount": 0
      }
    ]
  },
  "cppParameters": {
    "sample_app":"React Native Readme Sample"
  }
}

VerintXM.start(sdkConfig);

Some details about this config:

1. This config specifies a single survey (in the surveys section) for a client using an account in the Shared Hosted system.vovici.com instance of Survey Management.
2. The measure is configued to allow a survey invitation whenever the app has been launched more than 0 times ("launchCount": 0). In other words, the user is immediately eligible to see a survey.
3. If the user accepts the invitation they'll see a survey directly in the app ("notificationType": "IN_SESSION").
4. The invitation will be styled according to the invite section. The SDK will try to load an image called verint_logo to be centered on the invitation.
5. The survey will be styled according to the survey section.

Note
For more information please check Configuration Options

Adding branding images

You should include a logo and an optional header image for your invite. You can specify the names for these images in your configuration. These images must also be added to your app's native projects (i.e. via Xcode and/or Android Studio).

For more details, see this page.

Methods

All available methods are documented in VerintXM.js. Each of these methods has a direct analog in the native SDKs and full documentation for each one can be found as follows:

• React Native API Docs
• Android API Docs
• iOS API Docs

Some of the more common methods are documented here.

Starting the SDK

VerintXM.startWithSiteKey("<YOUR_SITE_KEY>")

Always start the SDK before attempting to show an invite.

Checking eligibility and showing an invite

This method will show an invite to users who have met the criteria specified in your configuration:

VerintXM.checkEligibility()

Showing an invite by name

Force-show an invite by name (i.e. without checking eligibility):

VerintXM.showInvite("my_survey_name");

Showing a survey by name

Force-show a survey by name (i.e. without checking eligibility or showing an invitation):

VerintXM.showSurvey("my_survey_name");

Handling lifecycle events

The SDK sends a number of lifecycle events during normal operation. To be notified of these events, first import the NativeEventEmitter:

import { NativeEventEmitter, NativeModules } from 'react-native';

You can subscribe to any of the following Verint SDK Lifecycle events:

Core/Startup

"onStarted"
"onStartedWithError"
"onFailedToStartWithError"

Predictive/Survey Management

"onInvitePresented"
"onSurveyPresented"
"onSurveyCompleted"
"onSurveyCancelledByUser"
"onSurveyCancelledWithNetworkError"
"onInviteCompleteWithAccept"
"onInviteCompleteWithDecline"
"onInviteNotShownWithEligibilityFailed"
"onInviteNotShownWithSamplingFailed"

Digital

"onDigitalSurveyPresented"
"onDigitalSurveyNotPresentedWithNetworkError"
"onDigitalSurveyNotPresentedWithDisabled"
"onDigitalSurveySubmitted"
"onDigitalSurveyNotSubmittedWithNetworkError"
"onDigitalSurveyNotSubmittedWithAbort"
"onDigitalSurveyStatusRetrieved"

Custom Invites

"shouldShowCustomInvite"
"shouldHideCustomInvite"
"shouldSetInvalidInput"

For example, to be notified when an invite is presented, subscribe to the onInvitePresented event:

const emitter = new NativeEventEmitter(VerintXM.nativeModule);
emitter.addListener(
  'onInvitePresented',
  (event) => console.log(event)
);

Which logs the following output:

{"event": "onInvitePresented"}

Custom Invites

Custom Invites allow you to control the invite UI that's displayed to the user, instead of the standard invite format. To enable custom invites use:

VerintXM.setCustomInviteEnabled(true)

You must specify invitation modes other than IN_SESSION:

VerintXM.setCustomInviteEnabled(true, "CONTACT")

Custom invites work like standard invites -- the Verint SDK will continue handling all criteria tracking -- except that the Verint SDK will send an event whenever it would otherwise show an invite, which your app should handle and respond to by showing an invite of its own:

// handler for custom invite
verintEmitter.addListener(
  "shouldShowCustomInvite",
  (data) => {
    // this is where you can show your own invite UI
  });

When custom invites are enabled it's up to your app to tell the Verint SDK whenever your user has accepted or declined the invite. For accepted:

VerintXM.customInviteAccepted()

And for declined:

VerintXM.customInviteDeclined()

For CONTACT invite types that require a phone number or email address, you may also subscribe to the shouldSetInvalidInput event, which will notify your app when the Verint SDK has received invalid contact details.

Handling return values

Some SDK methods return a value to the client code. These methods use Promises to bridge the native code and JavaScript. For example, print the SDK's version:

async function getVersion() {
  try {
    var version = await VerintXM.getVersion();
    console.log(version);
  } catch (e) {
    console.error(e);
  }
}

getVersion();

Capturing page views

The SDK automatically tracks page views in native apps. Generally, a page view is counted whenever a ViewController is loaded on iOS and, similarly, whenever an Android Activity's onResume method executes.

In a React Native application you'll need to track page views manually (if you want to trigger an invite based on that criterion). A page view can be whatever makes sense for your app. Tell the SDK to count a new page view like this:

VerintXM.incrementPageViews();

Troubleshooting

The following methods can be used in a development environment to debug the SDK's behavior:

VerintXM.resetState(); // reset the state of the SDK (clear all criteria counts)
VerintXM.setDebugLogEnabled(true); // enable additional native console logging
VerintXM.setEventLogEnabled(true); // enable remote event logging
VerintXM.setSkipPoolingCheck(true); // skip server-side pooling checks (i.e. show an invite to anyone eligible)

See the Verint Developer Portal's pages on troubleshooting for more information about debugging invites.

There are also some specific issues which may affect a React Native implementation:

Local notifications don't show

There are some extra steps needed to allow local notifications to show (if you're using the Exit Invite or Exit Survey invitation modes). Follow the instructions below:

For Android

1. Your AndroidManifest.xml will need to include the correct permission at the root level:

    ```xml
    <manifest xmlns:android="http://schemas.android.com/apk/res/android">
   
        <!-- Permissions required for notifications -->
        <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
   
        <application>
            <!-- Your application details -->
        </application>
    </manifest>
    ```

2. In your app.js, add the following code snippets:

   1. Import permissions

      import { 
          PermissionsAndroid,
          } from 'react-native';

   2. Add a method to request notification permissions

      const requestNotificationPermission = async () => {
          try {
              const granted = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS);
              if (granted === PermissionsAndroid.RESULTS.GRANTED) {
                  console.log('You can post notifications');
              } else {
                  console.log('Notifications permission denied');
              }
          } catch (err) {
              console.warn(err);
          }
      };

   3. Run the method above on Android only:

      if (Platform.OS === 'android') {
          requestNotificationPermission();
      }

For iOS

1. Add the following to your AppDelegate.h so that you're implementing the UNUserNotificationCenterDelegate protocol:

    #import <UserNotifications/UNUserNotificationCenter.h>
   
    @interface AppDelegate : RCTAppDelegate <UNUserNotificationCenterDelegate>

2. Add the following imports to your AppDelegate.mm so that you're implementing the `` protocol:

    #import <UserNotifications/UNUserNotificationCenter.h>
    #import <EXPPredictive/EXPPredictive.h>

3. Add the following to your AppDelegate's didFinishLaunchingWithOptions method:

    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        // ..other code.. //
   
        [UNUserNotificationCenter currentNotificationCenter].delegate = self;
   
        return [super application:application didFinishLaunchingWithOptions:launchOptions];
    }

4. Add the following methods to fulfill the UNUserNotificationCenterDelegate protocol

   - (void)userNotificationCenter:(UNUserNotificationCenter *)center
   didReceiveNotificationResponse:(UNNotificationResponse *)response
            withCompletionHandler:(nonnull void (^)(void))completionHandler
   {
       [EXPPredictive showSurveyForNotificationResponse:response];
       completionHandler();
   }
   
   // Called when a notification is delivered to the foregrounded app
   - (void)userNotificationCenter:(UNUserNotificationCenter *)center
          willPresentNotification:(UNNotification *)notification
            withCompletionHandler:(nonnull void (^)(UNNotificationPresentationOptions))completionHandler
   {
       completionHandler(
           UNAuthorizationOptionSound 
           | UNAuthorizationOptionAlert 
           | UNAuthorizationOptionBadge);
   }
   

Issues interacting with debug builds

There is a known issue with the Flipper library in some development environments in which a hidden Flipper window interferes with the survey invite on iOS, preventing further interaction with the app. This only affects development builds and should not appear in production apps. However, it can still make debugging and testing difficult.

The only known workaround is to disable the Flipper library in the development environment with the following environment variable:

export NO_FLIPPER="1"

After re-running pod install in your ios directory, Flipper will be uninstalled and the app should work normally.