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.
In version 4.1.3 these are the major changes:
-Integration with trusted web activity to open web activity in a secure way
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
}
}-
Customer id (
cpId- 32 characters)
This is your Customer ID provided by Kantar Sifo. This information will be included in the attribute calledcpidin the tags sent to the server. -
Application name (
applicationName- max 243 characters)
The name of your application. Choose a name that is representative of the application. If you have both Android and iOS version of app, use the same name. The framework will add platform (e.g. “APP_ANDROID”) to URL parameters, so do not add platform to the name. -
Category (
cat- max 255 characters)
The current category or name of the page the user is browsing. This value tell us what the user is doing. If the user is reading an article about sports in your application, the value should be “sports”. If the user is browsing a set of football scores the value should be “sports/scores/football”. If the user is in the main view of the application, the value should be “main” or similar. If the user is watching streaming/web tv the value chain should start with “stream”. This information will be included in the attribute calledcatin the tag. See also FAQ and contact Kantar Sifo for more info regarding what structure of category values you shall use and what you cannot use. -
Content id (
id- max 255 characters - optional, contact Kantar Sifo before use)
The value current article, resource or content within the category that is being browsed. If the current category does not provide different content, this value is not needed. This information will be included in the attribute calledidin the tag.
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:
- Install “Sifo Internet” app from Google Play Store.
- Login to app and stay logged in while running your app.
To get started with the tagging, you only need 4 methods.
- Use createInstance to create an instance of the framework and specify application name and customer ID.
- Use getInstance to get the instance of the framework that you created at any time in your application.
- For native apps, use sendTag to send a tag to the server when a view is shown in your application.
- For hybrid apps, use activateCookies to make a WebView automatically send tags when visiting webpages that have implemented tagging.
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:
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.
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.
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);
}
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()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.
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.
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.
- Why do I need to initialise the library by passing ComponentActivity and not just Context as
before?
To properly track information regarding Sifo panelist users the library needs to read information from the Sifo Internet app if it is also installed on the device. In the past it was possible to read the needed information directly from the Sifo Internet app, however since the recent security updates on Android this is no longer possible. The new solution is to request the information from the Sifo internet, app given it is installed on the same device. This means on initialisation the app will send an intent request to the Sifo Internet app and wait for the result and this is why just passing the context is no longer enough. - Which Activity is better for initialising the library? For initialising the library, it needs some time to set up itself, the best way to initialize the library is in MainActivity. Example: if you have SplashActivity and MainActivity. Splash activity is alive for 1 or 2 seconds and The best way to initialize the library is in MainActivity.
- How do I test and verify that the framework is correct integrated?
See Test Application and Validation test with Kantar Sifo below. - Native app - how do I integrate the framework?
You have to both initialize the framework and send “page view” events in a correct way. This is a difference to “hybrid app” where page tagging is implemented separate to the framework. - Hybrid app - how do I integrate the framework?
First you have to check if pages shown in web view already are tagged with Codigo scripts (contact Kantar Sifo regarding this). Then you need only to invoke activateCookies() on the framework instance. - How does Framework sync with Sifo Internet app?
If the device has the Sifo Internet app installed and is logged in,the SDK communicates with the Sifo Internet app to get the cookies. - Do I need to grant permissions to the framework to read files?
No, there is no need to explicitly grant permission. - Web TV / streaming - how shall we implement that?
Regarding web TV / streaming, it important to distinguish between measuring “preroll” and “start of clip”. Regarding what parameters to use, “preroll” shall not have the same category value as “Start of clip”. As “start of clip” shall have “streaming” as top category value, preroll can have e.g. “preroll” or “play”. - The initialization of the framework requires an Activity to be passed as an argument, but our app has more entry points which means more Activities. What is your recommendation in such a case? Should I initialize it in every Activity? You should only initialise the framework once and then you can access it anywhere else in your app by calling:
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.
- What about destroyFramework function? At what circumstances it should be called? You do not need to call destroy framework unless for some reason you want to ensure you do not send any further tracking information. It is not recommended to intialise or destroy the framework multiple times in your app lifecycle.
- Our app is using AppCompatActivity, but the initialization of the framework requires a ComponentActivity. How shall we handle this? See the solution in this link: https://stackoverflow.com/questions/54915164/why-are-there-2-different-componentactivity-classes
- What do I need to do to verify my integrate Trusted Web Activity? Contact Kantar
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:
- Inform us as soon as you find something that should be changed or improved
- Inform us as soon as you find a bug, memory or performance issue
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.
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.
Final step, contact Kantar Sifo (see contact info below) to verify that the sent tags have been correctly stored in the analytics databases.
Please send any questions or feedback to:
[email protected] +46 (0)701 842 372
[email protected] +46 (0)8 507 420 00