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.

Installation

1. Download the FollowAnalytics SDK from the developer portal.

2. Add the FollowAnalytics SDK plugin to your cordova project:

   cordova plugin add "/path/to/fa-sdk-phonegap-plugin/"
   

Upgrading

1. Remove the old version of the plugin from your project:

   cordova plugin rm cordova.plugin.followanalytics
   

2. Download the new version of the plugin and add it to your project:

   cordova plugin add "/path/to/fa-sdk-phonegap-plugin/"
   

3. Run cordova prepare ios and cordova prepare android to apply the new plugin changes.

Initialize the SDK

FollowAnalytics Phonegap SDK plugin will generate, if not available yet, a followanalytics_configuration.json file at your root directory of your cordova project:

cordova_project/
  |--- config.xml
  |--- followanalytics_configuration.json // <-
  |--- hooks/
  |--- node_modules/
  |--- package-lock.json
  |--- package.json
  |--- platforms/
  |--- plugins/
  |--- www/

This file holds information for initializing FollowAnalytics Phonegap SDK.

You will need to change the content of this file for customising the initialization of FollowAnalytics Phonegap SDK.

For instance :

{
  "android" :
  { 
    "debug":
    {
      "apiKey" : "YOUR_API_KEY",
      "isVerbose" : true,
      "maxBackgroundTimeWithinSession" : 120 
    },
    "release":
    {
      "apiKey" : "YOUR_API_KEY",
      "isVerbose" : false,
      "maxBackgroundTimeWithinSession" : 120 
    }
  },
  "ios" :
  { 
    "debug":
    {
      "apiKey" : "YOUR_API_KEY",
      "isVerbose" : true,
      "maxBackgroundTimeWithinSession" : 120 
    },
    "release":
    {
      "apiKey" : "YOUR_API_KEY",
      "isVerbose" : false,
      "maxBackgroundTimeWithinSession" : 120 
    }
  }
}

You can also add custom build variants in both platforms like this:

  { 
    "debug":
    {
      "apiKey" : "YOUR_API_KEY",
      "isVerbose" : true,
      "maxBackgroundTimeWithinSession" : 120 
    },
    "release":
    {
      "apiKey" : "YOUR_API_KEY",
      "isVerbose" : false,
      "maxBackgroundTimeWithinSession" : 120 
    },
    "customVariant":
    {
      "apiKey" : "YOUR_API_KEY",
      "isVerbose" : true,
      "maxBackgroundTimeWithinSession" : 120 
    }
  }

Below, a description table that FollowAnalytics Phonegap SDK accepts as properties to add for customizing the initialization :

Android

android.useAndroidX=true
android.enableJetifier=true

iOS

Register for notifications

Android and Firebase Cloud Messaging

FollowAnalytics SDK supports push notifications based on Firebase Cloud Messaging.

In this section we will explain to you how to use Firebase Cloud Messaging (or FCM) with FollowAnalytics SDK.

Register your application

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.

Install Firebase Cloud Messaging

Download your Firebase Cloud Messaging config file in your Firebase console and add it into your cordova project at your root directory:

cordova_project/
  |--- config.xml
  |--- followanalytics_configuration.json
  |--- google-services.json // <-
  |--- hooks/
  |--- node_modules/
  |--- package-lock.json
  |--- package.json
  |--- platforms/
  |--- plugins/
  |--- www/

That's it, FollowAnalytics SDK will now manage to install it into your application.

Call the register for push method (iOS only)

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>

Analytics

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 an event/error
<a href="#" onclick="FollowAnalytics.logEvent('My event')">Log an event</a>
<a href="#" onclick="FollowAnalytics.logError('My error')">Log an error</a>

You can also add details to the events and errors

// Log an event/error with details
<a href="#" onclick="FollowAnalytics.logEvent('My event', 'My event details')">Log an event</a>
<a href="#" onclick="FollowAnalytics.logError('My error', 'My error details')">Log an error</a>

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
<a href="#" onclick="FollowAnalytics.logLocationCoordinates(latitude, longitude)">Log Location</a>
<a href="#" onclick="FollowAnalytics.logLocationPosition(position)">Log Location</a> // 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.

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'});

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.

User ID

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

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

To inspect and set the opt-out state, call the following methods:

FollowAnalytics.getOptInAnalytics(function(error, result) {
    if (!error) {
        // do something with the result
        // console.log(result);
    } else {
        // do something with the error
        // console.log(error);
    }      
});

    FollowAnalytics.setOptInAnalytics(true); // accepts true/false as input

Data Wallet

If you want to use Data Wallet, the very first step is to enable it on the followanalytics_configuration.json using isDataWalletEnabled and set it to true.

Get the current policy:

FollowAnalytics.DataWallet.getPolicy(function(error, result) {       
    if (!error) {
        // do something with the result
        // console.log(JSON.stringify(result));
    } else {
        // do something with the error
        // console.log(error);
    }      
});

