SifoInternetAndroidSDK

![](https://www.kantarsifo.se/sites/all/themes/sifo/images/Kantar_Sifo_Small_Logo_CMYK.png “”)

Developer’s Guide

Kantar Sifo Mobile Analytics SDK for Android

Overview

The Kantar Sifo Mobile Analytics SDK helps you to measure usage of mobile application using Kantar Sifo’s services. In order to measure traffic, your application needs to send HTTPS requests to a server provided by Codigo Analytics using URLs following a specified pattern with information about your application.

Each of these HTTPS requests is called a “tag”. To get a good measure of the usage, your application should send a tag every time a new view or page of content is shown to the user. This tag should contain information about what content the user is seeing. For example when the user opens the application and its main view is shown, a tag should be sent, telling the server that the main view is displayed. When the user shows a list, an article, a video or some other page in your application, another tag should be sent, and so on.

The SDK can help you with the whole process, both creating these URLs, as well as sending them to the server. The only thing it needs from you is for you to tell it when a view has been shown and what content it has. It also needs some information about your application, which is specified later in this document.

What’s new?

In version 4.1.3 these are the major changes:

-Integration with trusted web activity to open web activity in a secure way

Getting started

For gradle

Follow the below steps to import the framework into your project.

Step 1: Add it in your root build.gradle at the end of repositories

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

Step 2: Add to dependency

dependencies {
    implementation 'com.github.kantarsifo:SifoInternetAndroidSDK:4.X.X'
}

If your minSdkVersion is below 24 you might get the following error:

Default interface methods are only supported starting with Android N (--min-api 24): void androidx.lifecycle.DefaultLifecycleObserver.onCreate(androidx.lifecycle.LifecycleOwner)

You can solve this by adding:

android {
 ...
 compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

Basic parameters

Integration with Sifo Internet app

Kantar Sifo collects information about how apps and websites are used in order to create for example statistics and insights for the app/website publisher. The software and service needed is made available once an agreement with Kantar Sifo is in place. The usage information captured can be associated with individuals in the Sifo Internet panel. The Sifo Internet panel consists of several thousand persons from the Sifo panel who have opted in to participate in the panel and install the Sifo Internet app on their mobile devices. For more information about the Sifo panel please go to: https://www.kantarsifo.se/undersokningsdeltagare/sifopanelen

Sifo Internet app integration is available to both WebView based apps and native apps. The purpose of this integration is to identify the user as a certain panelist. This is achieved by receiving a panelist ID string from the Sifo Internet app and setting that ID as a cookie in your app’s shared CookieStore. This communication is handled by with:

Code implementation

Basic functionality

To get started with the tagging, you only need 4 methods.

Implementation steps

Initialize the framework by calling the createInstance method as shown below.

Kotlin

TSMobileAnalytics.createInstance(
    activity,
    TSMobileAnalytics.Builder()
        .setCpId("Customer ID") // required
        .setApplicationName("Application name") // required
        .setPanelistTrackingOnly(boolean) // optional, default value is false
        .setLogPrintsActivated(boolean) // optional, default value is false
        .setIsWebViewBased(boolean) // optional, default value is false
        .build()
)

Java

TSMobileAnalytics.createInstance(
        getActivity(),
        new TSMobileAnalytics.Builder()
        .setCpId("Customer ID") // required
        .setApplicationName("Application name") // required
        .setPanelistTrackingOnly(boolean) // optional, default value is false
        .setLogPrintsActivated(boolean) // optional, default value is false
        .setIsWebViewBased(boolean) // optional, default value is false
        .build()
        );

The framework needs the application context to get a device identifier to separate unique users in the statistics. It can be a good idea to make sure that createInstance does not return null, that means that something was wrong with your input data. If this happens, you will also get an error print in the log.

Now use the following methods to send tags:

Native apps

In the onResume() method of any Activity or any other place where your application displays a view or page that should be tagged:

Kotlin

TSMobileAnalytics.instance?.sendTag(category)
or
TSMobileAnalytics.instance?.sendTag(category, contentID)

Java

if(TSMobileAnalytics.getInstance()!=null){
        TSMobileAnalytics.getInstance().sendTag(category);
        }
        or
        if(TSMobileAnalytics.getInstance()!=null){
        TSMobileAnalytics.getInstance().sendTag(category,contentID);
        }

The framework will now send a tag to the server with the information you provided using a background thread.

If you want to use a category structure with subcategories, such as “News>Sports>Football”, you can use an array of Strings to specify your category structure:

Kotlin

val categoryArray = arrayOf("News", "Sports", "Football")
TSMobileAnalytics.instance?.sendTag(categoryArray, contentID)

Java

String[]categoryArray={"News","Sports","Football"};
        if(TSMobileAnalytics.getInstance()!=null){
        TSMobileAnalytics.getInstance().sendTag(categoryArray,contentID);
        }

… where categoryArray is an array of Strings specifying the category structure. A maximum of 4 categories are allowed in the structure and their names must not be longer than 62 characters each.

If instance is null, it means that createInstance has not been called. It would be a good idea to take some action if this happens. If you turned on debug prints in the framework using ** setLogPrintsActivated(true)** as described above, you can see if tags are being sent and received properly in the Android LogCat.

Options

Besides the category parameter, you may use the additional parameter contentID, which is a String with the identifier of the current content. Maximum length of this parameter is 255 characters. Please contact Kantar Sifo before doing that.

Hybrid apps

In the onCreate() method of any Activity with a WebView that should utilize the tags:

Kotlin

TSMobileAnalytics.instance?.activateCookies()

Java

if(TSMobileAnalytics.getInstance()!=null){
        TSMobileAnalytics.getInstance().activateCookies();
        }

This method will allow third-party cookies.

If you have a react-native project, there is a known bug that doesn’t let the SDK work properly. This is how you can fix it until it is resolved in the main react-native repo:

   //>>>>> ReactAndroid/src/main/java/com/facebook/react/ReactActivity.java

  @Override
  public void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    mDelegate.onActivityResult(requestCode, resultCode, data);
  }

Trusted web activity Integration

You just need to call setTWAInfo function in SDK initialization and set the URL and extra parameters if you have extra parameters as like below code

TSMobileAnalytics.createInstance(
    this,
    TSMobileAnalytics.Builder()
        .setCpId(cpIdET.text.toString())  // required
        .setApplicationName(appNameET.text.toString()) // required
        .setPanelistTrackingOnly(panelistOnly.isChecked) // required value is false
        .setIsWebViewBased(isWebViewBased.isChecked)  // optional, default value is false
        .setLogPrintsActivated(logEnabled.isChecked) // optional, default value is false
        .setTWAInfo(TWAModel(url = "YOUR_URL").apply {
            extraParams.apply {
                put("customCustomerParam", "foo")
            }
        }) // optional 
        .build()
)

How do you launch the trusted web activity

Just call open Twa like below code

  TSMobileAnalytics.instance?.openTwa()

Debugging

There are several more advanced functions in the framework. The purpose of them is to help out if there are any problems or issues with the tagging that needs to be traced. It is possible to get information about pending requests and to subscribe on notifications when a tag request has completed or failed, and more. To see some examples on how to use these functions, have a look at the source code for the test application.

Threads

The framework will take care of the threading for you, so you do not need to think about running the code in a separate thread.

String encoding

Strings sent to the server will be encoded using UTF-8. If the String given to the framework contains characters that are not supported by this encoding, these characters will not be stored correctly in the statistics.

FAQ

TSMobileAnalytics.instance.sendTag()

or

TSMobileAnalytics.instance.activateCookies()

or whatever you need. It is recommended to initialise only once in your root activity or launcher activity and then call the instance in the rest of your app as described above. If you have multiple launcher activities then you can write something like:

if (TSMobileAnalytics.instance == null) {
    TSMobileAnalytics.createInstance...
}

To check if initialisation has taken place and to do so if it has not.

Update strategy

Updates of the framework will be necessary to fix bugs, add features, handle changes on the servers or platform etc. For this reason we want to make updating of the framework as easy and seamless as possible.

To keeping updating as seamless as possible it is important that you:

Example files

Below is a Kotlin code example of how you can use the framework for Android.

Kotlin

import se.kantarsifo.mobileanalytics.framework.TSMobileAnalytics

class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        TSMobileAnalytics.createInstance(
            this,
            TSMobileAnalytics.Builder()
                .setCpId("cpID")
                .setApplicationName("Application name")
                .setPanelistTrackingOnly(true)
                .setLogPrintsActivated(true)
                .build()
        )
    }

    override fun onResume() {
        super.onResume()
        TSMobileAnalytics.instance?.sendTag(
            "Page name",
            "Content ID"
        )
    }

}

