Versions

Hybrid solutions and the FollowAnalytics SDK

Note that if you are working on a hybrid non-native solution, you will have to do some of the procedures on the native side of your app. This will be the case for OS specific as well as more advanced features. When this is necessary, we will provide the information for each platform. Each FollowAnalytics SDK for React Native are based on a native version of the SDK.

The FollowAnalytics React Native SDK includes the following version:

Integration

Minimal requirements

The FollowAnaltyics SDK for React Native works with the versions of React Native 0.58.0 and above. After adding the SDK to your project, you will need to integrate the SDK in Android and then iOS, using Gradle and CocoaPods respectively.

Installation

Install from npm

The best way to start with the SDK is to download it directly from NPM. This way it will be much faster for you to add all the new updates for the SDK. Proceed to the installation by opening the terminal in your project

  1. Install the package from npm: $ npm install react-native-followanalytics --save
  2. Link it to your project: $ react-native link react-native-followanalytics

Troubleshooting

If you encounter an error such as Error: Cannot find module 'asap/raw', run $ npm install.

Install from zip file

You can also download the SDK directly from this site. If you want to use install the SDK from the zip file, open the terminal in your project.

  1. Install the package: $ npm install PATH_FOR_THE_SDK --save
  2. Link the package to your project: $ react-native link react-native-followanalytics

Android

Android Studio and React Native

To run your app and add the SDK, it will be easier to use Android Studio. Once installed, open the android file of your Project (and not the whole project) to access Android part of your react native app.

Install with Gradle

  1. Add the FollowAnalytics nexus repository to your build.gradle repositories.
repositories {
    ...
    maven {
        url 'https://nexus.follow-apps.com/nexus/content/repositories/releases/'
    }
}
  1. Go to your app build.gradle file and add FollowAnalytics SDK Android to the dependencies:
dependencies {
    implementation (':react-native-followanalytics') // this was added automatically
    implementation "com.followapps.android:sdk:6.4.+" // <-- add this line here
}

Verify your installation

After synchronizing Gradle, many of the elements needed to use the FollowAnaltyics SDK will have been added to the project.

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

import android.app.Application;
import com.facebook.react.ReactApplication;
import com.followanalytics.reactnative.sdk.RNFollowAnalyticsPackage; // <-- This one
Note how the new RNFollowAnalyticsPackage() is returned by the getPackages() method:

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

Troubleshooting

If you use a version < 0.60.0 of React Native, you will find all this changes on MainApplication.java .

Continue on your Android Project

Now that you have installed the app to your Android project, you can continue the integration on Android following the exact procedures found on the native SDK.

iOS

Install with Cocoapods

Starting with CocoaPods

The best way to install the SDK is with CocoaPods. This will allow you to easily update the SDK when new versions are released. If you have not installed CocoaPods yet, you may refer to the this site, where you can install Cocoapods (1.1.0 or later).

Before you start, be sure to have a Podfile. You could create one by writing pod init in your terminal in your project. To open your Podfile, you could find it in your Workspace, or by writing open -a Xcode Podfile in the terminal.

Using Cocoapods, add the following to your application target on the Podfile:

use_frameworks!
pod 'FollowAnalytics', path: '../node_modules/react-native-followanalytics/ios/Frameworks'

React Native Version >= 60

Locate the RNFollowAnalytics pod in your Podfile and add "/ios" to the end of the path:

pod 'RNFollowAnalytics', :path => '../node_modules/react-native-followanalytics/ios' // Add "/ios" to the end

Run pod install to add the required dependencies.

React Native Version 58 and 59

Run pod install to add the required dependencies.

Open YourProject.xcworkspace on XCode, then expand your project and inside of it expand the Libraries groups. From there find and select the RNFollowanalytics.xcodeproj.

Choose RNFollowanalytics on Targets, go to Build Settings -> Search Paths -> Framework Search Path and add the following path:

"$(SRCROOT)/../../node_modules/react-native-followanalytics/ios/Frameworks"

Troubleshooting

If you got some error like Failed to load bundle, go to Xcode, on your root directory delete main.jsbundle then create a new empty file called main.jsbundle. After that run the following command:

react-native bundle --entry-file index.js --platform ios --dev false --bundle-output ios/main.jsbundle --assets-dest ios

Continue on you iOS project

Now that you have installed the app to your iOS project, you can continue the integration on iOS by following the exact procedures found on the native SDK:

Use your Workspace

Use the .xcworkspace file generated by CocoaPods to work on your project."

React Native project

