README
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: 16.9.0
- react-native: 0.61.4
- Android: 21+
- iOS: 11.0+
- ForeSee SDK
- iOS 5.3.5
- Android 5.3.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 install
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-1.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-1.0.0.tgz
This package can be installed in your application:
npm install <path_to>/react-native-foresee-sdk-1.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-1.0.0.tgz --save
iOS
Install the Pods:
$ cd ios
$ pod install
And run it:
$ cd ..
$ 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:
- This config specifies a single measure (in the
measures
section) for the clientFSRTESTINGCODECID12345==
. - 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. - If the user accepts the invitation they'll see a survey directly in the app (
"notificationType": "IN_SESSION"
). - The invitation will be styled according to the
invite
section. The SDK will try to load an image calledforesee_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
Open your project's
.xcworkspace
and add a file calledforesee_configuration.json
. Paste your configuration into this file. See the ForeSee Developer Portal for documentation on all available options in this file.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.Next, start the SDK in your
AppDelegate
'sapplication: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
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.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.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();