react-native-verint-xm-sdk v3.0.1

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: 18.2.0
• react-native: 0.71.7
• Android: 21+
• iOS: 12.4+
• Verint-XM SDK
  • iOS 7.1.1

  • Android 7.1.2

Prerequisites

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

Installation

$ npm install react-native-verint-xm-sdk

Building locally

Building locally should only be attempted by Verint engineers. The process is described here

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 easiest way to start the SDK in a React Native application is to use Verint-Hosted configuration, which can be accessed using your App ID. If you don’t have an App ID, please contact your Verint Account Manager to have an App ID 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 App ID, you can start the SDK by calling VerintXM.startWithAppId in your app.js:

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

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

    // ..other code..

}

You also have the option to 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
If you would like to know more about manually configuring your app, please ask Verint Support.

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

Usage

Import the module:

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

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.startWithAppId("<YOUR_APP_ID>")

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

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

Digital

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

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

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

Which logs the following output:

{"event": "onInvitePresented"}

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 like this:

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