Prerequisites

Before you start to integrate the SDK into your app, you need to register your app and generate its API key on the FollowAnalytics platform by following the instructions here.

Getting Started

In this section, you will find the basic steps to integrate the SDK into your app:

• Installing the SDK in your project with Gradle
• Initializing the SDK using your API key
• Setting up push notifications

Once the integration is finished, you can validate your setup, and start tagging events and saving attributes in your application.

Install using Gradle

The best way to install the SDK is with Gradle:

1. Fetch the library from the private nexus repository

2. Add the FollowAnalytics SDK repository to your project-level build.gradle file:

   allprojects {
       repositories {
           ...
           maven {
               url 'https://nexus.follow-apps.com/nexus/content/repositories/releases/'
           }
       }
   }
   

3. Add the FollowAnalytics SDK dependency to your module-level build.gradle file:

   dependencies {
     ...
     implementation "com.followapps.android:sdk:7.3.1"
     ...
   }
   

1. Add the following lines to your module-level build.gradle file:

   android {
     ...
       applicationVariants.all { variant ->
           variant.outputs.each { output ->
               def processManifest = output.getProcessManifestProvider().get()
               processManifest.doLast { task ->
                   def outputDirectory = task.multiApkManifestOutputDirectory.asFile.get()
                   File manifestOutFile = file("$outputDirectory/AndroidManifest.xml")
                   if (manifestOutFile.exists() && manifestOutFile.canRead() && manifestOutFile.canWrite()) {
                       def updatedManifest = manifestOutFile.getText().replaceAll("(?=com.followanalytics.scheme.placeholder)(.*)(?=\")",
                               variant.applicationId.toLowerCase())
                       manifestOutFile.write(updatedManifest, 'UTF-8')
                   }
               }
           }
       }
     ...
   }
   

Once installation is over you will notice that dependencies and permissions are automatically added. For more information on dependencies and permissions, refer to the two subsections .

Dependencies

Using Gradle, dependencies will automatically be added while merging the manifest. The FollowAnalytics SDK depends on the following libraries:

implementation 'androidx.legacy:legacy-support-v4:1.0.0'
implementation 'androidx.cardview:cardview:1.0.0'
implementation 'androidx.appcompat:appcompat:1.0.0'
implementation 'com.google.android.gms:play-services-location:16.0.0'
implementation 'com.google.firebase:firebase-messaging:17.4.0'
implementation 'me.leolin:ShortcutBadger:1.1.19@aar'

Permissions

Automatically added permissions

Using Gradle, the SDK automatically adds the following normal permissions to your app manifest.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Initialize with your API key

To initialize the FollowAnalytics SDK, call FollowAnalytics.init(Context context, Configuration configuration) inside the onCreate() method of the Application class.

Open your Application subclass, or create a new one, and add the following lines to override the onCreate method:

public class MyAwesomeApplication extends Application {
  @Override
  public void onCreate(){
    [...]
    FollowAnalytics.init(this.getApplicationContext(), new FollowAnalytics.Configuration() {
      {
            this.apiKey = "MY_API_KEY";
            this.apiMode = BuildConfig.DEBUG ? ApiMode.DEV : ApiMode.PROD;
      }
    });
    [...]
  }
}

class MyAwesomeApplication : Application() {

    override fun onCreate() {
        [...]
        FollowAnalytics.init(this.applicationContext, object : FollowAnalytics.Configuration() {

            init {
                apiKey = "MY_API_KEY"
                apiMode = if (BuildConfig.DEBUG) ApiMode.DEV else ApiMode.PROD
            }
        })
        [...]
    }
}

If you just created an Application subclass, remember to declare it in your AndroidManifest.xml file:

<application
    android:name=".MyAwesomeApplication"
/>

Setting up push notifications

The FollowAnalytics SDK supports push notifications based on Firebase Cloud Messaging or Huawei Push Kit. To set up push notifications, you will need to:

• Add the Firebase SDK to your app if you want to send Push campaigns using Google push services.
• Add the Huawei Moble Services Core SDK to your app if you want to send Push campaigns using Huawei push services.
• Set up the FollowAnalytics Notification Channel name.

Add the Firebase SDK

• Register your Android project to Firebase.
• Add your FCM key to your app on the FollowAnalytics platform.
• Install the Cloud Messaging library in your Android project and implement token and message handling.

Register to Firebase

If you haven't done so yet, you will need to register your project to Firebase. To do so, follow the instructions from the official Firebase documentation.

Add your FCM key

1. From the Firebase console home page, open your project.

2. Click the Gear icon, and select Project settings:

   

3. Select the Cloud Messaging tab, and copy the Server key:

   

4. From the FollowAnalytics platform, go to Administration -> Apps -> YourApp, select the Push Settings tab, select the Google push service, and paste the Server key you copied previously into the Firebase Cloud Messaging (FCM) key field:

   

5. Save the changes

Install Firebase Cloud Messaging

1. Add the Firebase Cloud Messaging library dependency in your app-level build.gradle file:

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

2. Create a class which extends FirebaseMessagingService and override onMessageReceived and onNewToken as following:

   Java

   import com.followanalytics.FollowAnalytics;
   import com.google.firebase.messaging.FirebaseMessagingService;
   import com.google.firebase.messaging.RemoteMessage;
   
   public class MyFirebaseMessagingService extends FirebaseMessagingService {
   
       /**
        * This implemenation allows the FA SDK to receive Push campaigns
        */
       @Override
       public void onMessageReceived(RemoteMessage remoteMessage) {
           FollowAnalytics.processFirebaseMessage(this, remoteMessage);
       }
   
   
       /**
        * This implemenation allows the FA SDK to send the device token to the FA platform
        */
       @Override
       public void onNewToken(String token){
           FollowAnalytics.setFirebasePushToken(token);
       }
   }
   

   Kotlin

   import com.followanalytics.FollowAnalytics
   import com.google.firebase.messaging.FirebaseMessagingService
   import com.google.firebase.messaging.RemoteMessage
   
   class MyFirebaseMessagingService : FirebaseMessagingService() {
   
       /**
        * This implemenation allows the FA SDK to receive Push campaigns
        */
       override fun onMessageReceived(remoteMessage: RemoteMessage) {
           FollowAnalytics.processFirebaseMessage(this, remoteMessage)
       }
   
   
       /**
        * This implemenation allows the FA SDK to send the device token to the FA platform
        */
       override fun onNewToken(token: String) {
           FollowAnalytics.setFirebasePushToken(token)
       }
   }
   

