React Native SDK

Getting Started

If you haven't yet set up a React-Native project, do the following:

First install node and react:

brew install node
brew install watchman
npm install -g react-native-cli

import Taplytics from 'taplytics-react-native';

react-native init projectname
cd projectname
npm install

Install the taplytics-react-native package:

Install taplytics-react-native npm package:
- npm install taplytics-react-native --save
Then link the taplytics-react-native native module. (for iOS you will need to manually link the module to your XCode project as described below)
- react-native link taplytics-react-native

iOS Setup

Follow the react-native manual linking native library instructions
- project to import is located in /node_modules/taplytics-react-native/ios/RNTaplyticsReact.xcodeproj
- you can skip step 3 of the instructions.
Simply follow part 1 of the install instructions to install the Native Taplytics iOS SDK. Use CocoaPods if you use it for your project or the manual install instructions. iOS SDK installation docs here.

Android Setup

Append the taplytics-react-native project settings.gradle include line:

include 'app:', ':taplytics-react-native'

add the following line to settings.gradle:

project(':taplytics-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/taplytics-react-native/android')

In your app-level build.gradle add the following your dependencies:

compile project(':taplytics-react-native')

Note that React Native is packaged with an older version of OkHttp, so an older version of socketio is required:

debugCompile ('io.socket:socket.io-client:0.8.0') {
    exclude group: 'org.json', module: 'json'
}

In your app-level build.gradle, add this the Taplytics url to your repositories:

repositories {                                                                                              
	maven { url "https://github.com/taplytics/Taplytics-Android-SDK/raw/master/AndroidStudio/" }
}

In your Application Class (default is MainApplication), add Taplytics to your app's packages:

@Override
protected List<ReactPackage> getPackages() {
  return Arrays.asList(
      new MainReactPackage(),
      new TaplyticsReactPackage()
  );
}

Follow part 1. Installation and part 2. Initialization from the Android SDK docs.

Import Taplytics into your React Native App

This module wraps most native SDK methods in Javascript, allowing you to access features such as dynamic variables, code blocks and event logging in the React Native environment.

Be sure to import Taplytics into your react application:

import Taplytics from 'taplytics-react-native';

Follow the Experiment and the Push Notification docs to start making Experiments and sending Push Notifications to your users.

You can get started with using Taplytics React-Native in minutes. Just follow the steps below.

Experiments

1. Setting User Attributes

It's possible to send custom user attributes to Taplytics using a JSONObject of user info.

The possible fields are:

Parameter	Type
email	String
user_id	String
firstname	String
lastname	String
name	String
age	Number
gender	String

You can also add anything else you would like to this JSONObject and it will also be passed to Taplytics.

An example with custom data:

Taplytics.setUserAttributes({
    "email": "[email protected]",		
    "name": "John Doe",
    "age": 25,
    "gender": "male",
    "avatarurl": "https://someurl.com/someavatar.png",
    "customData": {
        "someCustomAttribute": 50,
        "paidSubscriber": true,
        "subscriptionPlan": "yearly"
    }
});

User Attributes on First Launch

User Attributes set before startTaplytics is called will be used for experiment segmentation on the first session of your app. Any attributes that are set after startTaplytics is called will not be used for experiment segmentation until the next session of your app.

Resetting user attributes or Logging out a user

Once a user logs out of your app, their User Attributes are no longer valid. You can reset their data by calling resetAppUser, make sure you do not set any new user attributes until you receive the callback.

Taplytics.resetAppUser();

Retrieving Session Info

Taplytics also offers a method to retrieve select information of what you know about a session at a given time. This method returns the user's Taplytics identifier (appUser_id) and current session id (session_id)

Taplytics.getSessionInfo().then((results) => {
    // use results map
});

2. Track Events

Automatic Events

Some events are automatically tracked by Taplytics and will appear on your dashboard. These events are:

App Start
App background

No changes are needed in your code for this event tracking to occur.

Currently the react SDK does not support automatic tracking of page changes. This is in the works.

Custom Events

To log your own events, simply call Taplytics.logEvent.

Due to the nature of React Native, you must supply all three parameters of Name, value, and custom attributes.

If you do not wish to pass these in, simply do the following:

