Integration

The FollowAnalytics SDK Xamarin component provides full bindings to the FollowAnalytics SDK for use in Xamarin Studio. With this component, Xamarin developers can target both iOS and Android devices with access to the full scope of the FollowAnalytics SDK, all while remaining in the C#/.NET ecosystem.

This document will cover app setup and the component installation process, as well as basic integration steps for iOS and Android.

For more information, please read the iOS and Android FollowAnalytics SDK documentations.

Installation

Download the FollowAnalytics SDK from the developer portal.

iOS

To install the iOS part of the SDK, follow these steps:

1. Right Click on project References.
2. Choose the .Net Assembly tab.
3. Go to Browse...
4. Add FollowAnalytics.iOS.dll to your iOS Xamarin project References.

Android

To install the Android part of the SDK, add FollowAnalytics.Android.dll to your Android Xamarin project References.

Initialize with your API keys

iOS

• In your AppDelegate.cs add at the top:

using FollowAnalyticsSDK;

• In the method FinishedLaunching, right after the loadApplication, add:

 try
 {
     bool isVerbose = false;
     #if DEBUG
        isVerbose = true;
     #endif

     FollowAnalytics.Configuration configuration = new FollowAnalytics.Configuration((obj) =>
     {
        obj.apiKey = "YOUR_API_KEY";
        obj.isVerbose = isVerbose;
        obj.archiveInAppMessages = true/false; (optional)
        obj.archivePushMessages = true/false; (optional)
        obj.apiMode = FollowAnalytics.APIMode.Prod/FollowAnalytics.APIMode.Dev; (optional)
        obj.isDataWalletEnabled = true/false; (optional)
        obj.appDelegateSwizzle = true/false; (optional)
        obj.crashReportingEnabled = true/false; (optional)
        obj.env = ""; (optional)
        obj.envProtocol = "https"; (optional)
        obj.onDataWalletPolicyChange = delegate () (optional)
        {
        // Something TO DO
        };
     });

    FollowAnalytics.iOS.Init(configuration, launchOptions);
 }
 catch (System.Exception ex)
 {
    System.Diagnostics.Debug.WriteLine(ex);
    return false;
 }

Android

1. To declare your Android API key, in your manifest, add the following line within the application tag:

<application>
  [...]
  <meta-data android:name="FAID" android:value="YOUR_API_KEY"/>
  [...]
</application>

Custom Configuration

Since Google has refactored of its "Notification system" for Android 8.0 ("Oreo"), (details here) FollowAnalytics SDK uses default_notification_fa as an id for id for the NotificationChannel object.

In order to customize the behavior of FollowAnalytics SDK, it is possible to change the default configuration.

You can customize Opt-Out analytics and Datawallet.

In order to achieve this, create a class that extends to FollowAnalytics.Configuration and override only the methods that are necessary to change.

using System;
using Android.App;

namespace FollowAnalyticsSDK.Android.Sample
{
    public class MyConfiguration : FollowAnalytics.Configuration
    {

        public override bool GetOptInAnalyticsDefault()
        {
            return true/false;
        }

        public override bool IsDataWalletEnabled()
        {
            return true/false;
        }

        public override string GetDefaultPolicyFilePath()
        {
            return "YOUR_DEFAULT_POLICY_PATH";
        }

        public override void OnDataWalletPolicyChanged()
        {
            Application.Context.StartActivity(typeof(PolicyActivity));
        }

    }
}

Finally, add a meta-data tag under the application tag to your android manifest. The value of android:name must be identical as com.followanalytics.configuration and the value of android:value is the path of the configuration class:

<application>
[...]
<meta-data
android:name="com.followanalytics.configuration"
android:value="the_full_path_of_your_configuration_class"/>
[...]
</application>

For instance:

<meta-data
android:name="com.followanalytics.configuration"
android:value="com.followapps.android.sdkdemo.Configuration"
/>

Now, FollowAnalytics SDK will start by default with the value associated to the methods overridden in the customized configuration class.

• In the file of your Application class, add, at the top:

using FollowAnalyticsSDK;

• In the same file, in the onCreate method, add:

FollowAnalytics.Android.Init(this);

Necessary project capabilities

iOS

If your app code is already registered to send push notifications, skip this step. Otherwise, add a call to registerForPush following the initialization line you added previously:

FollowAnalytics.RequestNotificationCenterDefaultAuthorisation();