Once you have finished with integrating the Android and iOS modules for the react native SDK, you can import it in your files. At the top of your javascript files add the following:

import FollowAnalytics from "react-native-followanalytics";

Now all the methods of the FollowAnalytics SDK will be available for you to use and you can start putting tags in your application.

Analytics

Events vs Attributes

The FollowAnalytics SDK allows you to tag both events and attributes. In this section, we explain how to utilize both of them in your app and benefit from analytics capabilities. If you are unsure about the difference, you may refer to the corresponding FAQ entry.

App logs

You can tag your app by adding logs to specific events and errors experienced by the user. These logs are then received and visible on the FollowAnalytics platform.

Logging best practices

To successfully empower your team with FollowAnalytics make sure your logs are relevant, read the Logging best practices entry in the FAQ section.

Regular, native logs

To add FollowAnalytics logs in your code, here are methods you can call from the SDK:

// Log an event/error
logEvent(name);
logError(name);

You can also add details to the events and errors

// Log an event/error with details
logEvent(name, details);
logError(name, details);

Use the name as the unique identifier of your log. Use the details to be more specific and add some context. The details allow you to associate multiple key-values for additional context.

For logging geolocations, you can use the following methods:

// Log a location coordinates
logLocationCoordinates(latitude, longitude);
logLocationPosition(position); // Takes a Position object provided by the Geolocation API

The logLocationPosition(position) method can be used to pass to FollowAnalytics SDK a position object provided by the Geolocation API.

User ID and attributes

This section covers the integration of a user ID and customer attributes. The SDK allows you to set values for attributes FollowAnalytics has predefined as well as custom attributes which you can make yourself.

You don't need a user ID to set attributes

Attributes are tied to the device when no user ID is provided. If a user ID is set, a profile is created server side and can be shared across apps.

In both cases, attributes can be used in segments and campaigns to target users.

User ID

What is a user ID?

If users can sign in somewhere in your app, you can specify their identifier to the SDK. Unique to each user, this identifier can be an e-mail address, internal client identifier, phone number, or anything else that ties your customers to you. This is what we call the user ID.

A user ID enables you to relate any event to a specific user across several devices. It is also an essential component for transactional campaigns. A common user ID enables you connect to a CRM or other external systems.

To register the user ID, use:

setUserId: function(user_id);

To remove the user ID (for example in the case of a sign out), use the same method but with null as value:

setUserId: function(null);

Predefined attributes

Predefined attributes are attributes that will be attached to default fields on your user profiles. FollowAnalytics SDK has the following properties for predefined attributes:

setFirstName(firstName);
setLastName(lastName);
setEmail(email);
setDateOfBirth(dateOfBirth) // takes a string, as React Native doesn't bridges Date types. It should have the `YYYY/MM/dd` format
setGender(FollowAnalytics.Gender.(MALE|FEMALE|OTHER);
setCountry(country);
setCity(city);
setRegion(region);
setProfilePictureUrl(profilePictureUrl);

The gender selection is as follows:

Gender: {
  MALE: 1,
  FEMALE: 2,
  OTHER: 3
};

For example, to set user Joe's city to "Paris", you would proceed as follows:

FollowAnalytics.UserAttributes.setCity("Paris");
FollowAnalytics.UserAttributes.setFirstName("Joe");

Custom attributes

In addition to predefined attributes, you can add your own custom attributes to your code.

Always double check your custom attribute types

When a value for an unknown attribute is received by the server, the attribute is declared with the type of that first value.

If you change the type of an attribute in the SDK, values might be refused server-side. Ensure the attribute types match. This could be done by comparing with the ones you have in the profile data section of the platform.

Set a custom attribute

To set your custom attributes, you can use methods that are adapted for each type:

setInteger(key, number);
setDouble(key, double);
setString(key, string);
setBoolean(key, true | false);
setDate(key, date); // takes a string (dd/MM/yyyy)
setDateTime(key, dateTime); //takes a string (MM-dd-yyyy HH:mm:ss Z)

For example, to set the user's job:

FollowAnalytics.UserAttributes.setString("occupation", "Taxi driver");
Delete a custom attribute value

You can delete the value of an attribute using its key. For example, to delete the user's job:

FollowAnalytics.UserAttributes.clear("occupation");
Set of attributes

You can add or remove an item to or from a set of attributes.

Opt-Out Analytics

What is Opt-out analytics?

The SDK can be configured to no longer track user information. This is what we call to opt out of analytics.

Once opted-out, no new data is collected, nor is it stored in the application. New session are not generated at launch and nothing is sent back to the server. This data includes the following:

  • tagged elements such as events, errors
  • new user identification and attributes
  • crash reports

When a user is opted-out of analytics, campaigns will continue to work with the following limitations:

  • No Contextual campaigns - as they depend on log tracking
  • No Transactional campaigns - as they depend on the user ID
  • No Dynamic campaigns - as they depend on users entering a segment
  • Campaigns filters will depend on old data (before the user opted-out)

All data collected before the user has opted-out is preserved within FollowAnalytics servers. This means that a user having opted-out will still receive campaigns based on data acquired before opting out (previous campaigns, existing segments, etc). The opt-in state is persisted between app starts (unless storage of the app is emptied).

Configuration

FollowAnalytics SDK is opt-in by default at the initialization of the SDK. However, you can configure it to opt-out before initialization by adding and overriding the method getOptInAnalyticsDefault() and by changing the value of this method in the configuration class.

getOptInAnalytics((error, result) => { ... }});
setOptInAnalytics(isOptIn);