Informs the SDK that the user has accepted the current policy:

FollowAnalytics.DataWallet.setIsRead(true);

Get current policy state:

FollowAnalytics.DataWallet.isRead(function(error, result) {       
    if (!error) {
        // do something with the result
        // console.log(result);
    } else {
        // do something with the error
        // console.log(error);
    }      
});

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

Rich push notifications (iOS Specific)

Notification Service Extension Framework

Requirement

To make your app able to receive rich notifications & badge incrementation, follow these steps:

1. In your Xcode project, add a new target.
   
   

   
   
   

2. Select Notification Service Extension, give it a name and confirm. Then when prompted, activate the scheme.
   
   

   
   
   

Add the FANotificationExtension framework

1. In your project settings, select your target and select the Build Phases tab:

   1. Press the + button, and select New Copy File Phase.
      
      
      
      
   2. On the newly added Copy File phase, change Destination to Frameworks.
      
      
      
      
   3. Press the + button.
      
      
      
      
   4. In the Choose item to add dialog, select the FANotificationExtension.framework inside the Frameworks folder.
   5. Click on Open button.
   6. Uncheck Copy items if needed box.
   7. Click on Finish button.
   8. In the Framework Search Paths fields of the Build Settings tab, add the path to the FANotificationExtension.framework.
      
      
      
      

   Make sure if your Framework Search Paths are equal to the Framework Search Paths of your main target.

Create an app group between your app and the extension

Before all, an App Group must be created.

• Go to the apple developer portal.
• Choose the identifier tab.
• Choose the App Groups filed from the list.
  
  

• Tap + to create a new App Group
• Create your App Group and click Continue
  
  

• Switch to the App ID of the app.
• Add App Groups capability
  
  

• Select the new App Group recently created.
  
  

• Then, the app group must be added to the AppId of app and extension
• Finally, the app group capability must be activated in Xcode for both app and extension
  
  

Configuring the SDK to work with the extension

First, make sure you have set the proper App Group for the app target:

The appGroup parameter should be specified in the followanalytics_configuration.json file:

{
"ios":
  { 
    "debug":
    {
      "apiKey" : "YOUR_API_KEY",
      "isVerbose" : true,
      "maxBackgroundTimeWithinSession" : 120,
      "appGroup":"group.your.identifier" 
    },
    "release":
    {
      "apiKey" : "YOUR_API_KEY",
      "isVerbose" : false,
      "maxBackgroundTimeWithinSession" : 120,
      "appGroup":"group.your.identifier"
    }
  }
}

Implement the Notification Service Extension

First, make sure you have set the proper App Group for the extension target:

Copy and paste the following implementation in the NotificationService file of the extension target you created and change the the name of the appGroup with the one you defined:

#import “NotificationService.h”
#import <FANotificationExtension/FANotificationExtension.h>

@interface NotificationService ()

@property(nonatomic, strong) void (^contentHandler)(UNNotificationContent* contentToDeliver);
@property(nonatomic, strong) UNMutableNotificationContent* bestAttemptContent;

@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest*)request
   withContentHandler:(void (^)(UNNotificationContent* _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    [FANotificationService
        getFAContentIfNeededWithRequest:request
                            bestContent:self.bestAttemptContent
                            appGroup:@"group.your.identifier"
                            completion:^(UNMutableNotificationContent* _Nullable newContent) {
                            NSLog(@"NotificationService: %@", request);
                            // Modify the notification content here...

                            self.contentHandler(newContent);
                            }];
}

- (void)serviceExtensionTimeWillExpire {
    // Called just before the extension will be terminated by the system.
    // Use this as an opportunity to deliver your "best attempt" at modified content,
    //otherwise the original push payload will be used.
    self.contentHandler(self.bestAttemptContent);
}
@end

import UserNotifications
import FANotificationExtension

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest,
                                withContentHandler contentHandler:
                                @escaping (UNNotificationContent) -> Void) {
        self.contentHandler = contentHandler
        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        if let bestAttemptContent = bestAttemptContent,
        let contentHandler = self.contentHandler {
        // Modify the notification content here...

            FANotificationService.getFAContentIfNeeded(with: request,
                                                        bestContent: bestAttemptContent,
                                                        appGroup: "group.your.identifier") {
                                                        (newContent) in
                                                        if let newC = newContent {
                                                            contentHandler(newC)
                                                        }
            }
        }
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }
}

Badge Management

Badges are the numbers displayed on the icon of the app, indicating to user that the app has new information. The FollowAnalytics SDK handles the badge number automatically, but if you need to update it and you want to take in consideration the current value number from our SDK you can use the FABadge class which lets you set and get the SDK badge value thought the following methods:

[FABadge setBadge:INTEGER]; // Set the value of the icon badge number
[FABadge updateBadgeBy:INTEGER]; // Update the value of the icon badge number
[FABadge badge]; // Get the value of the icon badge number

