cordova-plugin-verint-xm-sdk

Verint XM Cordova Plugin

Requirements

• cordova-android: 11.0.0+
• cordova-ios: 6.2.0+
• Android: 22+
• iOS: 12.0+
• Verint-XM SDK
  • iOS 7.4.0
  • Android 7.4.0

API Docs

Full API Docs can be found here

Setting up the plugin

To set up the plugin in your app, follow these instructions

1. Set up the required environment variables

   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 obtain the 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 plugin'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.

2. Add the Verint XM Cordova Plugin to your project from NPM:

   cordova plugin add cordova-plugin-verint-xm-sdk
   

   This will automatically add compile "com.verint.xm.sdk:*:+" to your build.gradle file. It will also copy the exp_configuration.json file to platform/ios and platform/android if they exist

   If you have a copy of this repo on disk, then you can also add the plugin to your app by pointing directly to it, like this:

   cordova plugin add <PATH_TO_THE_PLUGIN_REPO> --nofetch
   

3. Within the deviceready event handler initialize the Verint-XM SDK by invoking

   cordova.plugins.verint.xm.start(this.onSuccess, this.onFailure);
   

4. Now you can use cordova.plugins.verint.xm in your JavaScript code. For example:

   cordova.plugins.verint.xm.checkEligibility(this.onSuccess, this.onFailure);
   

5. For all supported methods please check the API docs included in this package, or online here. For general information about the Verint SDK, please see the Verint Developer Portal.

6. Add exp_logo.png file in your www/img/ folder to include a logo for the survey.

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 tell the SDK to start-up using that ID by placing it in the root of your project in a file named startup_configuration.json with the following structure:

{
    "siteKey":"<YOUR_SITE_KEY>"
}

Please ensure the startup_configuration.json is added to the resource folder of the platform. You could do this manually by coping startup_configuration.json to the resource folder each time after adding the platform. But there is an automated way to do this, with use of the config.xml API. In this example the origin startup_configuration.json file exists in the root of the project; if you store resources in another location, just make sure to provide the actual path in src:

<?xml ... ?>
    ...
    <platform name="android">
        ...
        <resource-file src="startup_configuration.json" target="app/src/main/res/raw/startup_configuration.json"/>
        ...
    </platform>
    <platform name="ios">
        ...
        <resource-file src="startup_configuration.json" target="startup_configuration.json"/>
        ...
    </platform>
</widget>

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.

A complete config with those values looks like this:

{
    "siteKey":"<YOUR_SITE_KEY>",
    "configurationContainer":"<CONFIGURATION_CONTAINER>"
}

configurationContainer is an optional value; it should be added only if a non-default value is in use.

Legacy configuration

Previous versions of the SDK loaded configurations from a legacy tool called FCP, which could be configured in a file called exp_fcp.json in the following format:

{
    "appId": "<YOUR_APP_ID>"
}   

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 by placing your config in a file called exp_configuration.json file in your app's www folder. Here's a minimal example:

{
    "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":"Cordova Readme Sample"
	}
}

Note
For more information please check Configuration Options

Usage

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:

• Cordova plugin API Docs
• Native Android SDK API Docs
• Native iOS SDK API Docs

Starting the SDK

The SDK does not need to be manually started, it will be started whenever the plugin is loaded:

• If your app includes a startup_configuration.json file with your Site Key, then it will start automatically with your Verint-hosted config from Configurator.
• If your app includes an exp_fcp.json file with your App ID, then it will start automatically with your Verint-hosted config from FCP.
• Otherwise, if you have included a local config in an exp_configuration.json file, the SDK will start using that.

Checking eligibility and showing an invite

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

cordova.plugins.verint.xm.checkEligibility(_onSuccess, _onFailure);

Showing an invite by name

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

cordova.plugins.verint.xm.showInvite("app_test_1", _onSuccess, _onFailure);

Showing a survey by name

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

cordova.plugins.verint.xm.showSurvey("app_test_1", _onSuccess, _onFailure);

Showing a Survey Management invite for name

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

cordova.plugins.verint.xm.showInviteForName("SampleSurvey", _onSuccess, _onFailure);

Showing a Survey Management survey for name

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

cordova.plugins.verint.xm.showSurveyForName("SampleSurvey", _onSuccess, _onFailure);

Handling local notifications on Android

The EXIT_SURVEY and EXIT_INVITE notification modes use local notifications to send surveys to the user. There are two requirements to enable notifications in Cordova on Android:

1. The permission android.permission.POST_NOTIFICATIONS must be listed in your application Manifest.
2. The cordova-plugin-android-permissions plugin is used to request the permission. Since Android 13 you need to explicitly request the user to enable the permission for your app.

Adding the permission to your app

When you add the Verint plugin to your app and build android using commands below the permission will automatically be added to you app manifest.

$ cordova plugin add https://github.com/foreseecode/verint-xm-cordova-plugin

$ cordova platform add android

Note: You can also manually add the permission by adding the following line to your application manifest:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Request runtime permission using the cordova-plugin-android-permissions plugin

Add the plugin to your project:

cordova plugin add cordova-plugin-android-permissions

See example code for requesting the runtime permission in your app’s Javascript:

