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.

2. Add FollowApps.iOS.dll to your iOS Xamarin project References.

3. Link the required library for iOS, under iOS project > iOS build, in "additional mtouch arguments":

   -gcc_flags="-framework Security -framework SystemConfiguration -framework CoreTelephony -framework CoreLocation -framework PassKit -framework WatchConnectivity -lc++ -lsqlite3 -lresolv"
   

4. Add FollowApps.DroidSDK.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:

  FollowAnalytics.iOS.Init("YOUR_API_KEY", FADEBUG, options);
  

Android

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

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

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

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

• Install the Rivets component from the Component Store if you haven't already done so

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

  

  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

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

Where %YOUR_APP_PACKAGE_NAME% should be replaced by the Android package name of your app.

Register for notifications

iOS

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

FollowAnalytics.iOS.RegisterForPushNotifications();

Android

The FollowAnalytics SDK supports push notifications based on Google Cloud Messaging.

1. Add the following permissions to your manifest:

   <permission android:name="%YOUR_APP_PACKAGE_NAME%.permission.C2D_MESSAGE"
                   android:protectionLevel="signature" />
    <uses-permission android:name="%YOUR_APP_PACKAGE_NAME%.permission.C2D_MESSAGE" />
   

2. Add the GCM Receiver to your manifest

   <receiver
           android:name="com.google.android.gms.gcm.GcmReceiver"
           android:exported="true"
           android:permission="com.google.android.c2dm.permission.SEND"
           >
       <intent-filter>
           <action android:name="com.google.android.c2dm.intent.RECEIVE"/>
           <!-- for Gingerbread GSF backward compat -->
           <action android:name="com.google.android.c2dm.intent.REGISTRATION"/>
           <category android:name="%YOUR_APP_PACKAGE_NAME%"/>
       </intent-filter>
    </receiver>
   

By default, Android does not ask permission to the users to show push notifications. If your app 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

Tag events

The SDK allows you to log events happening in your code. These are the two methods you can call on the SDK:

FollowAnalytics.LogEvent("my event name", "my event detail");
FollowAnalytics.LogError("my error", "my error detail");

Use the name as the unique identifier of your tag, use the details section to add specific details, 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 app, 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.

This identifier is usually an e-mail address, client identifier, phone number, or anything else that uniquely ties your customers to you.

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

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 example, 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.

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 type 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, you should implement the FollowAnalytics.iOS.IAppDelegate interface. For example:

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

This section will be defined later on.

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

Android

This section will be defined later on.

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, for instance.

Any campaign supposed to be displayed when the mechanism is paused is stacked and shown as soon as it is resumed.

To tell the SDK to prevent the display of rich campaigns, and then to activate it back, use the following methods:

FollowAnalytics.InApp.PauseCampaignDisplay();
FollowAnalytics.InApp.ResumeCampaignDisplay();