This package has been deprecated

Author message:

This project has been renamed. Install using react-native-verint-xm-sdk instead.

react-native-foresee-sdk

React Native ForeSee SDK is a wrapper around the ForeSee iOS and ForeSee Android SDKs, providing ForeSee 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-foresee-sdk in your React Native app.

Requirements

• react: 17.0.2
• react-native: 0.66.4
• Android: 21+
• iOS: 11.0+
• ForeSee SDK
  • iOS 6.0.6
  • Android 6.0.3

Installation

$ npm install react-native-foresee-sdk

Building Locally

First, clone this repo:

$ git clone https://github.com/foreseecode/react-native-foresee-sdk.git

And install dependencies:

$ cd react-native-foresee-sdk
$ npm install
$ cd ios && pod update && cd ..

Pack the extension for use

$ npm pack

This should output an archive file:

npm notice === Tarball Details ===
npm notice name:          react-native-foresee-sdk
npm notice version:       1.0.0
npm notice filename:      react-native-foresee-sdk-2.0.0.tgz
npm notice package size:  489.8 MB
npm notice unpacked size: 809.1 MB
npm notice shasum:        62405678c49021457ccdf86dd005c7307e729007
npm notice integrity:     sha512-jtpHyTsAHZp9s[...]SVBiyoQ3x6iBQ==
npm notice total files:   6204
npm notice
react-native-foresee-sdk-2.0.0.tgz

This package can be installed in your application:

npm install <path_to>/react-native-foresee-sdk-2.0.0.tgz --save

Running the included example

Install the react modules in the example app's root dir:

$ cd example
$ npm install

Then install the packed module to your local test app:

$ npm install ../react-native-foresee-sdk-2.0.0.tgz --save

iOS

Install the Pods:

$ cd ios && pod update && cd ..

And run it:

$ npx react-native run-ios

Android

The Android example requires no additional setup. To run it:

$ npx react-native run-android

Configuration and instrumentation

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

The easiest way to start the ForeSee SDK in a React Native application is to pass your config directly in JavaScript. Here's an example with a minimal sample configuration:

const foreSeeConfig = {
  "clientId": "FSRTESTINGCODECID12345==",
  "notificationType": "IN_SESSION",
  "measures":
  [
      {
          "surveyId": "iphone_app_QA",
          "launchCount": 0,
          "surveyStyle": "modern"
      }
  ],
  "invite": {
      "logo": "foresee_logo",
      "baseColor": [237, 38, 54]
  }
}

ForeSee.start(foreSeeConfig);

Note: There is a known issue with starting the SDK in JavaScript on Android devices that prevents the capturing of state until the application has been backgrounded and re-foregrounded at least once. For this reason, we currently recommend starting the ForeSee SDK in native code (see section below), especially for apps that support Android. We're working on a fix that will be available in a future version of the SDK.

Some details about this config:

1. This config specifies a single measure (in the measures section) for the client FSRTESTINGCODECID12345==.
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 foresee_logo to be centered on the invitation.

Styling the invitation

The invite section of the config controls the appearance of survey invitations in your app. The logo (and an optional header) field specifies an image that must be available to the native module (in other words, these images should be added as resources in the native portions of your app). More information about this section can be found on the ForeSee Developer Portal (iOS | Android).

Starting the SDK in native code (optional)

Note: This section can be skipped if you're starting the ForeSee SDK using the method described above.

In the simplest case, you'll start the SDK from JavaScript as described above. In more complicated apps (especially apps that include a lot of native code), you may want to be sure that the SDK is started as soon as possible, so that all page loads are captured, and to provide the most control over when an invite is displayed.

The upside of instrumenting the SDK in native code is that it gives you the highest level of control over when to start tracking. The downside is that more configuration is required. This section describes those requirements.

iOS

1. Open your project's .xcworkspace and add a file called foresee_configuration.json. Paste your configuration into this file. See the ForeSee Developer Portal for documentation on all available options in this file.

2. You should also include a logo and an optional header image for your invite, as specified in the invite portion of the ForeSee config. Add these images to your project.

3. Next, start the SDK in your AppDelegate's application:didFinishLaunchingWithOptions::

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     // ...
     [ForeSee start]; // will load foresee_configuration.json
     // ...
     return YES;
   }

   See the ForeSee Developer Portal for all available start methods and options.

Android

1. Add a file called foresee_configuration.json to your app's Android project and paste your configuration into this file. (See the sample above.) See the ForeSee Developer Portal for documentation on all available options in this file.

2. You should also include a logo and an optional header image for your invite, as specified in the invite portion of the ForeSee config. Add these images to your project.

3. Next, start the SDK in your MainApplication.java's (android/app/src/main/java/com/<project-name>/MainApplication.java) onCreate method:

   @Override
   public void onCreate() {
       super.onCreate();
       // ...
       ForeSee.start(this); // will load foresee_configuration.json
   }

   See the ForeSee Developer Portal for all available start methods and options.

Usage

Import the module:

import { ForeSee } from 'react-native-foresee-sdk'

All available methods are documented in ForeSee.js. Each of these methods has a direct analog in the native SDKs and full documentation for each one can be found on the ForeSee Developer Portal (iOS | Android).

Some of the more common methods are documented here.

Starting the SDK

const config = {/* ... */};
ForeSee.start(config);

If no configuation object is specified, then the SDK will look for a file called foresee_configuration.json in your native projects.

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 foresee_configuration.json:

ForeSee.checkEligibility()

Debugging

The following methods can be used in a development environment to debug invites:

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

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

Showing an invite by ID

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

ForeSee.showInvite("iphone_app_QA");

Showing a survey by ID

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

ForeSee.showSurvey("iphone_app_QA");

Handling lifecycle events

The ForeSee SDK sends a number of invite 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 ForeSee SDK Lifecycle events:

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

Note: The last two events listed here -- onInviteCancelledWithNetworkError and onInviteNotShownWithNetworkError -- currently only fire on Android devices (i.e. they'll never occur when running on iOS).

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

const foreseeEmitter = new NativeEventEmitter(ForeSee);
foreseeEmitter.addListener(
  'onInvitePresented',
  (event) => console.log("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 ForeSee SDK's version like this:

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

getVersion();

Capturing page views

The ForeSee 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 ForeSee SDK to count a new page view like this:

ForeSee.incrementPageViews();