SDK integration for iOS

Resources

You are free to download iOS SDK files.

Latest stable version: 2.2.5

Required:

iOS binary framework (zip)

Optional:

iOS demo application (zip) - also contains a binary framework file.

About iOS SDK

There are three server calls in iOS SDK:

Article load
Indicates that the article is loaded on the screen.
Article read
Indicates that the user spent at least 10s with the article on the 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 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, include ContentInsights-X.Y.Z.xcframework in your Xcode project.
X.Y.Z in the filename stands for SDK major and minor version with optional modifications.

Initialization

SDK should be properly initialized in the project's AppDelegate class.

Typical initialization looks like this:

var contentInsights: ContentInsights!
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Initialization
    self.contentInsights = ContentInsights.shared(domainID: "1234")
}

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 publisher's website.

Tracking

In your view controller class, create property to store AppDelegate instance:

private let delegate = UIApplication.shared.delegate as! AppDelegate

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.

In viewDidAppear, initiate tracking of the loaded article.

delegate.contentInsights.startArticleReadTracker(
    articleURL: "https://test.com/test",
    postID: "post-123",
    referUrl: "test.com"
)

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 startAttentionTracker that can be obtained from SDK in a similar way as startArticleReadTracker:

delegate.contentInsights.startAttentionTracker(
    articleURL: "https://test.com/test",
    postID: "post-123",
    referUrl: "test.com"
)

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

The tracker shouldn't be active when the app is not in the foreground. This must be handled manually.

When an article is opened, but the app loses focus, e.g. it gets minimized or a user switches to another app, you should call delegate.contentInsights.pauseAttention().

When the app comes back into focus, you should call delegate.contentInsights.startAttention().

Please make sure that ArticleReadTracker and AttentionTracker have already been started beforehand, when the article was opened.

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

IMPORTANT:

It's crucial to call the methods in the correct order:

startArticleReadTracker()
startAttentionTracker()

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() method whenever the scroll event occurs:

delegate.contentInsights.setNewScrollPosition(newPos)

Besides the manual call, there is an alternative way to track scrolls that might be used instead of this one:

View scroll tracking on iOS SDK

For articles that are served inside of some native iOS view, there is a way to track scrolling automatically.

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

delegate.contentInsights.trackScrolling(ScrollView)

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

Supported view classes:

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:

delegate.contentInsights.flushArticle()

Example application

We strongly advise you to check out the example application before implementing SDK in your 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).