3. Add the service previously created to the AndroidManifest inside your <application> tag. Make sure to set android:name to the relative path to your service:

   <service
       android:name=".MyFirebaseMessagingService"
       android:exported="false">
       <intent-filter>
           <action android:name="com.google.firebase.MESSAGING_EVENT"/>
       </intent-filter>
   </service>
   

Add the Huawei Mobile Services Core SDK

To have your app configured for Huawei Moble Services you have to:

• Register your Android project to Huawei AppGallery Connect.
• Add your Client Id and Client Secret to your app on the FollowAnalytics platform.
• Install the Push Kit library in your Android project and implement token and message handling.

Register to Huawei AppGallery Connect

If you haven't done so yet, you will need to create an AppGallery Connect Project and add your app to this project. To do so, follow the instructions from the official Huawei Push Kit documentation. Make sure to configure the Signing Certificate Fingerprint and to enable Push Kit, as described in Huawei's documentation.

Add your Client Id and Client Secret

1. Sign in to AppGallery Connect and click My projects.

2. Find your app project, and click the desired app name.

3. In the App information section, make sure you added the agconnect-services.json file to your project after you enabled Push Kit when you followed the Huawei Push Kit documentation:

   

4. Still in the App information section, make sure the SHA-256 certificate fingerprint is well defined:

   

5. Still in the App information section, take note of the App ID and App Secret:

   

6. From the FollowAnalytics platform, go to Administration -> Apps -> YourApp, select the Push Settings tab, select the Huawei push service, and copy the App ID and the App Secret fom the previous step into their related fields:

   

7. Save the changes

Install Push Kit

1. Add the Push Kit library dependency in your app-level build.gradle file:

   implementation 'com.huawei.hms:push:5.0.4.302'
   

2. Create a class which extends HmsMessageService and override onMessageReceived and onNewToken as following:

   Java

   import com.followanalytics.FollowAnalytics;
   import com.huawei.hms.push.HmsMessageService;
   import com.huawei.hms.push.RemoteMessage;
   
   public class MyHuaweiMessagingService extends HmsMessageService {
   
       /**
        * This implemenation allows the FA SDK to receive Push campaigns
        */
       @Override
       public void onMessageReceived(RemoteMessage remoteMessage) {
           FollowAnalytics.processHmsMessage(this, remoteMessage);
       }
   
       /**
        * This implemenation allows the FA SDK to send the device token to the FA platform
        */
       @Override
       public void onNewToken(String token) {
           FollowAnalytics.setHmsPushToken(token);
       }
   }
   

   Kotlin

   import com.followanalytics.FollowAnalytics
   import com.huawei.hms.push.HmsMessageService
   import com.huawei.hms.push.RemoteMessage
   
   class MyHuaweiMessagingService : HmsMessageService() {
   
       /**
        * This implemenation allows the FA SDK to receive Push campaigns
        */
       override fun onMessageReceived(remoteMessage: RemoteMessage) {
           FollowAnalytics.processHmsMessage(this, remoteMessage)
       }
   
       /**
        * This implemenation allows the FA SDK to send the device token to the FA platform
        */
       override fun onNewToken(token: String) {
           FollowAnalytics.setHmsPushToken(token)
       }
   }
   

3. Add the service previously created to the AndroidManifest inside your <application> tag. Make sure to set android:name to the relative path to your service:

   <service
       android:name=".MyHuaweiMessagingService"
       android:exported="false">
       <intent-filter>
           <action android:name="com.huawei.push.action.MESSAGING_EVENT"/>
       </intent-filter>
   </service>
   

Setup the FollowAnalytics Notification Channel name (Android 8.0 and above)

When you initialize the SDK, you can setup the name of the notification channel (whose id is default_notification_fa as mentionned above) created by the SDK. This name will displayed to the user in your application's settings. To do so, you need to override the value of the notificationChannelName attribute of the configuration object that you pass to the FollowAnalytics.init(Context context, Configuration configuration) method as below :

public class MyAwesomeApplication extends Application {
  @Override
  public void onCreate(){
    [...]
    FollowAnalytics.init(this.getApplicationContext(), new FollowAnalytics.Configuration() {
      {
            this.apiKey = "MY_API_KEY";
            this.apiMode = BuildConfig.DEBUG ? ApiMode.DEV : ApiMode.PROD;
            this.notificationChannelName = "MY_CHANNEL_NAME";
      }
    });
    [...]
  }
}

class MyAwesomeApplication : Application() {

    override fun onCreate() {
        [...]
        FollowAnalytics.init(this.applicationContext, object : FollowAnalytics.Configuration() {

            init {
                apiKey = "MY_API_KEY"
                apiMode = if (BuildConfig.DEBUG) ApiMode.DEV else ApiMode.PROD
                notificationChannelName = "MY_CHANNEL_NAME"
            }
        })
        [...]
    }
}

Validate your setup

Checking your SDK integration is valid can be done in two ways :

• At runtime, look into your console logs, some FollowAnalytics SDK logs will appear just after the app launch.

  For instance :

  --------Checking FollowAnalytics SDK setup--------
  Configuration
  OptInAnalyticsDefault : false
  Archive Push Messages : true
  Archive InApp Messages : true
  Notification Channel Name : My Channel
  ✅ ApiKey : HF7naIcl4f
  Environment Protocol : https
  Environment Domain : follow-apps.com
  ApiMode : PROD
  IsVerbose : true
  MaxBackgroundTimeWithinSession : 120
  Manifest
  ✅ Coarse location permission
  ✅ Fine location permission
  ✅ SDK services are all declared
  ✅ SDK receivers are all declared
  ✅ SDK activities are all declared
  