Taplytics.logEvent("event name", 0, {});

Otherwise

Taplytics.logEvent("eventName", 5, {"custom attribute": "something"})

Revenue Logging

It's also possible to log revenue.

Revenue logging is the same as event logging, only call logRevenue:

var someRevenue = 10000000;  
Taplytics.logRevenue("Revenue Name", someRevenue, {});

And similarly, with custom object data:

var someRevenue = 10000000;
var customInfo = {"custom attribute": "something"};
Taplytics.logRevenue("Revenue Name", someRevenue, customInfo);

3. Dynamic Variables & Code Blocks

To see and modify these variables or blocks on the dashboard, the app must be launched and this code containing the variable or block must be navigated to at least once.

The code below is used to send the information of the variable or block to Taplytics, so it will appear on the dashboard.

Dynamic Variables

Taplytics variables are values in your app that are controlled by experiments. Changing the values can update the content or functionality of your app. Variables are reusable between experiments and operate in one of two modes: synchronous or asynchronous.

You can use both sync and async variables from within Javascript.

However, because React Native uses an asynchronous communication link to native code, both these types of variables require a callback to retrieve their value.

Synchronous Dynamic Variables

Synchronous variables are guaranteed to have the same value for the entire session and will have that value immediately after construction.

Synchronous variables take two parameters in its constructor:

Variable name
Default Value
Promise

The type of the variable will be inferred from the type of value passed in as the default. This method returns a promise which resolves with the value of the synchronous variable:

Taplytics.newSyncVariable("My Variable", "default").then(value => {
  // do something
});

IMPORTANT: The value of these variables will be determined immediately, ie. the SDK will not wait for properties to be loaded from the server. Thus, if you want to ensure that the variables have their correct variables based on your experiment segmentation, you must initialize them after the properties have been loaded from the server. This module provides a callback to achieve this:

Taplytics.propertiesLoadedCallback().then(() => {
  // load variables here
});

Asynchronous Dynamic Variables

Asynchronous variables take care of insuring that the experiments have been loaded before returning a value. This removes any danger of tainting the results of your experiment with bad data. What comes with the insurance of using the correct value is the possibility that the value will not be set immediately. If the variable is constructed before the experiments are loaded, you won't have the correct value until the experiments have finished loading. If the experiments fail to load, then you will be given the default value, as specified in the variables constructor.

Asynchronous variables take three parameters in its constructor:

Variable name
Default Value
Variable Callback

To create an async variable:

Taplytics.newAsyncVariable(name, defaultValue, variableChangedCallback);

The third parameter is a function which will be called any time the value of the variable is changed. It is passed the current value of the variable. When the variable's value has been updated, the listener will be called with that updated value. You can specify what you want to do with the variable inside the callback.

Code Blocks

Similar to Dynamic Variables, Taplytics has an option for 'Code Blocks'. Code blocks are linked to Experiments through the Taplytics website very much the same way that Dynamic Variables are, and will be executed based on the configuration of the experiment through the Taplytics website. A Code Block is a callback that can be enabled or disabled depending on the variation. If enabled, the code within the callback will be executed. If disabled, the variation will not get the callback.

A Code Block can be used alongside as many other Code Blocks as you would like to determine a combination that yields the best results. Perhaps there are three different Code Blocks on one activity. This means there could be 8 different combinations of Code Blocks being enabled / disabled on that activity if you'd like.

You can register Javascript functions as code blocks to be run or not depending on your experiment variation:

Taplytics.runCodeBlock(name, someFunction);

By default, a code block will not run unless enabled on the Taplytics Dashboard. It must be enabled for a Variation before it will run.

4. List Running Experiments and Variables

Variables

To make it easier to keep track of your variables, this module also provides a method to retrieve an object map of their names and values:

Taplytics.getVariables();

which returns the variables in the format:

{
  "name1": value1,
  "name2": value2
  ...
}

This object will always contain the latest value of every Taplytics variable that has been initialized from Javascript

You can also register a function to be called whenever this object changes:

Taplytics.registerVariablesChangedListener(callback);

The callback will be passed the same object map as above. Only one callback function can be registered at a time. Calling this method again will overwrite the old callback.

Running experiments and variations