Android

The FollowAnalytics SDK supports push notifications based on Firebase Cloud Messaging. In order to make it work:

1. Add the required packages to your project

   Xamarin.Firebase.Common
   Xamarin.Firebase.Iid
   Xamarin.Firebase.Messaging
   

2. Add the FCM Receiver to your manifest

   <receiver android:name="com.google.firebase.iid.FirebaseInstanceIdInternalReceiver" android:exported="false" />
   <receiver android:name="com.google.firebase.iid.FirebaseInstanceIdReceiver" android:exported="true" android:permission="com.google.android.c2dm.permission.SEND">
   <intent-filter>
   <action android:name="com.google.android.c2dm.intent.RECEIVE" />
   <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
   <category android:name="${applicationId}" />
   </intent-filter>
   </receiver>
   

3. Add the MyFirebaseIIDService.cs file :

   using System;
   using Android.App;
   using Firebase.Iid;
   using Android.Util;
   
   namespace YOUR_NAME_SPACE
   {
       [Service]
       [IntentFilter(new[] { "com.google.firebase.INSTANCE_ID_EVENT" })]
       public class MyFirebaseIIDService : FirebaseInstanceIdService
       {
           const string TAG = "MyFirebaseIIDService";
           public override void OnTokenRefresh()
           {
               var refreshedToken = FirebaseInstanceId.Instance.Token;
               Log.Debug(TAG, "Refreshed token: " + refreshedToken);
               SendRegistrationToServer(refreshedToken);
           }
   
   
           void SendRegistrationToServer(string token)
           {
               FollowAnalytics.Android.SetPushToken(token);
               // Implement other processes
           }
       }
   }
   

4. Add the MyFirebaseMessagingService.cs file :

   using System;
   using Android.App;
   using Android.Content;
   using Android.Media;
   using Android.Util;
   using Firebase.Messaging;
   
   namespace FollowAnalyticsSDK.Android.Sample
   {
       [Service]
       [IntentFilter(new[] { "com.google.firebase.MESSAGING_EVENT" })]
       public class MyFirebaseMessagingService : FirebaseMessagingService
       {
           const string TAG = "MyFirebaseMsgService";
           public override void OnMessageReceived(RemoteMessage message)
           {
               FollowAnalytics.Android.ProcessFirebaseMessage(Application.Context, message);
           }
       }
   
   }
   

Define the URL scheme

To allow users to retrieve their device ID for campaign testing and tagging plan debugging, you need to define a URL scheme in your iOS and Android projects.

iOS

1. Make sure that the Rivets component is installed. If not, install with NuGet.

2. Open your app's Info.plist file, and under the Advanced tab, in the URL Types section, add a new URL Type like:

   

3. Make sure that the bundle ID of your app appears in the URL Schemes field as shown in the screenshot (where com.follow-apps.followme.inHouse needs to be replaced).

Android

1. Edit your AndroidManifest.xml file to add this:

<activity android:name="com.followapps.android.internal.activities.DeviceIdActivity" >
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="followanalytics.com"
            android:path="/deviceId"
            android:scheme="%YOUR_APP_PACKAGE_NAME%" />
    </intent-filter>
</activity>

1. Replace %YOUR_APP_PACKAGE_NAME% with the Android package name of your app.

Analytics

App tags

The SDK allows you to implement log events and errors in your code. The following methods that you can call with the SDK are the following:

FollowAnalytics.LogEvent(string eventName);
FollowAnalytics.LogEvent(string eventName, string details);
FollowAnalytics.LogEvent(string eventName, IDictionary<string, string> details);

FollowAnalytics.LogError(string eventName);
FollowAnalytics.LogError(string eventName, string details);
FollowAnalytics.LogError(string eventName, IDictionary<string, string> details);

Use the eventName as the unique identifier of your tag. Use the details section to add specific details or context. Events can be renamed later: the name that you give to your event here can be overridden in the FollowAnalytics UI.

The details field can either be a String or a Hash, so that you can associated multiple key-values for additional context.

For instance, logging the appearance of a view could be done the following way:

FollowAnalytics.LogEvent("Product view", "Product reference");

var options = new Dictionary<string, string>();
options["product_id"] = "ABCD123";
options["product_category"] = "Jeans";
FollowAnalytics.LogEvent("Add product to cart", options);

User ID and attributes