Java

import se.kantarsifo.mobileanalytics.framework.TSMobileAnalytics;

public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        TSMobileAnalytics.createInstance(
                this,
                new TSMobileAnalytics.Builder()
                        .setCpId("Customer ID") // required
                        .setApplicationName("Application name") // required
                        .setPanelistTrackingOnly(true) // optional, default value is false
                        .setLogPrintsActivated(true) // optional, default value is false
                        .build()
        );
    }

    @Override
    protected void onResume() {
        super.onResume();
        if (TSMobileAnalytics.getInstance() != null) {
            TSMobileAnalytics.getInstance().sendTag(
                    "Page name",
                    "Content ID"
            );
        }
    }

}

For a more detailed example, please see the code for the test application.

Test application

The Android framework comes with an example application for you to test it with. The application will display a catalog structure with fake native content and real “hybrid content”. When a page or a category is browsed, the application will send a tag to the server with information. The application will print logs in the print log console called LogCat, which is included in the Android SDK, to show what information is sent and when.

If necessary, one could use tools to monitor network traffic, such as Charles Proxy or Fiddler, to verify that the network calls look okay.

Validation test with Kantar Sifo

Final step, contact Kantar Sifo (see contact info below) to verify that the sent tags have been correctly stored in the analytics databases.

Contact information

Please send any questions or feedback to:

SwedishInternetSDK@kantar.com +46 (0)701 842 372

info@kantarsifo.com +46 (0)8 507 420 00