SDK integration for Android

Resources

About Android SDK

There are three server calls in Android SDK:

• Article Load
  Indicates that the article is loaded on the screen.
• Article Read
  Indicates that the user has spent at least 10 seconds reading the article on their screen. This is considered by the system as a signal that the user started reading the article. This call is very similar to the previous one (apart from a few parameters) and it's fired 10s after the first one.
• Attention time
  This call is triggered the first time when the article is opened and continues to be triggered every 5 seconds while the user is on the article. We start tracking attention time right from the start so we don't miss the first 10 seconds.

Installation

To install smartocto insights SDK into your application please include ContentInsights-X.Y.Z.aar as a dependency using Gradle.
X.Y.Z in the filename stands for SDK major and minor version with optional modifications.

One of the ways of doing this is putting the file into your project's libs folder and telling
Gradle to use it. In build.gradle Android Studio usually creates the following line:

implementation fileTree(include: ['*.jar'], dir: 'libs')

in order to include all .jar dependencies in the libs folder. To include .aar file just edit that line
to look like this:

implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')

Initialization

Before usage, SDK should be initialized in the project's Application class.

Typical initialization looks like this:

ContentInsightsConfig config =  
    new ContentInsightsConfig.Builder(this, "domain_id")
        .build();
ContentInsights.init(config);

IMPORTANT:

For testing purposes, in order to avoid mixing the data from the website and the mobile application, we recommend setting the unique domainID string different from the one that is used on the website (can be found on any article page under the JavaScript object property _ain.id).

Please contact our Support team to get the domainID: support@smartocto.com

After we confirm that requests are sent in the correct format, the domainID should be changed to match the one on the website.

All configuration of SDK behavior is done using ContentInsightsConfig instance.
For example, the following configuration sets SDK not to send real API calls and instead log requests under the ContentInsights tag.

ContentInsightsConfig config =  
    new ContentInsightsConfig.Builder(this, "domain_id")
        .noBackendRequests()
        .doLogWithTag("ContentInsights")
        .build();
ContentInsights.init(config);

Tracking Article Load

Loading an article means that the article page/screen has been opened to be read.
To track this event set desired parameters and request tracking to be done by the SDK.

ArticleReadTracker articleReadTracker = 
    ContentInsights.tracking().startArticleReadTracker(articleUrl, articleId);

Tracking Article Read

Tracking Article Read will be done automatically by the SDK, 10s after startArticleReadTracker has been called.

Tracking Attention Time

For attention time there is AttentionTimeTracker that can be obtained from SDK in a similar way as ArticleReadTracker.

AttentionTimeTracker attentionTracker = 
    ContentInsights.tracking().startAttentionTracker(articleUrl, articleId);

In order to achieve the maximum flexibility with older Android SDK levels, tracking when the app/screen has the user's attention is done manually.

Communication regarding when the app gets or loses the user's attention is done by calling ContentInsights.tracking().startAttention() and ContentInsights.tracking().pauseAttention().

Our suggestion is to use Activity lifecycle methods for these calls, but it's up to the specific implementation to find the most suitable model.

For example:

@Override
public void onStart() {
    super.onStart();
    ContentInsights.tracking().startAttention();
}

@Override
public void onPause() {
    super.onPause();
    ContentInsights.tracking().pauseAttention();
}

Apart from notifying when the article has user attention or not, no further calls are required in order to track the attention time.

Tracking Scrolling Activity

As part of AttentionTimeTracker, there is an option to track how much the user has been scrolled.

In order to have valid statistics, there is a formula for calculating scrolling:

(viewportHeight + scrollTop) * 100 / scrollHeight

New scroll position is marked manually by calling setNewScrollPosition() whenever the scroll event occurs:

ContentInsights.tracking().setNewScrollPosition(newPos) 

Besides the manual call, there are two alternative ways to track scrolls that might be used instead of this one:

1. ScrollView tracking on Android SDK level 23 and above

For articles that are served inside of ScrollView or its subclass, there is a way to track scrolling automatically on Android SDK levels 23 and above.

If that is the case, the only call that should be made is the following:

ContentInsights.tracking().trackScrolling(ScrollView)

and SDK will detect all scrolls and calculate them according to the formula.

2. WebView tracking with accompanying JavaScript

If your articles are served as HTML via WebView, the easiest way to track their scroll positions is by simply calling

ContentInsights.tracking().trackScrolling(articleWebView)

For this to work, WebView must have JavaScript enabled, and inside of article's HTML there should be JavaScript code that tracks scrolls, does the calculation according to the formula, and does exactly this call:

AndroidApi.setNewScrollPosition(scrollPosition)

If you use the same HTML source of an article outside of WebView, the best practice is to use the following code and avoid any errors in JavaScript outside of the WebView environment:

if (typeof AndroidApi !== 'undefined') {
    AndroidApi.setNewScrollPosition(scrollPosition);
}

Flushing the Article

When a user leaves the article, the tracker must flush the article. This is a sign for the tracker to finish the tracking of attention time and to do any final calls to smartocto insight servers.

When everything is finished, the tracker should be destroyed.

To flush the article, please call the following method:

ContentInsights.tracking().flushArticle()

Example application

You may review an example application located in the CiSDKExample folder.
An example app shows the loading Feed of articles from the website and includes all the SDK calls mentioned above.
It also shows all the optional parameters that might be needed for specific application setups.

We strongly advise you to check out the example application (download the bundle project from the link at the top) before implementing SDK in your Android application.

Testing the SDK integration

When you're done with the SDK integration, you will probably want to test if everything works as expected. You can always count on our dedicated support in this process or perform the testing yourselves.

There are two types of requests that can be sent by smartocto insights tracking script.

1. Page-View and Article Read (p-requests)

To search for page load requests, you can filter out "contentinsights.com/p" string in the output log console of your preferred testing tool.

There should be only two p-requests (one pair) for each loaded article, they can be identified by the t-parameter: 

• t=0 indicates a page-view
• t=1 indicates an article read, it loads 10 seconds after the first p-request

If the user leaves an article within the first 10 seconds, only one p-request should be sent (page-view).

2. Attention Time (a-requests)

To search for attention time requests, use "contentinsights.com/a" as a search string. 

One attention time request for a single loaded article should be fired every 5 seconds while reading an article.

It's correct and expected for our ingestion server to send a "204 No Content" response for every generated request.

IMPORTANT:

Please pay attention that not a single request is sent to ingestion.contentinsights.com after the user leaves the article or exits from the application (and the app still runs in the background).