GDPR

To request the data collected with FollowAnalytics SDK, use the following method :

FollowAnalytics.GDPR.requestToAccessMyData();

To delete the data that has been collected with FollowAnalytics SDK, use the following method :

FollowAnalytics.GDPR.requestToDeleteMyData();

Campaigns

Campaign basics

What we mean by campaigns are the messages that you send to your user from the FollowAnalytics platform. Currently, FollowAnalytics enables you to send two types of campaigns: push notifications and in-app campaigns. Push notifications allow you to send messages to your user's home screen, whereas an in-app is a messages that is displayed in the app while the user is actively using it.

In this section, we cover all you need for your app to receive the campaigns sent from the FollowAnalytics platform, and how you can add the features the fully take advantage of the SDK's capabilities.

Before you start, be sure that the SDK is properly initialized. This includes registration for push notifications, which is covered in the "Integration" section above.

Pausing and resuming in-app campaigns

What is pausing and resuming an in-app campaign?

Pausing campaigns are used to prevent in-app from being displayed on certain screens and views of your application. You may pause a screen of the app when it is too important, or is part of a process that is too important to be interrupted by an in-app (i.e a payment screen in the process of the user making a purchase).

When the screen is safe to display an in-app, you resume in-app campaigns. Any campaign that was supposed to be displayed when the mechanism wakes paused is stacked. It will be shown as soon as the mechanism is resumed. This way you can send send in-app campaigns without impacting the user experience.

To pause and resume campaigns, add the following methods in you code at the location you wish the pause and resume to take effect:

FollowAnalytics.InApp.pauseCampaignDisplay();  // will pause campaign display
FollowAnalytics.InApp.resumeCampaignDisplay();  // will resume campaign display

Create safe spaces for you in-app messages

Rather than pause everywhere you have an important screen or process, you can pause right at the initialization of the SDK and resume in the areas you think it is safe for in-app messages to be displayed.

Native specific features

Note that if you are working on a hybrid non-native solution, you will have to do some of the procedures on the native side of your app. This will be the case for OS specific as well as more advanced features.

These features include:

Enable campaign archiving

FollowAnalytics SDK allows you to store all campaigns and push notifications received by your application. This makes them available for custom usage, like building an inbox. To enable this feature, add the following line in the app manifest under the tag application.

Data Wallet

What is the Data Wallet?

The Data Wallet is a consent management and data declaration tool that helps you on your way to in compliance with GDPR.

Your Data Wallet puts together with what is called a policy. This policy which is created from the FollowAnalytics platform, is what brings together the legal texts, data categories, recipients and purposes you have determined in your Data Wallet. There could only be one policy at a time. Every time it is updated on the platform, the policy downloaded by the SDK.

All the data in the SDK will be in a JSON format and the developer will need to reorganize them in order to display them. The use of this feature is one of the most advanced for FollowAnalytics. We recommend that the developer working with the Data Wallet should be familiar with the FollowAnalytics and that most features were already installed.

Policy methods

Get Policy

To access the latest available policy, call the method getPolicy :

FollowAnalytics.DataWallet.getPolicy();

This method returns an object called Policy. Policy allows you to acquire and process the information related to the policy set in the Data Wallet (version, legal texts, data categories, etc).

Policy status

To check the read status of the policy, use the following method :

FollowAnalytics.DataWallet.isRead();

This method returns a boolean value.

To change the read status of the policy, use the method setIsRead(boolean read) with a boolean value as parameter.

FollowAnalytics.Datawallet.setIsRead(boolean read);

The policy is read when the boolean parameter is true and is not read when it is false.