User ID

If users can sign in somewhere in your application, you can specify their identifier to the SDK. This way, you will be able to relate crashes to specific users, link your users between FollowAnalytics and your CRM, and more.

It is recommended to use a cryptographic number that uniquely ties your customer to you.

To register the user identifier, use:

FollowAnalytics.SetUserId("1547521wed2155w57e02dwe574");

If you want to remove the user identifier (in case of a sign out for instance) use the following method:

FollowAnalytics.SetUserId(null);

At any moment, you can retrieve the current user ID this way:

string user_id = FollowAnalytics.GetUserId(); // returns null if there is no user id

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.SetDateOfBirth(DateTime.Today);
FollowAnalytics.UserAttributes.SetProfilePictureUrl("https://picture/picture");

They are "predefined" in the sense that they will be attached to default fields on your user profiles.

To unset an attribute, set it to null. For instance :

FollowAnalytics.UserAttributes.SetFirstName(null);

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_number", 1);
FollowAnalytics.UserAttributes.SetNumber("key_double", 32.428);
FollowAnalytics.UserAttributes.SetDate("key_date", DateTime.Today);
FollowAnalytics.UserAttributes.SetDateTime("key_dateTime", Date.Now);
FollowAnalytics.UserAttributes.SetString("key_string", "string");
FollowAnalytics.UserAttributes.SetBoolean("key_bool", true);

For example, to set the user's job:

FollowAnalytics.UserAttributes.SetString("job", "Taxi driver");

Delete a custom attribute value

You can clear the value of an attribute using its key. For instance, to delete the user's job:

FollowAnalytics.UserAttributes.Clear("job");

Set of Attributes

You can add or remove an item to or from a set of attributes.

To add an item:

FAFollowApps.UserAttributes.AddToSet("fruits", "apple");

To add several items:

FAFollowApps.UserAttributes.AddToSet("fruits", "orange", "banana");

To remove an item:

FAFollowApps.UserAttributes.RemoveFromSet("fruits", "orange");

And to clear a set:

FAFollowApps.UserAttributes.ClearSet("fruits");

Opt-Out Analytics

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 on FollowAnalytics class:

FollowAnalytics.SetOptInAnalytics(bool optInAnalytics);
FollowAnalytics.GetOptInAnalytics();

Please see additional doc in the new FollowAnalytics and FollowAnalyticsConfiguration interface for more details.

Additionally, if the opt-in by default policy doesn't suit your use case you can change it by setting the optInAnalyticsDefault on FollowAnalyticsConfiguration.

bool optInAnalyticsDefault;

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

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

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.

You're able to access the functionality by enabling the Deep Linking switch in our UI, when creating a campaign. There you'll find the field App Link that expects you to enter these types of URL 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 or for in-app button actions.

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

iOS

In order to receive the custom parameters sent within a Push Notification or an In App message payload, you'll need to enable the swizzling of your appDelegate

Your Configuration object must contain the obj.appDelegateSwizzle attribute with its value as true :

FollowAnalytics.Configuration configuration = new FollowAnalytics.Configuration((obj) =>
{
    ...
    obj.appDelegateSwizzle = true;
});

Add the following method inside the class:

public void FollowAppsShouldHandleParameters(NSDictionary customParameters, NSString actionIdentifier, NSString actionTitle, Action completionHandler) {
    //For example
    if (customParameters["my_key"] != null) {
        // do what you need to do.
    }
    if (completionHandler != null) {
      completionHandler();
    }
}

Android

In FollowAnalytics campaigns through our platform, you can specify deep-linking parameters, e.g. in your push messages or for in-app button actions.

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

To obtain these parameters, you can extend the Com.Followanalytics.FollowAnalytics.DefaultMessageHandler class, like in the following example:

//import the namespace
using System.Collections.Generic;
using Android.Content;

....
public class CustomMessageHandler : Com.Followanalytics.FollowAnalytics.DefaultMessageHandler
{
    public override void OnInAppMessageClicked(Context p0, string p1, IDictionary<string, string> p2){
        base.OnInAppMessageClicked(p0,p1,p2);

        //Write code to process information
    }

    public override void OnPushMessageClicked(Context p0, string p1, IDictionary<string, string> p2){
        base.OnPushMessageClicked(p0, p1, p2);

        //Write code to process information
    }