• Call the following method to display the validator in a dialog :

  FollowAnalytics.displaySDKValidatorDialog(Activity activity);
  

Analytics

To enrich User Analytics on the platform, FollowAnalytics SDK allows you to:

• Log your users events, errors and locations.
• Set attributes for your users.

Logs and attributes can also be used to target specific audiences when creating campaigns on the platform. You can find more information about the difference between logs and attributes here.

Our CSM team can help you creating relevant logs in your app. You can also find our recommendations here.

Logging Events and Errors

You can log Events and Errors in your app by calling the following methods:

static boolean logEvent(String name);
static boolean logError(String name);

static boolean logEvent(String name, String details);
static boolean logError(String name, String details);

static boolean logEvent(String name, Map<String, String> details);
static boolean logError(String name, Map<String, String> details);

Those methods return true if the log is valid, otherwise false is returned and an error description is printed to the console. If details exceeds 60KB it will be considered as invalid. A valid log will be sent to the platform only if opt-in analytics is true.

Use name as a unique identifier for your log. Use details to pass specific context to your log.

The following code shows an example of how you can log the viewing and the purchasing of a product:

FollowAnalytics.logEvent("Product view", "RF1672") // Product viewing

HashMap<String, String> details = new HashMap<String, String>();
details.put("reference", "RF1672");
details.put("payment_mode", "credit_card");
details.put("color", "red");
FollowAnalytics.logEvent("Product purchased", details); // Product purchasing

FollowAnalytics.logEvent("Product view", "RF1672") // Product viewing

val details : HashMap<String, String> = HashMap<String, String>();
details.put("reference", "RF1672");
details.put("payment_mode", "credit_card");
details.put("color", "red");
FollowAnalytics.logEvent("Product purchased", details); // Product purchasing

Logging Locations

There are two ways for logging locations:

static boolean logLocation(double latitude, double longitude);
static boolean logLocation(Location location);

Those methods return true if the log is valid, otherwise false is returned and an error description is printed to the console:

• if the location distance from the last logged location is less than 100 meters, the log will be ignored and logLocation returns false.
• if the location time interval from the last logged location is less that 1 hour, the log will be ignored and logLocation returns false.

A valid log will be sent to the platform only if opt-in analytics is true.

One way to use the logLocation method, is to implement a LocationCallback in your application, request location updates and log the last location update. FollowAnalytics SDK will take care of ignoring a location log if this location is too close from the last one:

LocationRequest locationRequest = LocationRequest.create()
        .setFastestInterval(5*1000)
        .setInterval(10*1000)
        .setMaxWaitTime(30*1000)
        .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);

FusedLocationProviderClient client = LocationServices.getFusedLocationProviderClient(your_context);
LocationCallback locationCallback = new LocationCallback() {
  @Override
  public void onLocationResult(LocationResult locationResult) {
    Location location = locationResult.getLastLocation();
    if (location != null) {
        FollowAnalytics.logLocation(location);
    }
  }
};
client.requestLocationUpdates(locationRequest, locationCallback, null);

val locationRequest = LocationRequest.create()
    .setFastestInterval(5 * 1000)
    .setInterval(10 * 1000)
    .setMaxWaitTime(30 * 1000)
    .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY)

val client = LocationServices.getFusedLocationProviderClient(your_context)
val locationCallback = object : LocationCallback() {
    override fun onLocationResult(locationResult: LocationResult) {
        val location = locationResult.lastLocation
        if (location != null) {
            FollowAnalytics.logLocation(location)
        }
    }
}
client.requestLocationUpdates(locationRequest, locationCallback, null)

User Attributes

A user can be defined by setting its identifier. This identifier is a string that you provide to the SDK to uniquely identify a user of your app. It can be an e-mail address, an identifier from your own backend (for instance a primary key), a phone number, or anything else that could allow you to uniquely identify a user.

Attributes (like first name, date of birth...) can be associated to a user if it's defined. Attributes are associated to the device when no user is defined.

When a user is defined, a user profile is created server-side and can be shared across apps.

You can set predefined as well as custom attributes.

Define a user

To define a user, set its user ID:

FollowAnalytics.setUserId("UniqueIdentifier");

To remove a user (for example in case of a sign out), just pass null to setUserId:

FollowAnalytics.setUserId(null);

Predefined attributes

To set predefined attributes, you can call the following methods on the UserAttributes class provided by the SDK:

static boolean setFirstName(String firstName);
static boolean setLastName(String lastName);
static boolean setEmail(String email);
static boolean setDateOfBirth(Date birthDate);
static boolean setGender(Gender gender);
static boolean setCountry(String country);
static boolean setCity(String city);
static boolean setRegion(String region);
static boolean setProfilePictureUrl(String profilePictureUrl);

Those methods return:

• true, when the attribute has been successfully saved and will be sent to the platform.
• false, if the passed argument is invalid or if opt-in analytics is false. In this case the attribute is not sent to the platform.

For example, to set the user Joe's city to "Paris", you would proceed as follows:

FollowAnalytics.UserAttributes.setFirstName("Joe");
FollowAnalytics.UserAttributes.setCity("Paris");

Custom attributes

In addition to predefined attributes, you can set your own custom attributes.

Set a custom attribute

To set custom attributes, you can call the following methods on the UserAttributes class provided by the SDK:

static boolean setNumber(String key, Integer value);
static boolean setNumber(String key, Long value);
static boolean setNumber(String key, Double value);
static boolean setNumber(String key, Float value);
static boolean setNumber(String key, BigDecimal value);
static boolean setString(String key, String value);
static boolean setBoolean(String key, Boolean value);
static boolean setDate(String key, Date value);
static boolean setDateTime(String key, Date value);

Those methods return:

