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 plugin cordova to your app:

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

Initialize the SDK

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

Register for notifications

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:

• Installing FCM in your project
• Integrating FCM with the FollowAnalytics SDK

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:

• Installing FCM in your project
• Integrating FCM with the FollowAnalytics SDK

Install Firebase Cloud Messaging

1. Add the library FCM to your build.gradle file in your application module.

   implementation "com.google.firebase:firebase-messaging:17.3.0"
   

2. Create a class that extends to FirebaseMessagingService and override the two methods onMessageReceived and onNewToken.

   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){ }
   }
   

3. Add the following service tag in your AndroidManifest application file. Be sure that the value in android: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>
   

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

   

Interacting Firebase Cloud Messaging with FollowAnalytics SDK

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 function onNewToken.

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

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

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

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.

   

Install using Cocoapods

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

2. Select the target of your main app, in Build phase

   1. Press the + button, and select New Copy File Phase.
   2. Change the destination to Frameworks
   3. Add the FANotificationExtension.framework, you should find it inside the Pod folder.

3. Still in the Build phase

   1. Press the + button, and select New Run Script Phase.
   2. Add this script:

      bash "${PODS_ROOT}/FANotificationExtension/FANotificationExtension.framework/strip-frameworks.sh"
      

Initialise

1. import the <FANotificationExtension/FANotificationExtension.h> in your file of your target extension.
2. 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

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

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

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.