    public override void OnPushMessageClicked(Context p0, IDictionary<string, string> p1){
        base.OnPushMessageClicked(p0, p1);

        //Write code to process information
    }
}

If you chose to define a custom MessageHandler, you must declare it in your application on your AndroidManifest file as meta-data.

In order to do this, you need to retrieve the value associated to the name of the Android Callable Wrapper for your custom implementation.

The easiest way to get the value at runtime, is to implement the following code:

//import the namespace in your activity
using Android.Util;

//implement this code in one of the lifecycle method of your activity
Log.Debug("FA","The CustomMessageHandler name is : " + Java.Lang.Class.FromType(typeof(<ABSOLUTE_PATH_OF_THE_CLASS>.<NAME_OF_THE_CUSTOM_MESSAGE_HANDLER_CLASS>)).Name);

For instance:

Log.Debug("FA","The CustomMessageHandler name is : " + Java.Lang.Class.FromType(typeof(FollowAnalyticsSDK.Android.Sample.CustomMessageHandler)).Name);

This will output a similar result, at runtime, in the Logcat console:

FA  D  The CustomMessageHandler name is : md5dc1df9376dd70f35e4f0f156de0b2eea.CustomMessageHandler

Finally, copy the value and paste it to the attribute android:value in your <meta-data> tag.

For instance:

<application>
   [...]
    <meta-data android:name="com.followanalytics.deeplinking.handler" android:value="md5dc1df9376dd70f35e4f0f156de0b2eea.CustomMessageHandler"/>
   [...]
</application>

Consider to test those changes before removing the code which retrieves the value associated to the name of the Android Callable Wrapper.

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 geofencing campaigns you need to enable geofence

FollowAnalytics.EnableGeoffencing();

Pausing in-app campaigns

To prevent the SDK from displaying rich campaigns use the following method:

FollowAnalytics.InApp.PauseCampaignDisplay();

To resume the SDK from displaying rich campaigns use the following method:

FollowAnalytics.InApp.ResumeCampaignDisplay();

Data Wallet

Policy download and consent

Now that the Data Wallet is enabled, the SDK will automatically download the new policies as they are published. In order to deal with the currently known policy, call the API with the following methods:

DataWallet.Policy policy = FollowAnalytics.DataWallet.GetPolicy();  // gets the current policy

BOOL policyIsRead =  FollowAnalytics.DataWallet.isRead;  // true if the current policy is considered accepted

FollowAnalytics.DataWallet.SetIsRead(true);  // informs the SDK that the user has accepted the current policy

There could only be one active policy at a time. When a new policy becomes available online, the SDK will call on the main thread onDataWalletPolicyChange, callback set on the FollowAnalyticsConfiguration. To set this up before starting the SDK, include the following code:

iOS

FollowAnalytics.Configuration configuration = new FollowAnalytics.Configuration((obj) =>
{
    ...
    obj.isDataWalletEnabled = true/false;
    obj.onDataWalletPolicyChange = delegate () (optional)
    {
    };
});

Android

public class MyConfiguration : FollowAnalytics.Configuration
{

    ...

    public override bool IsDataWalletEnabled()
    {
        return true;
    }

    public override void OnDataWalletPolicyChanged()
    {
        Application.Context.StartActivity(typeof(PolicyActivity));
    }

}

At each major policy update, there needs to be consent from the client. When the user accepts a policy call [FollowAnalytics.dataWallet setIsRead:true] to mark the current policy as "read". In other words:

• If FollowAnalytics.DataWallet.isRead is false, the current policy major version has yet to be accepted by the user.
• If the current policy is accepted, FollowAnalytics.DataWallet.isRead becomes true.

The SDK records the major version of the current policy for future reference. By default, if no other configuration is present, the SDK will return a default policy with version 0.0. This policy is always read. You should check for version 0.0 and handle it appropriately.

Custom default policy

If you want to provide a custom default policy for your users, download the policy JSON file from the back office and add it to your app, then modify the configuration to use it as follows:

iOS

FollowAnalytics.Configuration configuration = new FollowAnalytics.Configuration((obj) =>
{
    obj.dataWalletDefaultPolicyPath = "YOUR_POLICY_PATH";
});

Android

public class MyConfiguration : FollowAnalytics.Configuration
{
    ...

    public override string GetDefaultPolicyFilePath()
    {
        return "YOUR_POLICY_PATH";
    }
}