• true, when the attribute has been successfully saved and will be sent to the platform.
• false, if the key or value is invalid or if opt-in analytics is false. In this case the attribute is not sent to the platform.

For instance, to set the user's job:

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

Delete a custom attribute value

You can delete 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 to a set:

FollowAnalytics.UserAttributes.addToSet("fruits", "apple"); // Adds "apple" to set "fruits"
FollowAnalytics.UserAttributes.addToSet("fruits", "strawberry"); // Adds "strawberry" to set "fruits"
FollowAnalytics.UserAttributes.addToSet("fruits", "lemon"); // Adds "lemon" to set "fruits"

// This is the equivalent, by using the variable number of arguments mechanism
FollowAnalytics.UserAttributes.addToSet("fruits", "apple", "strawberry", "lemon");

To remove an item from a set:

FollowAnalytics.UserAttributes.removeFromSet("fruits", "lemon"); // Removes "lemon" from set "fruits".
FollowAnalytics.UserAttributes.removeFromSet("fruits", "strawberry"); // Removes "strawberry" from set "fruits".

// This is the equivalent, by using the variable number of arguments mechanism
FollowAnalytics.UserAttributes.removeFromSet("fruits", "lemon", "strawberry");

To clear a set:

FollowAnalytics.UserAttributes.clearSet("fruits"); // Removes all items from set "fruits".

Opt-in Analytics

FollowAnalytics SDK opt-in analytics state define whether to send logs and attributes to the platform. Opt-in analytics is true by default, meaning logs and attributes will be sent to FollowAnalytics platform.

You can set it to opt-in analytics to false at SDK initialization by setting the optInAnalyticsDefault parameter to false in the FollowAnalytics.Configuration object passed to the initialization method. This is only used to set the default opt-in value at initialization. Moreover you can change the opt-in value at runtime.

To change opt-in analytics state at runtime, use the setOptInAnalytics method:

static void setOptInAnalytics(boolean state);

This value is persisted in memory and the opt-in analytics state is changed for all subsequent launch of your application, meaning optInAnalyticsDefault is ignored.

To retrieve the current opt-in analytics state, use the getOptInAnalytics method:

static boolean getOptInAnalytics();

GDPR

To request the data collected with FollowAnalytics SDK, call the following method on the GDPR class provided by the SDK:

static void requestToAccessMyData()

To delete the data that has been collected with FollowAnalytics SDK, call the following method on the GDPR class provided by the SDK:

 static void requestToDeleteMyData()

Campaigns

In this section, we cover all the necessary for your app to handle InApp and Push campaigns sent from the FollowAnalytics platform. We will also see how you can take advantage of the SDK's capabilities, with concret examples.

Before you start, make sure the SDK is properly integrated into your app by carefully follow our Getting Started guide.

Opt-in Notifications

The FollowAnalytics SDK opt-in notifications status defines whether your app will receive notifications from your Push campaigns. Opt-in notifications is true by default, meaning notifications from your Push campaigns will be received by your app. This status is independent from the Android system notification authorization, which is also needed by your app to display notifications.

Thanks to this opt-in notifications status, you can implement a UI in your app to allow to choose whether to receive notifications, without the need to go to the Android notification authorization settings. Note that the opt-in notifications status will have no effect if the Android system notification authorization is not allowed, and in this case, your app will not receive notifications from your Push campaigns, whatever the opt-in notifications status.

To update your app UI to reflect the current opt-in notifications status, use the getOptInNotifications method:

static boolean getOptInNotifications();

To update the current opt-in notifications status upon UI change, use the setOptInNotifications method:

static void setOptInNotifications(boolean state);

It's also possible to set the opt-in notifications status to false at the SDK initialization by setting the optInNotificationsDefault parameter to false in the Configuration object passed to the initialization method. This is only used to set the default opt-in value at the first launch of the app. Note that calling setOptInNotifications() will persist the opt-in notifications status for all subsequent launch of your application, meaning optInNotificationsDefault will be ignored.

Customize push notifications

To customize the appearence and behavior of Push campaigns notifications, you have to override the onNotificationBuilding() method in the FollowAnalytics.Configuration class, which is called right before the notification is actually displayed on the device. In your implementation, you can use the FollowAnalytics.NotificationBuilder provided to customize the notification layout, or to add action buttons to the notification, as well as the FollowAnalytics.Message to retrieve the Push campaign information:

new FollowAnalytics.Configuration() {
    // ...
    @Override
    public void onNotificationBuilding(@NonNull FollowAnalytics.NotificationBuilder notificationBuilder, @NonNull FollowAnalytics.Message message) {
        // Put your notification customization here
    }
    // ...
}

object : FollowAnalytics.Configuration() {
    // ...
    override fun onNotificationBuilding(FollowAnalytics.NotificationBuilder notificationBuilder,  FollowAnalytics.Message message) {
        // Put your notification customization here
    }
    // ...
}

The FollowAnalytics.NotificationBuilder class is a subclass of the Android NotificationCompat.Builder class. You can use it as you would do with a regular NotificationCompat.Builder instances, except for the following methods, which have been deactivated and have no effect in FollowAnalytics.NotificationBuilder:

• setContentIntent(PendingItent), see the Behavior on notification action guide instead.
• addAction(int, CharSequence, PendingIntent) and addAction(NotificationCompat.Action action), see the Interactive notifications guide to see how to add actions to notifications.

Interactive notifications

An Interactive Notification is a notification containing custom action buttons that the user can access by revealing the notification:

When tapped, an action button will:

• Close the notification.
• Open the application if and only if this action is a foreground action (default action). The application is not opened if this action is a background action (see below how to create one).
• Execute the custom behavior you implemented for this notification action.

To create a campaign with Interactive Notifications:

• On the platform, create a Push Campaign and define a Category in the Interactive Notification section of the campaign editor. For our example, let's set this field to "NewContent".

• In your app, define the action names you want for your notification, we will call them actionIdentifiers. Those identifiers will be displayed as is on the platform in the Push Opened stats:

