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.

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.5" // <-- 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("anEventName");
logError("anErrorName");

You can also add details to the events and errors

// Log an event/error with details
logEvent("anEventName", "anEventDetail");
logError("anErrorName", "anErrorDetail");
Use the name as the unique identifier of your log. Use the details to be more specific and add some context.

You can send details objects using the following methods:

// Log an event/error with details object
logEventObject("anEventName", {"Key 1": "Value 1", "Key 2": "Value 2", "Key 3": "Value 3"});
logErrorObject("anErrorName", {"Key 1": "Value 1", "Key 2": "Value 2", "Key 3": "Value 3"});
The details object allow you to associate multiple key-values for additional context. For Android the log details object should only contain String fields.

For logging geolocations, you can use the following methods:

// Log a location coordinates
logLocationCoordinates(48.8410646, 2.3210844);
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("aFirstName");
setLastName("aLastName");
setEmail("something@domain.com");
setDateOfBirth("2020-02-28");  // Takes a string (yyyy-MM-dd)
setGender(FollowAnalytics.Gender.MALE); // Also can use FEMALE || OTHER
setCountry("France");
setCity("Paris");
setRegion("Île-de-France");
setProfilePictureUrl("https://picture_url");

The gender selection is as follows:

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

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("aKey", 100);
setDouble("aKey", 10.5);
setString("aKey", "aString");
setBoolean("aKey", true); // Or False
setDate("aKey", "2020-02-28"); // Takes a string (yyyy-MM-dd)
setDateTime("aKey", "2020-02-28 18:46:19 +0200");  // Takes a string (yyyy-MM-dd 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-in Analytics

FollowAnalytics SDK opt-in analytics state define whether to send logs and attributes to the platform. Opt-in analytics is true by default, meaning logs and attributes will be sent to FollowAnalytics platform.

You can set opt-in analytics to false at SDK initialization by setting the optInAnalyticsDefault parameter to false in the FollowAnalytics.Configuration object passed to the initialization method. This is only used to set the default opt-in value at initialization.

Once opt-in analytics is false, no more data is collected. This data includes the following:

To change opt-in analytics state at runtime, use the setOptInAnalytics method:

FollowAnalytics.setOptInAnalytics(state); // state is a boolean

This value is persisted in memory and the opt-in analytics state is changed for all subsequent launch of your application, meaning optInAnalyticsDefault is ignored.

To retrieve the current opt-in analytics state, use the getOptInAnalytics() method:

FollowAnalytics.getOptInAnalytics((error, response) => {
    if(error) {
        console.log(error);
    } else {
        console.log(response);
    }
});

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 to 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.

Opt-in Notifications

The FollowAnalytics SDK opt-in notifications status defines whether your app will receive notifications from your Push campaigns. Opt-in notifications is true by default, meaning notifications from your Push campaigns will be received by your app. This status is independent from the system notification authorization, which is also needed by your app to display notifications.

Thanks to this opt-in notifications status, you can implement a UI in your app to allow to choose whether to receive notifications, without the need to go to the notification authorization settings. Note that the opt-in notifications status will have no effect if the system notification authorization is not allowed, and in this case, your app will not receive notifications from your Push campaigns, whatever the opt-in notifications status.

To update your app UI to reflect the current opt-in notifications status, use the getOptInNotifications method:

FollowAnalytics.getOptInNotifications((error, response) => {
    if(error) {
        console.log(error);
    } else {
        console.log(response);
    }
});

To update the current opt-in notifications status upon UI change, use the setOptInNotifications method:

FollowAnalytics.setOptInNotifications(state); // state is a boolean

Handling transistion from opt-out to opt-in notifications

Just calling FollowAnalytics.setOptInNotifications(true) after the user interacts with your app UI to opts-in for notifications could be insufficient if the system notification authorization is not allowed. For this reason, we recommend to implement the following flow after the user opts-in for notifications in your app:

Check the return value of FollowAnalytics.isRegisteredForPushNotifications() which is true only if the system notification authorization AND the opt-in notifications status are true. If false, display a message and button to invite your user to enable the system notification authorization. Call FollowAnalytics.openNotificationSettingsEventually() when the user taps the button, to direct him to the notification settings screen. Another possibility is to bypass the first two steps and only implement the last one. In this case the notification settings will be opened only if the system authorization was not allowed.

It's also possible to set the opt-in notifications status to false at the SDK initialization by setting the optInNotificationsDefault parameter to false in the Configuration object passed to the initialization method. This is only used to set the default opt-in value at the first launch of the app. Note that calling setOptInNotifications() will persist the opt-in notifications status for all subsequent launch of your application, meaning optInNotificationsDefault will be ignored.

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:

Rich Push notifications

In XCode project settings, make sure the Deployment target version for your Notification Service Extension target is 10.0 or higher. If you installed the SDK via CocoaPods make sure the platform version is set to 10.0 or higher for the Notification Service Extension target in your Podfile.

Enable campaign archiving

FollowAnalytics SDK allows you to store campaigns's messages received by your app. This makes them available for custom usage, like building an inbox feature. Messages received by a device can be archived locally and accessed from the developer's code, formatted as a Message object. In order for you to enable the message archiving, you need to set the following Configuration properties at SDK initialization:

archivePushMessages = true;
archiveInAppMessages = true;

The Message object contains the following properties:

Properties Type Description
body string Text provided in the platform's "Content" field of the Push campaign editor.
category string Return the category
deepLinkUrl string Url provided in the platform's "App Link" field of the Push campaign editor.
id string Unique message Identifier.
layout string Return layout
params object Key/Value pairs provided in the Push campaign editor.
messageType string Return message type
receivedDate string If message comes from a Push campaign, this is the date at which the message is received on the device. If message comes from an In-App campaign, this is the start date of the campaign.
title string Text provided in the platform's "Title" field of the Push campaign editor.
url string Url provided in the platform's "URL" field of In-App Custom Web Page campaign editor. If the message comes from a Push campaign, this is the url of the Rich Media.
isInApp boolean Returns true if message comes from a In-App campaign, false if it comes from a Push campaign.
isPush boolean Returns true if message comes from a Push campaign, false if it comes from a In-App campaign.
isRead boolean Indicates if the message has been read or not. False at message reception.
isSilent boolean Returns true if message comes from a Push campaign with the "Silent" option enabled, false otherwise.
Android only:
Properties Type Description
isNotificationDismissed boolean This property returns true if the notification has been dismissed, false otherwise.
notificationId integer If message comes from a Push campaign, this is the Android notification identifier.
iOS only:
Properties Type Description
subtitle boolean Text provided in the platform's "Subtitle" field of the Push campaign editor.
notificationId string If message comes from a Push campaign, this is the UNNotificationRequest unique identifier (iOS >= 10.0), otherwise it's null

Updating from older versions

Updating from 2.1.0 to 3.0.0