Initial SDK setup

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.

Install the SDK

  1. Download the FollowAnalytics SDK from the developer portal.

iOS

  1. Add FollowAnalyticsSDK.iOS.dll to your iOS Xamarin project References.

Android

  1. Add FollowAnalytics.Android.dll to your Android Xamarin project References.

Initialize with your API keys

Prepare your API keys

Be sure to have your API keys for this step of the configuration. If you are not sure where to find them, please reach out to your Customer Success Manager or message support@followanalytics.com

iOS

Access to the "ApplicationDelegate"

In order to get the original applicationDelegate for your iOS application, please use the FollowAnalytics.iOS.GetApplicationDelegate() method.

Android

Google Play Service version

The SDK requires version 8.4.0 or higher of the google-play-service dependency. Install or update it from the Android Extras section using the Android SDK manager (run 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>
  2. In the file of your Application class, add, at the top:

    using FollowAnalyticsSDK;
  3. In the same file, in the onCreate method, add:

    FollowAnalytics.Android.Init(this);

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:

    URL Scheme

  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>
  2. Replace %YOUR_APP_PACKAGE_NAME% with the Android package name of your app.

Register for notifications

iOS

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

FollowAnalytics.iOS.RegisterForPushNotifications();

Android

Build in release mode

The application must be built in release mode in order to receive push notifications

The FollowAnalytics SDK supports push notifications based on Google Cloud Messaging. It is automatically integrated in FollowAnalytics SDK.

By default, Android does not ask permission from users to show push notifications. If your application handles an opt-out state, you can use the following methods to inform FollowAnalytics:

// check the status
FollowAnalytics.Android.ArePushNotificationsEnabled();
// opt user in
FollowAnalytics.Android.SetPushNotificationsEnabled(true);
// opt user out
FollowAnalytics.Android.SetPushNotificationsEnabled(false);

Logging

Data sent in debug mode will not appear on dashboards

When your application 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.

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.

Events vs Attributes

The FollowAnalytics SDK allows you to tag both events and attributes. If you are unsure about the difference, please refer to the corresponding FAQ entry.

Tag events

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

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

In both cases, attributes can be used in segments and campaigns to target users.

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

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_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");

Advanced Use Cases

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.

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 be able to receive the custom parameters sent within a Push Notification or an In App message payload you'll need to implement the FollowAppsShouldHandleParameters method.

Your AppDelegate class must implement the FollowAnalytics.iOS.IAppDelegate interface. For example:

using System;

public class AppDelegate : UIApplicationDelegate, FollowAnalytics.iOS.IAppDelegate
{
    ...
}

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

Nothing appears in Logcat console

The problem can be due to the wrong absolute path or the activity that has not executed the line of code (wrong place). Consider to recheck your code.

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>

Don't change the attribute android:name

The content associated to the attribute android:name must not be changed ! It is used by the FollowAnalytics SDK in order to find the customized class.

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

Control over campaigns

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 FollowAppsShouldHandleWebViewUrl method in your AppDelegate:

public void FollowAppsShouldHandleWebViewUrl(NSUrl url, string urlTitle, NSDictionary parameters) {
    //do what you need to do.
}

This requires you to have implemented the FollowAnalytics.iOS.IAppDelegate interface:

public class AppDelegate : UIApplicationDelegate, FollowAnalytics.iOS.IAppDelegate
{
    ...

Pausing in-app campaigns

You can prevent in-app campaigns from being displayed on certain views of your app. This can be useful when you are displaying a media content or if the topmost screen is only shown for a few seconds.

When the mechanism is paused, the campaigns are deactivated. Whenever the mechanism is resumed, the campaigns are re-activated.

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

Tip: Use the lifecycle concepts from android to control campaigns.

To prevent the SDK from displaying the campaigns on a given activity, call the Pause method before the creation of an activity in order to block the campaigns.

Resume the campaigns by calling the Resume method on any other place of the application which will activate them.