static final String DELETE = "Delete";
static final String VIEW = "View";
static final String REMIND = "Remind me tomorrow";

val DELETE = "Delete"
val VIEW = "View"
val REMIND = "Remind me tomorrow"

To add action buttons to your notification, you have to use either addAction(Context context, int icon, String actionLabel, String actionIdentifier) or addBackgroundAction(Context context, int icon, String actionLabel, String actionIdentifier) from theFollowAnalytics.NotificationBuilder class:

• The actionLabel argument is your localized String that represents your action button's text.
• The actionIdentifier is a unique identifier you provide for each of your action buttons. This identifier will be passed as an argument to the onNotificationAction callback, which will be called whenever an action button is clicked on.
• The addAction() method is to be used whenever the button should trigger a foreground action (i.e. immediately visible to the user), like opening a specific section of your app or opening a URL.
• The addBackgroundAction() method is to be used whenever the button will only trigger background actions, like downloading or updating content in the background. Any attempt to launch an activity from a background action will fail.

An example of adding buttons to the notification is available below. Please note how the "NewContent" field defined above is used.

    @Override
    public void onNotificationBuilding(@NonNull FollowAnalytics.NotificationBuilder notificationBuilder, @NonNull FollowAnalytics.Message message) {
        Context context = MyApplication.this;
        if (message.getCategory().equals("NewContent")) {
            notificationBuilder.addAction(context, android.R.drawable.ic_menu_send, context.getResources().getString(R.string.view), VIEW);
            notificationBuilder.addBackgroundAction(context, android.R.drawable.ic_menu_delete, context.getResources().getString(R.string.delete), DELETE);
            notificationBuilder.addBackgroundAction(context, android.R.drawable.ic_menu_agenda, context.getResources().getString(R.string.remind_me), REMIND);
        }
    }

    override fun onNotificationBuilding(context: Context, notificationBuilder: FollowAnalytics.NotificationBuilder, message: FollowAnalytics.Message) {
        val context = this@MyApplication
        if (message.category.equals("NewContent")) {
            notificationBuilder.addAction(context, android.R.drawable.ic_menu_send, context.resources.getString(R.string.view), VIEW)
            notificationBuilder.addBackgroundAction(context, android.R.drawable.ic_menu_delete, context.resources.getString(R.string.delete), DELETE)
            notificationBuilder.addBackgroundAction(context, android.R.drawable.ic_menu_agenda, context.resources.getString(R.string.remind_me), REMIND)
        }
    }

Behavior on notification action