var app = {
    // Application Constructor
    initialize: function() {
        document.addEventListener('deviceready', this.onDeviceReady.bind(this), false);
    },
    onDeviceReady: function() {
        // Request permissions for Android 33
        if (device.platform == "Android") {
            var permissions = cordova.plugins.permissions;

            permissions.hasPermission(permissions.POST_NOTIFICATIONS, function (status) {
                if (status.hasPermission) {
                    // Permission has been granted previously, no need to request it again.
                } else {
                    var error = function () {
                        // Permission has been denied.
                        console.warn('permission has been denied');
                    };

                    var success = function (status) {
                        if (!status.hasPermission) {
                            // Permission has been denied.
                            error();
                        } else {
                            console.warn('permission has been granted');
                        }
                    };

                    // Request the permission to allow notifications.
                    permissions.requestPermission(permissions.POST_NOTIFICATIONS, success, error);
                }
            })
        }
    }
}    

Limitations

There is an issue where notifications will not appear until the app is backgrounded and foregrounded at least once when building the app locally from the local command line.

This will not affect users who download the app from Play Store or other distribution methods.

Handling local notifications on iOS

The EXIT_SURVEY and EXIT_INVITE notification modes use local notifications to send surveys to the user. There are two ways to handle notifications in Cordova on iOS:

1. In your app’s native iOS classes
2. Using the cordova-plugin-local-notification plugin

Native classes

Import UserNotifications and adopt the UNUserNotificationCenterDelegate protocol

#import <Cordova/CDVViewController.h>
#import <Cordova/CDVAppDelegate.h>
#import <UserNotifications/UserNotifications.h>

@interface AppDelegate : CDVAppDelegate <UNUserNotificationCenterDelegate>
@end

Register self as the UNUserNotificationCenterDelegate

[UNUserNotificationCenter currentNotificationCenter].delegate = self;

Handle incoming notifications

#pragma mark - UNUserNotificationCenterDelegate

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
didReceiveNotificationResponse:(UNNotificationResponse *)response
         withCompletionHandler:(nonnull void (^)(void))completionHandler
{
  [EXPPredictive showSurveyForNotificationResponse:response];
  completionHandler();
}

Using the cordova-plugin-local-notification plugin

Add the plugin to your project:

cordova plugin add cordova-plugin-local-notification

And then handle notifications in your app’s Javascript:

if (device.platform == "iOS") {
    cordova.plugins.notification.local.on("click", function (notification) {
        if (notification.EXPLocalNotificationMeasureKey != null) {
            cordova.plugins.verint.xm.showSurvey([notification.EXPLocalNotificationMeasureKey], this.onSuccess, this.onFailure);
        }
    }, this);
}

Limitations

There is a documented negative interaction when using this plugin alongside other Cordova plugins that use local notifications (e.g. Firebase Cloud Messaging.) This can cause a crash in apps that use both plugins.

The issue has been raised in the cordova-plugin-local-notification repository, but has no updates at the time of writing. (This issue seems to appear between the beta.2 and beta.3 versions.)

As of this moment, there is not a known workaround, and we suggest using the CONTACT notification method, instead, if you are a user of one of those other plugins.

Handling lifecycle events

The SDK sends a number of lifecycle events during typical operation.

Predictive and Survey Management Events

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

Digital Events

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

Add or Remove Predictive/Survey Management Events

Use setInviteListener(success, error) and removeInviteListener(success, error) to add/remove listeners for Predictive or Survey Management events.

Add listeners for Predictive/Survey Management events:

cordova.plugins.verint.xm.setInviteListener(function success(data) {
    console.log("Invite listener event:" + data.event + ", SID: " + data.surveyId);
}, function failure(data) {
    console.log("Fail: " + data);
});

Remove listeners for Predictive/Survey Management events:

cordova.plugins.verint.xm.removeInviteListener(this.onSuccess, this.onFailure);

Add or Remove Digital Events

Use setDigitalListener(success, error) and removeDigitalListener(success, error) to add/remove listeners for Digital events.

Add listeners for Digital events:

cordova.plugins.verint.xm.setDigitalListener(function success(data) {
    console.log("Digital listener event:" + data.event);
}, function failure(data) {
    console.log("Fail: " + data);
});

Remove listeners for Digital events:

cordova.plugins.verint.xm.removeDigitalListener(this.onSuccess, this.onFailure);

Troubleshooting

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

Reset the state of the SDK (clear all criteria counts):

cordova.plugins.verint.xm.resetState(_onSuccess, _onFailure);

Enable additional native console logging:

cordova.plugins.verint.xm.setDebugLogEnabled(true, _onSuccess, _onFailure);

Enable remote event logging:

cordova.plugins.verint.xm.setEventLogEnabled(true, _onSuccess, _onFailure);

Skip server-side pooling checks (i.e. show an invite to anyone eligible):

cordova.plugins.verint.xm.setSkipPoolingCheck(true, _onSuccess, _onFailure);

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

API Documentation generation

The JSDoc tool is used to generate API documentaion. Make sure to update documentation after any API changes. See: https://github.com/jsdoc/jsdoc

License

Apache License, Version 2.0 https://www.apache.org/licenses/LICENSE-2.0