Numbers Probably Matter

    react-native-foresee-sdk

    2.0.0 • Public • Published

    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();

    Keywords

    Install

    npm i react-native-foresee-sdk

    DownloadsWeekly Downloads

    5

    Version

    2.0.0

    License

    SEE LICENSE IN LICENSE.md

    Unpacked Size

    1.72 MB

    Total Files

    102

    Last publish

    Collaborators

    • wayne.burkett