FABadge.setBadge(Int) // Set the value of the icon badge number
FABadge.updateBadgeBy(Int) // Update the value of the icon badge number
FABadge.badge // Get the value of the icon badge number

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

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 (Android Only)

On the platform, you can specify deep-linking parameters for your Push campaign. These parameters are passed to the app 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.).

To handle the deeplinking from your javascript code, set a callback for the onPushMessageClicked event as soon as the device is ready:

onDeviceReady: function() {
    ...
    FollowAnalytics.handleDeeplink();
    FollowAnalytics.on("onPushMessageClicked", function(data){
        alert(JSON.stringify(data));
    });
    ...
},

• 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

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();

Archiving messages

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. All campaigns displayed by a device can be archived locally and accessed from the developer's code. In order to configure your campaign storage, you have to set the following FollowAnalyticsConfiguration properties on the followanalytics_configuration.json:

{
    "archiveInAppMessages": true,
    "archivePushMessages": true
}

Get all campaigns

FollowAnalytics.InApp.getAll(function(error, result) {
    if (!error) {
        // do something with the result
        // console.log(JSON.stringify(result));
    } else {
        // do something with the error
        // console.log(error);
    }      
});

FollowAnalytics.Push.getAll(function(error, result) {
    if (!error) {
        // do something with the result
        // console.log(JSON.stringify(result));
    } else {
        // do something with the error
        // console.log(error);
    }      
});

Get campaign by identifier

FollowAnalytics.InApp.get(identifier, function(error, result) {
    if (!error) {
        // do something with the result
        // console.log(JSON.stringify(result));
    } else {
        // do something with the error
        // console.log(error);
    }      
});

FollowAnalytics.Push.get(identifier, function(error, result) {
    if (!error) {
        // do something with the result
        // console.log(JSON.stringify(result));
    } else {
        // do something with the error
        // console.log(error);
    }      
});

Mark campaigns as read

FollowAnalytics.InApp.markAsRead([identifier1, identifier2, ...]);
FollowAnalytics.Push.markAsRead([identifier1, identifier2, ...]);

Mark campaigns as unread

FollowAnalytics.InApp.markAsUnread([identifier1, identifier2, ...]);
FollowAnalytics.Push.markAsUnread([identifier1, identifier2, ...]);

Delete campaigns

FollowAnalytics.InApp.delete([identifier1, identifier2, ...]);
FollowAnalytics.Push.delete([identifier1, identifier2, ...]);

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

Updating from 6.3.0 to 6.3.1

• Calling FABage.enable() on the native side is no longer necessary to enable the bagde feature. Now the SDK automatically handles the badge number from the received campaigns.
• Calling FollowAnalytics.initialize() from the app.onDeviceReady() callback in your index.js is no longer necessary. Now the plugin automatically adds the SDK initialization code in your AppDelegate.m.

Updating from 6.2 to 6.3

• It's no longer needed to define the SDK Configuration on the native side. Now, for both Android and iOS platforms, the Configuration must be defined in the followanalytics_configuration.json file. If you are updating from 6.2, we recommend to follow those steps:
  • Remove the FollowAnalytics plugin: cordova plugin rm cordova.plugin.followanalytics
  • Delete the existing followanalytics_configuration.json file or edit it to define your desired SDK Configuration.
  • Add the FollowAnalytics plugin back: cordova plugin add /path/to/fa-sdk-phonegap-plugin/.
  • Edit the followanalytics_configuration.json file to define your desired SDK Configuration if needed.
  • Run cordova prepare ios and cordova prepare android to apply the changes on followanalytics_configuration.json.
• Some advanced configurations like rich push notifications for iOS still requires native modifications.
• Modify the methods arguments in all your calls to SDK getters. For instance, to get the opt-in analytics state, you have to update your code from this:

  FollowAnalytics.getOptInAnalytics(function(result) {
      // Do something with the result
  });
  

  To this:

  FollowAnalytics.getOptInAnalytics(function(error, result) {
      if (!error) {
          // Do something with the result
      } else {
          // Do something with the error
      }      
  });
  

  Make sure to read each method's description in the documentation.
• The method setMaximumBackgroundTimeWithinSession() is no longer available. Now, you have to use the maxBackgroundTimeWithinSession parameter in followanalytics_configuration.json instead.

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

Inline JavaScript not executed

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.

Cannot find module 'xcode'

Execute the following command : npm install --save xcode and reinstall FollowAnalytics SDK plugin.

Cannot find module 'q'

Execute the following command : npm install --save q and reinstall FollowAnalytics SDK plugin.

Problems with arm64 Architecture or PhaseScriptExecution failed

First of all make sure you removed all Run Script from your Build Phases.
Remove the plugin with: cordova plugin remove cordova.plugin.followanalytics.
Add the plugin again with: cordova plugin add /path/to/fa-sdk-phonegap-plugin/