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 PhoneGap/Cordova are based on a native version of the SDK.
The FollowAnalytics PhoneGap/Cordova SDK was tested on Cordova v6.+ and includes the following version:
- 6.1.1 FollowAnalytics SDK iOS
- 6.1.1 FollowAnalytics SDK Android.
Integration
This document will cover app setup and the component installation process, as well as basic integration steps for iOS and Android.
If you want an example, check out our PhoneGap sample integration code on Github.
Prerequisites and minimal setup
In this section, we explain how to get started with FollowAnalytics SDK for iOS. Before you start, be sure to have all the necessary prerequisites. These include:
- Registering the application on the Platform
- Generating the API Key
Here are the minimal steps for integrating the SDK in your app:
- Installing the SDK in your app
- Initializing the SDK using your API key
- Registering for notifications and location
Once the integration is finished, we highly recommend you test the setup. You will find out how to test your setup in this section. Then, you can start tagging events and saving attributes in your app.
Installation
-
Download the FollowAnalytics SDK from the developer portal.
-
Add the plugin
cordova
to your app:cordova plugin add /path/to/fa-sdk-phonegap-plugin/
Initialize the SDK
Be sure to have your API key
Be sure to have your API key for this step of the configuration. You can retrieve you app's API key from the administration section of the FollowAnalytics platform (see here)
Add the following to your index.js
:
onDeviceReady: function() {
FollowAnalytics.initialize(YOUR_API_KEY);
}
Debug mode
If you want the SDK to be initialized in Debug mode hence being more verbose about the methods called and actions performed, please initialize it as follows:
onDeviceReady: function() {
FollowAnalytics.initialize(YOUR_API_KEY, true);
}
Remove Debug mode before releasing
Don't forget to remove the debug flag when compiling to the stores in order to reduce logging within clients applications.
Register for notifications
Important
Push notifications on debug
mode don't work. If you wish to test your notifications, which is highly recommended, switch to release
mode.
The FollowAnalytics SDK supports push notifications based on Firebase Cloud Messaging. If you haven't done so already, you will need to add your project to Firebase in order to continue in the following steps. In this section we will explain to you how to use Firebase Cloud Messaging (or FCM) with the FollowAnalytics SDK. This means that we will cover:
Android and Firebase Cloud Messaging
The FollowAnalytics SDK supports push notifications based on Firebase Cloud Messaging. If you haven't done so already, you will need to add your project to Firebase in order to continue in the following steps. In this section we will explain to you how to use Firebase Cloud Messaging (or FCM) with the FollowAnalytics SDK. This means that we will cover:
Install Firebase Cloud Messaging
Get started with Firebase
Sending push notifications for Android requires Firebase Cloud Messaging, Google's standard messaging service. If you don't already use Firebase, you will need to do the following:
- Add Firebase to your project
- Create Firebase project to Firebase console
Before you start adding Firebase to your project, we recommend you take the time to familiarize yourself with firebase and its console. You will find this information (and much more) by referring to the Google documentation.
-
Add the library FCM to your
build.gradle
file in your application module.implementation "com.google.firebase:firebase-messaging:17.3.0"
-
Create a class that extends to
FirebaseMessagingService
and override the two methodsonMessageReceived
andonNewToken
.import com.google.firebase.messaging.FirebaseMessagingService; import com.google.firebase.messaging.RemoteMessage; public class MyFirebaseMessagingService extends FirebaseMessagingService { /** * Every push notification will arrive through this method */ @Override public void onMessageReceived(RemoteMessage remoteMessage) { } /** * Every new token will arrive through this method */ @Override public void onNewToken(String s){ } }
-
Add the following service tag in your
AndroidManifest
application file. Be sure that the value inandroid:name
is the relative path to your new service previously created.<service android:name=".MyFirebaseMessagingService"> <!-- Relative path of service class--> <intent-filter> <action android:name="com.google.firebase.MESSAGING_EVENT"/> </intent-filter> </service>
-
Finally, do not forget to copy the FCM Server key token (available through Firebase Console in your project settings).
and paste it to our platform in the application's administration.
Verify your Google Services configuration
Be sure to check the configuration of Google Services as they have to be the following if you want the FollowAnalytics SDK and Firebase to work.
- Version of Google Services that is at least 4.0.1
- The JSON for Google Services in your application is correct. It is accessible by doing select Project > App > google-services.json) is the same as the one in Firebase (which you can download from the Firebase Console
Interacting Firebase Cloud Messaging with FollowAnalytics SDK
Prerequisites for using Firebase
Before you begin, you need to have Firebase Cloud Messaging (FCM) installed in your project. Then only you can proceed to the integration.
If your app already uses Google Cloud Messaging (GCM) for your push notifications, you will need to migrate to Firebase Cloud Messaging (FCM) after installation. You can skip this section and follow the instructions here.
Now that you have installed FCM, you need it to interact with the FollowAnalytics SDK. For this, access the your Firebase Cloud Messaging Service class (a class we previously called MyFirebaseMessagingService
that was created and extended to FirebaseMessagingService
).
Set push token
FollowAnalytics.setPushToken(String token)
is a function that passes a FCM token to FollowAnalytics SDK. Add it to the functiononNewToken
.
For example:
@Override
public void onNewToken(String s){
android.util.Log.d(TAG, "Token is : "+s);
FollowAnalytics.setPushToken(s); // <-- Insert this method
}
Process Firebase Message
FollowAnalytics.processFirebaseMessage(Context context, RemoteMessage remoteMessage)
is a function that passes the push message notification to FollowAnalytics SDK.
This function must be added to onMessageReceived
in cases to transmit the push notification to FollowAnalytics SDK.
@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
FollowAnalytics.processFirebaseMessage(this, remoteMessage); // <-- Insert this method
}
Call the register for push method (iOS only)
Note
While on Android, the devices are registered for push notifications automatically after Firebase is integrated, this is not the case for iOS devices. You must first call a method that will let your device authorize the notifications
Add a call to registerForPush
, either from your HTML code whenever you think the moment has come to ask the user for it. If, however your app code is already registered to send push notifications, then the you have nothing to do here and skip to the next section.
HTML
<a href="#" onclick="FollowAnalytics.registerForPush()">register for push</a>
Build in release mode for Android
The app must be built in release mode in order to receive push notifications
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.
Data sent in debug mode will not appear on dashboards
When your app runs in DEBUG mode or in a simulator, the data is automatically sent as development logs, and is therefore not processed to be shown on the main UI page. DEBUG logs can be checked using the method given in the FAQ section (see related entry in FAQ for more information on debug & release modes).
App tags
The SDK allows you to log events happening in your code. These are the methods that you can call on the SDK:
//Log event with no details
<a href="#" onclick="FollowAnalytics.logEvent('My event')">Log an event</a>
//Log event with details
<a href="#" onclick="FollowAnalytics.logEvent('My event', 'My event details')">Log an event</a>
//Log error with no details
<a href="#" onclick="FollowAnalytics.logError('My error')">Log an error</a>
//Log error with details
<a href="#" onclick="FollowAnalytics.logError('My error', 'My error details')">Log an error</a>
Events can be renamed on the FollowAnalytics platform
The name that you give to your event here can be overridden in the FollowAnalytics platform. For more information, reach out to your Customer Success Manager or message support.
Use the name as the unique identifier of your log. Use the details section to add specific details or context. The details field can either be a String or a Hash, so that you can associate multiple key-values for additional context.
For example, you can log the display of a view by writing the following:
FollowAnalytics.logEvent('Product view', Product reference);
FollowAnalytics.logEvent('Add product to cart', {'product_id': 'ABCD123','product_category': 'Jeans'});
Logging best practices
To ensure your tags are relevant and will end up empowering your team through FollowAnalytics, please read the Logging best practices entry in the FAQ section.
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 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 identifier, use:
FollowAnalytics.setUserId("user_id@email.com");
If you want to remove the user identifier (in case of a sign out for instance) use the following method:
FollowAnalytics.unsetUserID();
Predefined attributes
The SDK allows to set values for both custom and predefined attributes.
For predefined attributes, the SDK has the following properties:
FollowAnalytics.UserAttributes.setFirstName("Peter");
FollowAnalytics.UserAttributes.setLastName("Jackson");
FollowAnalytics.UserAttributes.setCity("San Francisco");
FollowAnalytics.UserAttributes.setRegion("California");
FollowAnalytics.UserAttributes.setCountry("USA");
FollowAnalytics.UserAttributes.setGender(FollowAnalytics.Gender.Male);
FollowAnalytics.UserAttributes.setEmail("mail@mail.com");
FollowAnalytics.UserAttributes.setBirthDate("2001-02-22");
FollowAnalytics.UserAttributes.setProfilePicture("https://picture/picture");
They are "predefined" in the sense that they will be attached to default fields on your user profiles.
Custom attributes
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. Please ensure the types match by visiting the profile data section of the product.
Set a custom attribute
To set your custom attributes, you can use methods that are adapted for each type:
FollowAnalytics.UserAttributes.setNumber('key', "1");
FollowAnalytics.UserAttributes.setString('key', "A custom string attribute");
FollowAnalytics.UserAttributes.setBoolean('key', "true");
FollowAnalytics.UserAttributes.setDate('key', "2016-10-26");
FollowAnalytics.UserAttributes.setDateTime('key', "2016-10-26T11:22:33+01:00");
For example, to set the user's job:
FollowAnalytics.setString("job", "Taxi driver");
Delete a custom attribute value
You can clear the value of an attribute using its key. For example, to delete the user's job:
FollowAnalytics.clear("job");
Set of Attributes
You can add or remove an item to or from a set of attributes.
To add an item:
FollowAnalytics.addToSet("fruits", "apple");
FollowAnalytics.addToSet("fruits", "banana");
To remove an item:
FollowAnalytics.removeFromSet("fruits", "apple");
And to clear a set:
FollowAnalytics.clearSet("fruits");
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 app. 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).
To inspect and set the opt-out state, call the following methods:
FollowAnalytics.getOptInAnalytics(function(result){
// do something with the result
// console.log(result);
});
FollowAnalytics.setOptInAnalytics(true); // accepts true/false as input
GDPR
You can record when the user expresses his demand to access or delete his personal data by calling one of the following methods:
FollowAnalytics.GDPR.requestToAccessMyData();
FollowAnalytics.GDPR.requestToDeleteMyData();
The SDK will record all requests and send them to FollowAnalytics servers as soon as network conditions allow it. The SDK remembers pending requests between app restarts.
Campaigns
Campaign basics
What we mean by campaigns are the messages that you with to send to your user from the FollowAnalytics platform. Currently, FollowAnalytics enables you to send two types of campaigns: push notifications and in-app messages. Push notifications allow you to send messages to your user's home screen, whereas an in-app a message that is displayed in the app while the user is actively using it.
Before you start, be sure that the SDK is properly initialized. This includes registration for push notifications, which is covered in the integration section.
Rich push notifications (iOS Specific)
Rich push notifications on iOS
Rich push notifications are notifications with embedded rich media (images, GIFs, videos). They are only available on iOS 10 and above. Should a user have a version under iOS 10, they will receive rich push notifications but not be able to see the rich media included.
Notification Service Extension Framework
Requirement
To make your app able to receive rich notifications & badge incrementation, follow these steps:
-
In your xCode project, add a new target.
-
Select Notification Service Extension, give it a name and confirm. Then when prompted, activate the scheme.
Install using Cocoapods
-
If you want to use Cocoapods to manage your external dependencies, simply add the following line to your Podfile only in the extension target:
pod 'FANotificationExtension'
If you don't have a podfile yet, open a console and do a
pod init
in your project directory.Then, you only need to update your cocoapods dependencies:
pod install
-
Select the target of your main app, in Build phase
- Press the + button, and select
New Copy File Phase
. - Change the destination to
Frameworks
- Add the FANotificationExtension.framework, you should find it inside the Pod folder.
- Press the + button, and select
-
Still in the Build phase
- Press the + button, and select
New Run Script Phase
. - Add this script:
bash "${PODS_ROOT}/FANotificationExtension/FANotificationExtension.framework/strip-frameworks.sh"
- Press the + button, and select
Initialise
- import the
<FANotificationExtension/FANotificationExtension.h>
in your file of your target extension. - Implement the code in the method:
didReceiveNotificationRequest
:
Objective-C
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
self.contentHandler = contentHandler;
self.bestAttemptContent = [request.content mutableCopy];
[FANotificationService getFAContentIfNeededWithRequest:request bestContent:self.bestAttemptContent appGroup:@"APPGROUP" completion:^(UNMutableNotificationContent * _Nullable newContent) {
// Modify the notification content here...
self.contentHandler(newContent);
}];
}
Swift
override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
self.contentHandler = contentHandler
bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
if let bestAttemptContent = bestAttemptContent {
FANotificationService.getFAContentIfNeeded(with: request, bestContent: bestAttemptContent, appGroup: "APPGROUP", completion: { (newContent:UNMutableNotificationContent?) in
// Modify the notification content here...
contentHandler(newContent!)
})
}
}
⚠️If you need to increase the badge number with a push, you will need an app Group between your main App and you extension.
Custom handling of rich campaigns
Rich campaigns can be handled directly by the application code, instead of being showed automatically by the SDK. The behavior is defined when creating the campaign, using the "automatically display content" switch.
iOS
For campaigns where the content is not handled by FollowAnalytics, implement the following FAFollowAppsDelegate method in your AppDelegate:
- (void)followAppsShouldHandleWebViewUrl:(NSURL *)url withTitle:(NSString *)webviewTitle;
Android
For campaigns where the content is not handled by FollowAnalytics, you will need to extend com.followapps.android.CustomRichCampaignBaseReceiver
and declare it in your AndroidManifest.xml
.
You'll need to use an intent-filter on BROADCAST_RICH_CAMPAIGNS_ACTION
. For instance:
<receiver android:name=".RichCampaignDataReceiver" >
<intent-filter>
<action android:name="%YOUR_APP_PACKAGE_NAME%.BROADCAST_RICH_CAMPAIGNS_ACTION" />
</intent-filter>
</receiver>
Where %YOUR_APP_PACKAGE_NAME%
is your application package name.
The method onRichCampaignDataReceived
must be overridden. Rich campaign parameters are provided as method arguments:
- Campaign title:
title
- Campaign URL:
url
- Custom Parameters associated to the campaign:
customParams
Customize the Icon Notification (Android specific)
For applications that targets at least Lollipop version, the push notification icon at the status bar needs to be updated according to this section and this section (tutorial for creating icons with android studio).
Make sure to rename all the icon images to ic_fa_notification.png
for each density created.
Then, place them to your project under platforms/android/res
folder and make sure that all your notifications looks right with the new color scheme. For example :
yourproject/platforms/android/res/drawable-mdpi/ic_fa_notification.png
Icon colors
Update or remove assets that involve color. The system ignores all non-alpha channels in action icons and in the main notification icon. You should assume that these icons will be alpha-only. The system draws notification icons in white and action icons in dark gray.
Deep-linking: URL, Parameters
Campaigns created through FollowAnalytics allow to deep link to content in your app. You can either use an App Link, or use key-value parameters that are forwarded to your code.
App Links
Version 4.1.0 of the SDK introduced the possibility to use direct App Links like twitter://messages
, which will send you to the corresponding screen inside the Twitter application.
To use App Links you need to enable Deep Linking switch in our UI, when creating a campaign. Use the App Link field to set the type of URLs schemas.
It can either be an URL Schema to an external application or for your own application.
Deep-linking parameters
In FollowAnalytics campaigns, you can specify deep-linking parameters, e.g. in your push messages.
These parameters are given to the developer's code by the SDK. It is then up to the developer to implement the deep-linking in the app (specific path of screens, format of the arguments, etc.).
Deep-linking parameters
To handle the deeplinking from your javascript code, have this run when the device is ready:
onDeviceReady: function() {
...
FollowAnalytics.handleDeeplink();
FollowAnalytics.on("onPushMessageClicked", function(data){
alert(JSON.stringify(data));
});
...
},
As you can notice here, the plugin provides the following events : onPushMessageClicked
.
-
PushMessageClicked: When the user clicks on the push, you can retrieve all the added custom parameter as following:
FollowAnalytics.on("onPushMessageClicked",function(data){ //The argument data is an object Json.You can retrieve your value by data.my_key key/value json });
The argument
data
is the javascript key-value object, you can retrieve the value by the key as following :data["deepurl"]
Pausing 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 app. 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 supposed to be displayed when the mechanism is paused, is stacked and 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.pauseCampaignDisplay();
FollowAnalytics.resumeCampaignDisplay();
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 campaigns to be displayed.
Opening an external webview
The plugin allows you to launch a native web view with a given url
and be able to performs logs from that external resource. In order to do so, if you want to open url https://s3-eu-west-1.amazonaws.com/fa-sdk-files/index.html
in a native web view launched from your html code, call the following method from your PhoneGap HTML:
FollowAnalytics.openWebView(URL, TITLE, CLOSE_BUTTON_TEXT);
Something like:
<a href="#" onclick="FollowAnalytics.openWebView('https://s3-eu-west-1.amazonaws.com/fa-sdk-files/index.html', 'Test Log', 'Close'); return false;">Open WebView with title</a>
The URL
argument will contain the url of the page to display (required), the TITLE
argument will be shown as the title for the NavigationBar (optional, iOS only), and the CLOSE_BUTTON_TEXT
will contain the text for the close button (optional, iOS only, defaults to “close”).
Please check the html at https://s3-eu-west-1.amazonaws.com/fa-sdk-files/index.html
to see how to tag your external pages.
Current available methods are:
logEvent(name, details)
logError(name, details)
setUserId(userId)
unsetUserId()
NOTE: if you're tagging from a link and the link has a real href
set, the SDK will handle that for you, performing the onclick
action and redirecting you right after.
Migration and Troubleshooting
Migration from 4.x
Although previous versions of the FollowAnalytics plugin respected Cordova guidelines of integration they still required developers to perform modifications to the native code for each supported platform.
This new version changes things as it can be used without having to modify nothing but the config.xml
and the html/js
code.
If you plan to update from older versions, the shortest path would be to:
- remove the FollowAnalytics plugin
- remove both platforms (iOS and Android)
- add back the platforms (iOS and Android)
- add back the FollowAnalytics plugin
- follow this installation guide from the top
If you plan to keep the current code you'll need to remove all the code needed to integrate previous plugin versions (please check older plugin documentation to know exactly what to remove).
Troubleshooting
If you eventually run into an error like:
Refused to execute inline event handler because it violates the following Content Security Policy directive: "default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'". Note that 'script-src' was not explicitly set, so 'default-src' is used as a fallback.
Be sure to replace the line
<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
on your index.html
by
<meta http-equiv="Content-Security-Policy" content="default-src *; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval'" >
This will enable the logging of events.