By default, the SDK has the following behavior when the user opens a notification (i.e. tap on the notification's body) or taps on a notification's foreground action:

• The SDK will start your app's main Activity through an Intent with:

  • FLAG_ACTIVITY_CLEAR_TASK and FLAG_ACTIVITY_NEW_TASK as flags, this means all opened Activities are destroyed and your main Activity is created, any work in progress will be lost,
  • the defined custom parameters (key/values) as extras.

• If a URL has been defined in the campaign, the SDK will try to start a new Activity through an Intent with:

  • ACTION_VIEW as action,
  • the defined URL as data,
  • FLAG_ACTIVITY_CLEAR_TOP and FLAG_ACTIVITY_NEW_TASK as flags,
  • the defined custom parameters (key/values) as extras.

  This will let the Android system choose the best app for opening the provided URL. Note this Intent is sent after your app is opened.

By default, the SDK does nothing if the following actions are performed on the notication:

• the user taps on a notification's background action button,
• the user dismisses the noticiation (i.e. notification is swiped out).

You can define a custom behavior when the user interacts with a notification by implementing the onNotificationAction callback in FollowAnalytics.Configuration. This allows your app to follow a specific logic for each possible action on the notification.

You will find below an usage example for the onNotificationAction callback, taking into consideration we implemented customized notifications by adding a VIEW, DELETE and REMIND action buttons (see the example provided in the Interactive notifications section) :

new FollowAnalytics.Configuration() {

    /**
     * This method is executed when a action is performed on a notification.
     */
    @Override
    public void onNotificationAction(@NonNull FollowAnalytics.ActionInfo actionInfo) {
        switch (actionInfo.getIdentifier()) {
            case FollowAnalytics.ActionInfo.PUSH_OPEN:
                // The user tapped on the notification body
                if (!actionInfo.getParameters().isEmpty()) {
                    // Your behaviour to handle custom parameters (key/values)
                } else {
                    // Let the SDK opens the URL (default behavior)
                    super.onNotificationAction(actionInfo);
                }
                break;
            case FollowAnalytics.ActionInfo.PUSH_DISMISS:
                // Your behavior when the notification is explicitly dismissed by the user
                // Note this is a background action
                break;
            case VIEW:
                // Your behavior for a tap on the "View" foreground action button
                break;
            case DELETE:
                // Your behavior for a tap on the "Delete" background action button
                break;
            case REMIND:
                // Your behavior for a tap on the "Remind me tomorrow" background action button
                break;
        }
    }

}

object : FollowAnalytics.Configuration() {

    /**
     * This method is executed when a action is performed on a notification.
     */
    override fun onNotificationAction(actionInfo: ActionInfo) {
        when (actionInfo.identifier) {
            ActionInfo.PUSH_OPEN -> {
                // The user tapped on the notification body
                if (!actionInfo.parameters.isEmpty()) {
                    // Your behaviour to handle custom parameters (key/values)
                } else {
                    // Let the SDK opens the URL (default behavior)
                    super.onNotificationAction(actionInfo)
                }
            }
            ActionInfo.PUSH_DISMISS -> {
                // Your behavior when the notification is explicitly dismissed by the user
                // Note this is a background action
            }
            VIEW -> {
                // Your behavior for a tap on the "View" foreground action button
            }
            DELETE -> {
                // Your behavior for a tap on the "Delete" background action button
            }
            REMIND -> {
                // Your behavior for a tap on the "Remind me tomorrow" background action button
            }
        }
    }

}

The actionInfo argument provides all the action button details to your app. Here is a description of the FollowAnalytics.ActionInfo class :

Behavior on Push message reception

You can handle the reception of a Push campaign message by overriding the onPushMessageReceived callback in FollowAnalytics.Configuration. This allows you to access any Push campaign details at the message reception time and perform specific logic accordingly:

new FollowAnalytics.Configuration() {
        ...
        @Override
        public void onPushMessageReceived(@NonNull FollowAnalytics.Message message) {
            // YOUR BEHAVIOR
        }
        ...
}

object : FollowAnalytics.Configuration() {
    ...
    override fun onPushMessageReceived(message: FollowAnalytics.Message) {
        // YOUR BEHAVIOR
    }
    ...
}

You can use this callback to perform specific logic when a silent push message is received, for instance to download content in the background.

Another usage could be to cancel a notification as soon as it arrives, according to a specific the notification from your code, you can use the Message.cancelNotification(Context). Here is an example of how to use it :

new FollowAnalytics.Configuration() {
    // ...
    @Override
    public void onPushMessageReceived(M@NonNull FollowAnalytics.Message message) {
        if (/* specific logic */) {
            message.cancelNotification(MyApplication.this);
        }
    }
    // ...
}

object : FollowAnalytics.Configuration() {
    // ...
    override fun onPushMessageReceived(message: FollowAnalytics.Message) {
        if (/* specific logic */) {
            message.cancelNotification(this@MyApplication)
        }
    }
    // ...
}

Behavior on native InApp action

The SDK has the following behavior when the user closes an native InApp (i.e. Native Alert or Evaluation Booster) is closed by tapping on one of its native buttons:

• If a URL has been defined for this button, the SDK will try to start a new activity through an Intent with:

  • ACTION_VIEW as action,
  • the defined URL as data,
  • FLAG_ACTIVITY_CLEAR_TOP and FLAG_ACTIVITY_NEW_TASK as flags.

  This will let the Android system choose the best app for opening the provided URL.

• If no URL has been defined for this button, the SDK does nothing.

You can define a URL on a Native Alert button in the platform's campaign editor. For Evaluation Booster campaign, a URL is automatically set on the Rate button of the Positive answer dialog.

Additionally to the SDK behavior, you can define a custom behavior when the user closes a native InApp by implementing the onInAppNativeAction callback in FollowAnalytics.Configuration. This allows your app to follow a specific logic for each closing button:

new FollowAnalytics.Configuration() {

    /**
     * This method is executed when a Native Alert or Evaluation Booster dialog is closed by tapping a button.
     */
    @Override
    public void onInAppNativeAction(@NonNull FollowAnalytics.ActionInfo actionInfo) {
        // Your behavior
    }

}

object : FollowAnalytics.Configuration() {

    /**
     * This method is executed when a Native Alert or Evaluation Booster dialog is closed by tapping a button.
     */
    override fun onInAppNativeAction(actionInfo: ActionInfo) {
        // Your behavior
    }

}

The actionInfo argument provides all the InApp button details to your app. Here is a description of the FollowAnalytics.ActionInfo class :

Geofencing

The geofencing feature allows you to trigger campaigns when a user enters or leaves a given geographical area.

To use the geofencing feature, add the following permissions to your app manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" /> (Since Android 10)
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

Pausing and resuming 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.InApp.pauseCampaignDisplay();  // will pause campaign display
FollowAnalytics.InApp.resumeCampaignDisplay(); // will resume campaign display

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. Messages received by a device can be archived locally and accessed from the developer's code, formatted as a Message object. In order for you to enable the message archiving, you need to set the following Configuration properties at SDK initialization:

protected boolean archivePushMessages;
protected boolean archiveInAppMessages;

You will find below all the methods you need to handle all the archived Message.

FollowAnalytics.InApp.getAll() // Get all archived in-app messages
FollowAnalytics.Push.getAll()  // Get all archived push messages

FollowAnalytics.InApp.get("MESSAGE_ID") // Get an archived in-app message
FollowAnalytics.Push.get("MESSAGE_ID") // Get an archived push message

FollowAnalytics.InApp.delete(message.getId()) // Remove an in-app message from the archive
FollowAnalytics.Push.delete(message.getId())  // Remove a push message from the archive

FollowAnalytics.InApp.markAsRead(message.getId()) // Mark an archived iin-app message as read
FollowAnalytics.Push.markAsRead(message.getId()) // Mark an archived push message as read

FollowAnalytics.InApp.markAsUnread(message.getId()) // Mark an archived in-app message as unread
FollowAnalytics.Push.markAsUnread(message.getId()) // Mark an archived push message as unread

FollowAnalytics.InApp.display(message.getId()) // Re-display the InApp related to this message in the exact same way as it was displayed by the SDK at message reception.

And here is a description of the Message methods:

Web Views

If your app contains web views, you can use FollowAnalytics SDK from within your JavaScript code. This is possible using our FAWebView to display your web pages, instead of the regular Android WebView.

Using FAWebView

1. Declare the FAWebView element into your <layout>.xml. For instance:

   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:orientation="vertical"
       android:padding="20dp"
       android:layout_width="match_parent"
       android:layout_height="match_parent" >
   
       <com.followapps.android.FAWebView
           android:layout_width="match_parent"
           android:id="@+id/fa_webview"
           android:layout_height="match_parent"/>
   
   </LinearLayout>
   

2. In the corresponding activity which uses the <layout>.xml layout, retrieve the FAWebView instance:

   Java

   FAWebView faWebView = (FAWebView) view.findViewById(R.id.fa_webview);
   

   Kotlin

   val faWebView = findViewById<FAWebView>(R.id.fa_webview)
   

3. Load your HTML page in the FAWebView by using the loadUrl method:

   Java

   faWebView.loadUrl("file:///android_asset/webView.html");
   

   Kotlin

   faWebView.loadUrl("file:///android_asset/webView.html");
   

FollowAnalytics SDK JS interface

Here are the SDK methods you can call from the JavaScript code:

• Environment information and actions:

  FollowAnalytics.getUserId();
  FollowAnalytics.setUserId("aUserId");
  FollowAnalytics.getSDKPlatform();
  FollowAnalytics.getSDKVersion();
  FollowAnalytics.getDeviceId();
  FollowAnalytics.setOptInAnalytics(false);
  FollowAnalytics.getOptInAnalytics(); // Returns the string "true" if the opt-in analytics status is true, "false" otherwhise.
  FollowAnalytics.setOptInNotifications(false);
  FollowAnalytics.getOptInNotifications(); // Returns the string "true" if the opt-in notifications status is true, "false" otherwhise.
  FollowAnalytics.isRegisteredForPushNotifications() // Get the Push campaigns registration status. Will return "true" only if the Android system notification authorization is allowed AND the SDK opt-in notifications status is true. Otherwise, will return "false".
  FollowAnalytics.openNotificationSettingsIfNeeded();
  FollowAnalytics.setData("key", "value"); // To save and persist string data.
  FollowAnalytics.getData("key"); // To retrieve a previously saved string data from its key: note that "notificationAuthorization" is a reserved key returning
                                  // "true" if the Android system notification authorization is allowed, "false" otherwise, or null if not set.
  FollowAnalytics.requestInAppReview(); // To ask the user to rate/review your app. Because this method may or may not present the alert, it's not appropriate to call it in response to a button tap or other user action.
  

• Logging events/errors/locations:

  FollowAnalytics.logEvent("anEventName");
  FollowAnalytics.logEvent("anEventName", "anEventDetail");
  FollowAnalytics.logError("anErrorName");
  FollowAnalytics.logError("anErrorName", "anErrorDetail");
  FollowAnalytics.logLocation(48.8410646, 2.3210844);
  

• User attributes:

  FollowAnalytics.UserAttributes.setFirstName("aFirstName");
  FollowAnalytics.UserAttributes.setLastName("aLastName");
  FollowAnalytics.UserAttributes.setEmail("something@domain.com");
  FollowAnalytics.UserAttributes.setDateOfBirth(new Date("1998-08-01"));
  FollowAnalytics.UserAttributes.setGender(FollowAnalytics.Gender.MALE); // Can be MALE, FEMALE or OTHER
  FollowAnalytics.UserAttributes.setCountry("France");
  FollowAnalytics.UserAttributes.setCity("Paris");
  FollowAnalytics.UserAttributes.setRegion("Île-de-France");
  FollowAnalytics.UserAttributes.setProfilePictureUrl("https://picture_url");
  FollowAnalytics.UserAttributes.setNumber("aKey", 10.5);
  FollowAnalytics.UserAttributes.setDateTime("aKey", Date.now());
  FollowAnalytics.UserAttributes.setDate("aKey", Date.now());
  FollowAnalytics.UserAttributes.setString("aKey", "aString");
  FollowAnalytics.UserAttributes.setBoolean("aKey", true);
  FollowAnalytics.UserAttributes.addToSet("aSetKey", "aSetElement");
  FollowAnalytics.UserAttributes.removeFromSet("aSetKey", "aSetElement");
  FollowAnalytics.UserAttributes.clear("aKey");
  FollowAnalytics.UserAttributes.clearSet("aSetKey");
  

• InApp campaigns archiving:

  FollowAnalytics.InApp.display("messageId"); // Re-display a InApp as it was displayed by the SDK at the time it was received
  FollowAnalytics.InApp.markAsRead("messageId1", "messageId2"/*,..., "messageIdN"*/);
  FollowAnalytics.InApp.markAsUnread("messageId1", "messageId2"/*,..., "messageIdN"*/);
  FollowAnalytics.InApp.delete("messageId1", "messageId2"/*,..., "messageIdN"*/);
  FollowAnalytics.InApp.get("messageId"); // Returns an campaign Message json object as a String
  FollowAnalytics.InApp.getAll(); // Returns an array of campaign Message json object as a String
  

• Push campaigns archiving:

  FollowAnalytics.Push.markAsRead("messageId1", "messageId2"/*,..., "messageIdN"*/);
  FollowAnalytics.Push.markAsUnread("messageId1", "messageId2"/*,..., "messageIdN"*/);
  FollowAnalytics.Push.delete("messageId1", "messageId2"/*,..., "messageIdN"*/);
  FollowAnalytics.Push.get("messageId"); // Returns an campaign Message json object as a String
  FollowAnalytics.Push.getAll(); // Returns an array of campaign Message json object as a String
  

Make sure to test if FollowAnalytics object exists with if (typeof FollowAnalytics !== 'undefined'). This way, you can reuse the exact same code for your mobile web site without impact.

Watch face

Follow Analytics SDK can be used with a watch face.

The watch face architecture has a different approach relatively to Android architecture with their lifecycle that needs to be settle down.

Two different types of background and foreground states exist in CanvasWatchFaceService.Engine.class:

• onVisibilityChanged()
• onAmbientModeChanged()

The method onVisibilityChanged() will be executed whenever the watch face becomes visible or hidden in the smartwatch.

However, the method onAmbientModeChanged() will be executed whenever the device enters or exits ambient mode (this mode will switch to a black (hidden seconds) and white display (displayed seconds)).

Now in order to use watch face with FollowAnalytics SDK, two methods are available :

FollowAnalytics.WatchFace.enterForeground();
FollowAnalytics.WatchFace.enterBackground();

The function FollowAnalytics.WatchFace.enterForeground() triggers the information of entering in foreground.

The function FollowAnalytics.WatchFace.enterBackground() triggers the information of entering in background.

Those methods must be added in two different places :

@Override
 public void onAmbientModeChanged(boolean inAmbientMode) {
     super.onAmbientModeChanged(inAmbientMode);

     ...

     if (inAmbientMode) {
         FollowAnalytics.WatchFace.enterBackground();
     } else {
         FollowAnalytics.WatchFace.enterForeground();
     }
     ...
 }

@Override
public void onVisibilityChanged(boolean visible) {
    super.onVisibilityChanged(visible);

    if (visible) {
        ...
        FollowAnalytics.WatchFace.enterForeground();
    } else {
        FollowAnalytics.WatchFace.enterBackground();
        ...
    }
    ...
}

override fun onAmbientModeChanged(inAmbientMode: Boolean) {
    super.onAmbientModeChanged(inAmbientMode)

    ...

    if (inAmbientMode) {
        FollowAnalytics.WatchFace.enterForeground();
    } else {
        FollowAnalytics.WatchFace.enterBackground();
    }
    ...
}

override fun onVisibilityChanged(visible: Boolean) {
    super.onVisibilityChanged(visible)

    if (visible) {
        ...
        FollowAnalytics.WatchFace.enterForeground();
    } else {
        FollowAnalytics.WatchFace.enterBackground();
        ...
    }
    ...
}

Configuration

In order to customize the behavior of FollowAnalytics SDK, it is possible to change the default configuration by creating your own configuration in the project.

It can be achieved by creating an anonymous FollowAnalytics.Configuration, see all parameters here.

public class MyAwesomeApplication extends Application {
  public static boolean isPolicyCalled = false;

  @Override
  public void onCreate(){
    [...]
    FollowAnalytics.init(this.getApplicationContext(), new FollowAnalytics.Configuration() {
            {
              this.apiKey = "API_KEY";
              this.archiveInAppMessages = true;
            }
        });
    [...]
  }
}

class MyAwesomeApplication : Application() {
    var isPolicyCalled = false
    override fun onCreate() {
        [...]
        FollowAnalytics.init(this.applicationContext, object : FollowAnalytics.Configuration() {

            init {
                apiKey = "API_KEY"
                archiveInAppMessages = true
            }
        })
    [...]
    }
}

Or it can be achieved by creating a class that extends FollowAnalytics.Configuration, see all parameters here.

import com.followanalytics.FollowAnalytics;

public class MyConfiguration extends FollowAnalytics.Configuration {
    public static boolean isPolicyCalled = false;

    public MyConfiguration(){
      this.apiKey = "API_KEY";
      this.archiveInAppMessages = true;
    }
}

import com.followanalytics.FollowAnalytics

class MyConfiguration : FollowAnalytics.Configuration() {
    init {
        this.apiKey = "API_KEY"
        this.archiveInAppMessages = true
    }
}

And then, you can initialize FollowAnalytics SDK with instantiating and passing the configuration object. For Instance:

public class MyAwesomeApplication extends Application {
  @Override
  public void onCreate(){
    [...]
    FollowAnalytics.init(this.getApplicationContext(), new MyConfiguration());
    [...]
  }
}

class MyAwesomeApplication : Application() {
    override fun onCreate() {
        [...]
        FollowAnalytics.init(this.applicationContext, MyConfiguration())
        [...]
    }
}

Parameters

A description table with the properties that can be modified with FollowAnalytics.Configuration.

Advanced Use Cases

Proguard

If you need to obfuscate and/or shrink your app before Google Play publication, be sure you protect the FollowAnalytics SDK, otherwise logs won't be sent.

Here is the ProGuard configuration:

-keep class com.followanalytics.** { *; }
-keep class com.followapps.android.** { *; }
-keep interface com.followapps.android.** { *; }

Updating from older versions

Updating from 7.2 to 7.3

From 7.3.0, opening a notification (i.e. tapping on its body) will always open your app to its home screen. This means any work in progress, for instance a form which is not saved/submitted yet, will be lost if ever the user opens a notification. This behavior also applies to notification action buttons, unless you explicitly define a background action button thanks to the new FollowAnalytics.NotificationBuilder.addBackgroundAction() method.

As a result of having the app always open on notification opening and foreground action buttons tap, your implementation of the onNotificationAction() callback is now called after the home screen is opened and calling super.onNotificationAction() will no longer open your app.

Make sure to review the notification interaction logic implemented in your app to handle this behavior and perform modifications in your code if needed. Please refer to the following documentation sections for more details:

• Interactive notifications
• Behavior on notification action

Updating from 6.8 to 7.0

• In your implementation of your FirebaseMessagingService, you must replace your call to FollowAnalytics.setPushToken by FollowAnalytics.setFirebasePushToken.
• If you have set lastKnownLocationEnabled to true in the Configuration and you want it to work on Huawei Mobile Services devices, you have to add a dependency to the HMS Location Kit library into your gradle app module : implementation 'com.huawei.hms:location:5.1.0.300'
• The DefaultMessageHandler class does not exist anymore and its methods has been moved to the FollowAnalytics.Configuration class. Review the Campaigns section to understand how to use the new SDK callbacks.
• All of the the sdk parameters that were previously set in the AndroidManifest.xml file have to be overriden directly in your FollowAnalytics.Configuration subclass (or anonymous class).
• The Message.getDeepLinkUrl() method is renamed Message.getOpeningUrl()
• The Message.getParams() method is renamed Message.getParameters()
• The Message.getUrl() method is renamed Message.getContentUrl()
• The Message.getId() method is renamed Message.getIdentifier()
• The Message.isSilentPush() method is renamed Message.isSilent()
• The com.followapps.android.CustomRichCampaignBaseReceiver class has been removed. That means that the custom rich campaigns can't be handled by your app code anymore. Please note that you can use the silent pushes feature to display your own custom campaigns.

Updating from 6.4 to 6.5

From 6.5.0, by default, the last known location is no longer logged when a session starts. Set the Configuration parameter lastKnownLocationEnabled to true if you want to enable this feature.

Updating from 6.3 to 6.4

Prior to version 6.4.0, for apps that had the fine location permission, the SDK was requesting periodic location updates internally and was sending locations logs to the FollowAnalytics platform. Since version 6.4.0, it's the responsibility of the developer to send location logs to the platform by using the new logLocation() methods, as explained in the Logging Locations section.