If you would like to see which variations and experiments are running on a given device, there exists a getRunningExperimentsAndVariations function which provides a callback with a map of the current experiments and their running variation. An example:

Taplytics.getRunningExperimentsAndVariations().then((results) => {
    // use results map
});

NOTE: This function runs asynchronously, as it waits for the updated properties to load from Taplytics' servers before returning the running experiments.

If you want to see when the experiments have been loaded by Taplytics, you can wrap this in a propertiesLoadedCallback

Taplytics.propertiesLoadedCallback(() => {
	Taplytics.getRunningExperimentsAndVariations().then((results) => {
   		// use results map
	});
});

5. Sessions

StartNewSession

To manually force a new user session (ex: A user has logged in / out), there exists

Taplytics.startNewSession();

This method returns a promise that resolves when the session has been created

You can also register a callback to be run when Taplytics creates a new session:

Taplytics.setTaplyticsNewSessionListener(callback);

Retrieving Session Info

Taplytics.getSessionInfo().then((results) => {
    // use results map
});

Push Notifications

Setting up Push Notifications

Due to the nature of push notifications and their dependencies on the specific platforms, setup for each individual platform must be performed natively.

Push Event Listeners

It's possible to attach listeners to the three push notification events handled by the Taplytics SDK. These are push received, push dismissed and push opened. Use the following three methods:

Taplytics.registerPushOpenedListener((value) => {
   // Do something
})
Taplytics.registerPushReceivedListener((value) => {
  // Do something
})
//Only available on android
Taplytics.registerPushDismissedListener((value) => {
  // Do something
})

You can register multiple callbacks for the same event, and all will be executed.

Before these event listeners trigger, push notifications must be set up fully on each respective platform.

iOS

To register for push notifications, it is possible to do so by calling:

// iOS available only
Taplytics.registerPushNotifications()

To set up push notifications on iOS natively, please follow the documentation here:
iOS SDK - Push Notifications

Other Push Event Listeners
On iOS, its also possible to use the built-in React Native push notification module, which can be found here

Android

If you wish to use Push Notifications on Taplytics, you must add the following permissions (replace com.yourpackagename with your app's package name) to your Android Manifest:

<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<permission android:name="com.yourpackagename.permission.C2D_MESSAGE"/>
<uses-permission android:name="com.yourpackagename.permission.C2D_MESSAGE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

And you must add the following receiver and service under your application tag:

<receiver
    android:name="com.taplytics.react.TRNBroadcastReceiver"
    android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    </intent-filter>

    <intent-filter>
         <action android:name="taplytics.push.OPEN" />
         <action android:name="taplytics.push.DISMISS" />
    </intent-filter>
</receiver>
<service android:name="com.taplytics.sdk.TLGcmIntentService" />

Then add the following to your build.gradle:

compile("com.google.android.gms:play-services-gcm:9.+")

Rich Push, Advanced Usage, and more Android Push Features
To see more push features available to android, please view the Android push documentation.
Android SDK - Push Notifications

Feature Flags

Taplytics feature flags operate in synchronous mode. Synchronous feature flags are guaranteed to have the same value for the entire session and will have that value immediately after construction.

Taplytics featureFlagEnabled("featureFlagKey").then(isEnabled => {
    if (isEnabled) {
      // Put feature code here, or launch feature from here
    }
  });

IMPORTANT: The value of featureFlagEnabled will be determined immediately, ie. the SDK will not wait for properties to be loaded from the server. Thus, if you want to ensure that the variables have their correct variables based on your experiment segmentation, you must initialize them after the properties have been loaded from the server. This module provides a callback to achieve this:

Taplytics.propertiesLoadedCallback(() => {
  Taplytics featureFlagEnabled("featureFlagKey").then(isEnabled => {
      if (isEnabled) {
        // Put feature code here, or launch feature from here
      }
    });
});

Running Feature Flags

If you would like to see which feature flags are running on a given device, there exists a getRunningFeatureFlags() function which provides a callback with the current feature flags' names and their associated key. An example:

Taplytics.getRunningFeatureFlags().then((results) => {
    // use results map
});

NOTE: The block can return asynchronously once Taplytics properties have loaded. The block will return a WritableMap with feature flag name as the key value, and feature flag key as the value.