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:
- Android SDK Version 6.8.0 (documentation)
- iOS SDK Version 6.9.0 (documentation)
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
- Install the package from npm:
$ npm install react-native-followanalytics --save
- 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.
- Install the package:
$ npm install PATH_FOR_THE_SDK --save
- 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.
Migration to AndroidX
Please note that the FollowAnalytics sdk uses AndroidX libraries. If your project does not use AndroidX, please make sure to migrate your project to use it. See this guide for more informations about the migration.
Install with Gradle
- Add the FollowAnalytics nexus repository to your build.gradle repositories.
repositories {
...
maven {
url 'https://nexus.follow-apps.com/nexus/content/repositories/releases/'
}
}
- 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.8.0" // <-- 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.
- You could first verify that the following was added to the
settings.gradle
file:
include ':react-native-followanalytics'
project(':react-native-followanalytics').projectDir = new File(rootProject.projectDir,'../node_modules/react-native-followanalytics/android')
- In Android Studio, go to the
java/com.facebook.react/PackageList
file. At the top of the page, notice the react package of the FollowAnalytics SDK was imported:
import android.app.Application;
import com.facebook.react.ReactApplication;
import com.followanalytics.reactnative.sdk.RNFollowAnalyticsPackage; // <-- This one
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");
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"});
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.
-
To add an item, use the
addToSet
method:FollowAnalytics.UserAttributes.addToSet("fruits","apple"); FollowAnalytics.UserAttributes.addToSet("fruits","strawberry"); FollowAnalytics.UserAttributes.addToSet("fruits","lemon");
-
To remove an item, use the
removeFromSet
method:FollowAnalytics.UserAttributes.removeFromSet("fruits","lemon"); // Removes "lemon" from set of fruits.
-
To clear a set:
FollowAnalytics.UserAttributes.clearSet("fruits"); // Removes all the items from the set.
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:
- Events and errors tags
- New user identification and attributes
- Crash reports
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.
Badge Management
Badges are the numbers displayed on the icon of the app, indicating to the user that the app has new information. Our service offers you two ways to update this value. The first one through the campaign editor on our platform and the second one using our SDK methods.
Using our platform, when creating a Push Campaign, it's possible to set a badge increment so that the SDK updates the badge number at push reception.
Using our SDK you can set, increment, decrement or get the badge number through the following methods:
FollowAnalytics.Badge.get(function); // Get the value of the icon badge number
FollowAnalytics.Badge.set(integer); // Set the value of the icon badge number
FollowAnalytics.Badge.updateBy(integer); // Update the value of the icon badge number
Some examples for each method:
FollowAnalytics.Badge.get((err, res) => {
if(err) {
console.log(err);
} else {
console.log(res); // `res` contains the badge value
}
});
FollowAnalytics.Badge.set(3); // Will set the badge number with the value `3`
FollowAnalytics.Badge.updateBy(1); // Will increase the badge number by `1`
FollowAnalytics.Badge.updateBy(-1); // Will decrease the badge number by `1`
Android 8.0 or higher,
The feature does not impact devices running on Android 8.0 (Oreo) or higher, as badge management is automatically handled by Android.
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: iOS (automatically featured with Android)
- Custom push notification icons: Android
- Custom handling of push campaigns Android
- Deeplinks: Android, iOS
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;
-
To get all in-app or push messages:
FollowAnalytics.InApp.getAll() //for in-app messages FollowAnalytics.Push.getAll() //for push notifications
-
To get an in-app or a push message by identifier:
FollowAnalytics.InApp.get(id) //for an in-app message FollowAnalytics.Push.get(id) //for a push notification
-
To delete an in-app or a push message:
FollowAnalytics.InApp.delete(id) //for an in-app message FollowAnalytics.Push.delete(id) //for a push notification
-
To mark as read an in-app or a push message:
FollowAnalytics.InApp.markAsRead(id) //for an in-app message FollowAnalytics.Push.markAsRead(id) //for a push notification
-
To mark as unread an in-app or a push message:
FollowAnalytics.InApp.markAsUnread(id) //for an in-app message FollowAnalytics.Push.markAsUnread(id) //for a push notification
-
You can get the
Message
object like this:FollowAnalytics.Push.getAll( (error, messages) => { if (error) { console.log(error); } else { console.log(messages); // Array of all the archived messages console.log(messages[0]); // First archived message console.log(messages[0].id); // Get only one property from the first element. See the properties below } });
FollowAnalytics.Push.get( id, (error, message) =>{ if (error) { console.log(error); } else { console.log(message); // Get message from id console.log(message.params); // Get only one property from message. See the properties below } });
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 3.2.0 to 3.3.0
- Before v3.3.0, if the
apiMode
was not explicitly defined in theConfiguration
, the SDK was automatically changing it based on theisVerbose
value. From v3.3.0 the SDK will no longer change theapiMode
automatically on real device and we recommend that you set it explicitly in your code, based on the XcodeDEBUG
flag like this:
#if DEBUG
configuration.apiMode = FollowAnalyticsAPIModeDev;
#else
configuration.apiMode = FollowAnalyticsAPIModeProd;
#endif
Updating from 2.1.0 to 3.0.0
- On iOS, the properties
identifier
anddateReceived
of theMessage
object was been renamed respectivelyid
andreceivedDate
. - On Android, the property
deepLinkURL
of theMessage
object was been renameddeepLinkUrl
. If you was using those properties, make sure to update your code with their new name. See allMessage
properties here.