Kantar Media Streaming Sensor iOS
Kantar Media Streaming Measurement Library for iOS
Kantar Media Streaming Sensor iOS Documentation

Kantar Media Streaming Sensor iOS User Manual

SDK 1.12.0 and higher

Starting from SDK version 1.12.0, we are dropping the usage of IDFA addressing the privacy changes that Apple introduced in iOS 14.
The constructor that disables the use of IDFA is now removed

AppStore Submission with iOS 11

Please be aware that if you do not include the AdSupport.framework in your app you will have to disable the use of the IDFA via API in the constructor. Otherwise your App may be rejected from the AppStore for legal reasons.
For more information see the API documentation of the constructor.

Migration to iOS 9

From version 1.4.0, KMA measuerment libraries will not support iOS6 any more. Kantar Media Streaming library components are all with KMA as prefix from this version, please read more in the API documentation.

URL Scheme

Starting on iOS 9, iOS apps will have to declare what URL schemes they would like to be able to check for and open in the configuration files (plist file) of the app as it is submitted to Apple. So if your application is combining with a specific "Panel App" (e.g. Virtualmeter App), please register the URL scheme in your application, the syntax is as following:

<key>LSApplicationQueriesSchemes</key>
    <array>
        <string>NOT_NEEDED_IN_DEMO_VERSION</string>
        <string>NOT_NEEDED_IN_DEMO_VERSION</string>
    </array>
please contact your library provider for the URL scheme

App Transport Security (ATS)

Starting from iOS 9.0, App Transport Security (ATS) enforces best practices in the secure connections between an app and its back end. Migrating from http to https has to be planed for the more secure communication. However for this moment, if you decide to keep http in KMA_Spring library, please add following into the project plist file, otherwise please activate ssl on in the library.
<key>NSAppTransportSecurity</key>
<dict>
        <key>NSAllowsArbitraryLoads</key>
        <false/>
        <key>NSExceptionDomains</key>
        <dict>
            <key>2cnt.net</key>
            <dict>
                <key>NSIncludesSubdomains</key>
                <true/>
                <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
                <true/>
                <key>NSExceptionRequiresForwardSecrecy</key>
                <false/>
            </dict>
        </dict>
    </dict>
if ATS is not enabled in your application, as NSAllowsArbitraryLoads = true, then you don't need to modify anything.

Notification registration for debug purpose

From KMA streaming iOS version 1.4.4, a notification is inserted into the implementation, so that the customers are able to retrieve the requests sent by the library, see more info KMA_STREAMING_DEBUGINTERFACE_NOTIFICATION. The notification contains a NSDictionary object, with the keys, "Request" and "Statuscode". With the following implementation, it is sample to fetch the debug information.

 [[NSNotificationCenter defaultCenter] addObserver:self selector:@ selector(handleApplicationEvent:) name:KMA_STREAMING_DEBUGINTERFACE_NOTIFICATION object:nil];
 − (void) handleApplicationEvent:(NSNotification *)n {
 if(KMA_STREAMING_DEBUGINTERFACE_NOTIFICATION == [n name]) {
         have the implementation
 }
 }
 
Please Note: Set the debug mode (KMA_SpringStreams.debug) to false in your live product, otherwise there will be a debug flag in the measurement request.

BitCode

Bitcode is a new feature on iOS 9, an intermediate representation of a compiled program. Now you have the new KMA_SpringStreams lib with bitcode enabled, for your application you have the chance to enable or disable the bitcode service.

Integration into Swift Project

If the project is a Swift project, a swift bridging header file is required for the integration, more tutorial can be found here: https://kantarmedia.atlassian.net/wiki/spaces/public/pages/159726961/Tutorial+on+how+to+import+KMA+measurement+Objective-C+library+into+Swift+project

Offline Mode

Kantar Media Streaming Sensor iOS has feature so called "offlineMode". This mode can be switched on and off by using public API: KMA_SpringStreams.offlineMode. If the lib is configured to offlineMode, KMA_SpringStreams library will hold all requests in a local buffer and send them when the device goes back online. KMA_SpringStreams lib checks the Internet connection regularly by using the iOS Timer and send the data as soon as possible. Please notice:

  1. Old requests will be dropped if too many requests pump into local buffer for the limitation in buffer size. The default buffer size is 500. The data will be stored in a local file, so the lib will not lose the requests even if the application terminates.
  2. KMA_SpringStreams lib tries to send the requests in a fixed rate, 10 seconds by default, and sends them if device is online.

Chromecast support

In order to measure videos, which are casted to a Chromecast device, the KMA_MediaPlayerAdapter_Chromecast has to be used or extended instead of the default KMA_MediaPlayerAdapter. The KMA_MediaPlayerAdapter_Chromecast automatically detects, if the video is played locally on the iOS device or if it is casted to a connected Chromecast device.
!Important! Current Googlecast-SDK version 4.3.2 has a bug and is not working correctly with iOS 12. In order to use Chromecast on iOS 12 devices, the Googlecast-SDK version 3.4.0 must be used until the bug has been fixed by Google.

UDID

Device ID(did)Advertising ID(ai)MAC ID(mid)

ID_For_Vendor(ifv)

iOS 4
MAC ID(mid)
iOS 5
MAC ID(mid)
iOS 6
Advertising ID(ai)MAC ID(mid)ID_For_Vendor(ifv)
iOS 7
Advertising ID(ai)
ID_For_Vendor(ifv)
iOS 8
Advertising ID(ai)
ID_For_Vendor(ifv)
iOS 9
Advertising ID(ai)
ID_For_Vendor(ifv)

Considering that the Apple private policy is changing all the time, Kantar Media Sensor libs have to adapt different UDIDs for identifying the end user's devices.

  1. Since iOS 6, device ID and mac ID are not available anymore,
  2. Switch to Advertising ID and ID_For_Vendor

Please attention: Apple will reject all the applications which retrieve advertising ID but with no advertising content provided. So Advertising-Framework is linked as optional in Kantar Media Sensor libs, If the Advertising ID should be used as udid, please import Advertising-Framework into your projects.

NextUID

Beginning with the Kantar Media Streaming Library 1.9.0, we are providing a getter-method to retrieve the next UID that will be used when tracking is started in the streaming sensor. Developers can call getNextUID() to retrieve the UID of the stream, which is played next. The track() method will now accept additional parameter handle which is UID retrieved before.

Handling Control Center

The following scenario may occur during measurement: When opening the control center, the measurement will be started with a new uid after closing the control center.
Our recommendation to handle this is as follows. When calling the track method in applicationDidBecomeActive lifecycle hook, please be aware that opening and closing the control center will trigger the action (applicationDidBecomeActive lifecycle method). To avoid this please use applicationWillResignActive lifecycle hook which is invoked when the control center is opened and store a flag to know that the app actually did not go to background but control center is opened. Do necessary changes (like pausing video if desired). On applicationDidBecomeActive please check whether the flag is stored and call the track method only if it is not. This will ensure uninterrupted measurement of streams.

WKWebView

Recently, Apple started warning users that it is going to stop accepting submissions of apps that use UIWebView APIs. Hence, we have removed that.
Starting from kantarmedia Streaming 1.11.0 we are replacing UIWebview with WKWebView for retreiving Useragent. The integrator must add Webkit framework into the application for the app to run properly.

UI Pasteboard

Starting from kantarmedia Streaming 1.11.1 we are replacing URLScheme with UIPasteboard for IDFA Exchange . The integrator must add -ObjC linker flag to build settings for the app to run properly.

Chromecast

Starting from streaming 1.11.1 we are changing the way we measure data in chomecast context. Instead of measuring everything from the sender application we created a new custom reciever which you will receive with kantarmedia-streaming-js artifact. To achieve this you need to include all the files that are included inside src folder in the package except adapter into your project. And On cast session connected(didStartSession) and resume(didResumeSession) events, you need to call sendMessage method of CastSessionManager class

NOTICE

Please Note: Some components in Kantar Media Sensor libs are running in background threads. Please keep the initialization and usage of Kantar Media Sensor libs in your main thread, Kantar Media Sensor libs will not block your UI display.

Release Notes

Version 1.14.0

Changes Attribute Description
BARB Firebase crashes Bug Fix

App Crash reported by the Firebase Crashlitycs tool is fixed.

Privacy manifest files Improvement

Privacy manifest file is added to the SDK package.

iOS 17/iPadOS 17 Platform Review

Support for the iOS 17/iPadOS 17 platforms is added to the SDK package.

Version 1.13.1

Changes Attribute Description
XCFramework Improvement

SDK is distributed now in the form of XCFramework distributable binary package.

Version 1.13.0

Changes Attribute Description
c-parameter Improvement

c-parameter is added to the request as a fallback for missing cookie.

kid Improvement

A new identifier kid is now added to the measurement.

iOS 15/iPadOS 15 Platform Review

Support for iOS 15/iPadOS 15 platforms is added.

Version 1.12.1 (Universal Only)

ChangesAttributeDescription
Universal Improvement

New market FI will now be supported inside SDK as part of multi-market measurement

Version 1.12.0

ChangesAttributeDescription
IDFA Update

SDK will now drop the usage of IDFA

Timers Improvement

Timers are now cleared on unload of SDK

URLScheme Enhancement

SDK will now check for old URLScheme first and then the new one

SSL off-loader Improvement

Removing ssl off-loader. Box will now take care of all ssl requests.(Internal)

Offline Mode Bug fix

Apps built with Xcode 12 will not crash with this release of SDK

iOS14/iPadOS14 Platform review

SDK is now compatible and working with iOS14/iPadOS14

Version 1.11.0

ChangesAttribute

Description

Demo Libraries Improvement

Added new target "Demo" to libraries

WKWebview Improvement

Replaced UIWebview with WKWebview

Version 1.10.2

ChangesAttribute

Description

Scrubbing Improvement

Improved scrubbing algorithm so that it would not add additional playstates in certain scenarios

Version 1.10.0

ChangesAttribute

Description

MultiMarket Support Improvement

Sensor now provides a way to set market/domain via new constructor(limited to Universal artifact, currently supports only UK, NO & DK markets)

Version 1.9.0

ChangesAttribute

Description

ITP 2.0 Analysis

Analysis: Cookie and Local Storage behavior in New Safari.

iOS 12 Analysis

Test sensor on iOS 12.

UID Improvement

Sensor provides a new method, which returns the UID of the next created stream (BARB only).

ChromeCast Improvement

Add ChromeCast support to the iOS sensor.

Payload elements Improvement

Additional variables for the operating system ("os") and the app version ("av") have been added.

Version 1.8.0

ChangesAttribute

Description

32Bit iOS devices Bugfix

Fixes a crash on 32-bit devices, when using a VirtualMeter app.

Scrubbing Improvement

Scrubbing now will not add more playstates to request.

Requests Improvement

New payload information in requestes: OS Version & Application Name.

URL schema trigger Bugfix

VirtualMeter app trigger mechanism has been made more reliable.

32Bit iOS devices Bugfix

Fixes a bug, which causes the VirtualMeter app been triggered to often.

Version 1.7.3

ChangesAttribute

Description

Control over IDFA Access Bugfix

The use of the IDFA can now be disabled in constructor. See API documentation for more information.

Version 1.7.2

ChangesAttribute

Description

UID Bugfix

UID generation now working correctly also on 32-bit devices.

Version 1.7.1

ChangesAttribute

Description

Useragent Improvement

OS Version and Application Name now are added to the user agent string.

Payload object Improvement

OS Version (osv) and Application Name (an) now are added to the payload object of each request.

Version 1.7.0

ChangesAttribute

Description

Cookie Management Improvement

Store cookies in app data in order to prevent deletion of the cookies.

Expose identifiers Improvement

The mobile identifiers can be accessed with the new public method getEncryptedIdentifiers of the class Stream.

Ringbuffer Improvement

Ringbuffer now flushes all requests when the app goes into background.

SSL Improvement

Non-SSL communication has been removed.

Ringbuffer Improvement

Requests from the ringbuffer will now be sent always, not only in offline mode.

Streamname Refaktoring

Variable stream is now mandatory.

UID Improvement

Randomness of UID has been increased and UID is now accessable with an getter.

Version 1.6.0

ChangesAttribute

Description

Ringbuffer Handling Improvement

Requests from the ringbuffer should be sent always, not only in offline mode.

Player position Bugfix

Player position (PST object) not accurate in Offline mode for app streaming.

Version 1.5.0

ChangesAttribute

Description

URL Scheme Trigger Improvement

The VM Trigger frequence has been raised. Within first month after install trigger VM once a week. After the first month after install, trigger VM once a month.

URL Scheme Trigger Improvement

The URL scheme trigger triggers the CamelCase version first, if unsuccessful the lowercase version is called.

Version 1.4.4

ChangesAttribute

Description

AVPlayerViewController Improvement

The deprecated API MPMoviePlayerController now is replaced by AVPlayerViewController, in the sample KMA_MediaPlayerAdapter implementation.

Request Debugger Improvement

A debug Notification is integrated into the library, so that the customers are able to fetch the request sent by the library. See more KMA_STREAMING_DEBUGINTERFACE_NOTIFICATION.

Debug mode Improvement

Debug mode should be set to false if the application is live product. If the debug set to true, the KMA library will automatic add a flag "isDebug=1" in the http request.

URL Scheme Improvement

New beta iOS 10 release has already fixed the url-scheme bug, now capital letters are again valid in url-scheme registration.

URL encoding bug fix

URL encoding component is updated in the library. Symbols will be also url-encoded in measurement requests.

Version 1.4.0

ChangesAttribute

Description

URL Scheme Improvement

In iOS 10, all the url schemes have to be lower-case string, please modify the plist to grant lower-cased url scheme.

API modifications Improvement

All the KMA streaming library components are now with KMA as prefix, please adapt the changes in your implementation, more details can be found in the API documentation enclosed.

API replacement Improvement

Some of the APIs are replaced with the latest iOS APIs, for better compability. From this version, iOS 6 will not be supported any more.

Version 1.3.6

ChangesAttribute

Description

Https transmission Improvement

Change the https prefix for some clients on their demand. QSIClient now is also aligned with ssl options.

Version 1.3.5

ChangesAttribute

Description

Https transmission Improvement

new API setSSL() is added to the library, default https ssl transmission is off, can be switched on. please don't swtich it on until Kantar media Support Team suggest so.

Version 1.3.4

ChangesAttribute

Description

Bitcode Bug

Enabled "-fembed-bitcode" in 'Other C Flags', so that bitcode service can be enabled in applications.

Compiling warnings Improvement

Set "Precompiling Header Prefix" to NO, to avoid precompiling warnings.

Version 1.3.3

ChangesAttribute

Description

Bitcode Improvement

Bitcode is enabled in the KMA_SpringStreams lib, clients have the chance to enable or disable the bitcode service in their applications.

Version 1.3.2

ChangesAttribute

Description

Request Timer Fix

dipatch the NStimer in background thread, avoid the UI block

Background Thread Handler Improvement

Modify the corresponding background thread expiration handlers, prevent from the crash caused by the auto-release of the OS(180sec, or 600sec)

Version 1.3.1

ChangesAttribute

Description

Bundle Name Improvement

The 'an' parameter in the http request is restored to be the CFBundleDisplayname, instead of CFBundleName.

Version 1.3.0

ChangesAttribute

Description

ARC Fix

The Kantar Media Sensor lib is now changing to ARC(automatic reference counting), in order to wipe out/fix the potential/existing bugs.

Delay on Url switch Improvment

Postpone the URL scheme call to UIApplicationDidBecomeActive, only for panelApp users

CFBundleName Fix

Replace the CFBundleDisplayName with CFBundleName in the requests

Version 1.2.4

ChangesAttribute

Description

Debug Mode Modification

Starting from the version 1.2.4, the debug mode of Kantar Media Streaming Sensor lib is set back to false. When debug mode is switch to YES, advertising ID and ID_for_vendor will be displayed in plain text in console, as the reference for the further test.

Version 1.2.3

ChangesAttribute

Description

Panel App Improvement

Starting from the version 1.2.3, Kantar Media Streaming Sensor lib is able to pair with previous customized panelApp, as well as 'Nip App'. The related component is optimized.

Advertising ID Modification

As Apple requested, add the check of user's 'Limit Ad tracking' option before reading the advertising ID.

Version 1.2.2

ChangesAttribute

Description

Data encoding Fix

Fix a parameter encoding problem

Panel App Improvement

Speed up the switch to panel App, this improvement applies to the related clients

Panel App Modification

Preconditions which leads to the panel App switch has been modified. With this modification, the main App with Kantar Media Sensor lib imported can also trigger the panel App even though the panel App has been installed after the main App. New Kantar Media Sensor lib attempts on switching to the panel App every time when the main App goes foreground. This modification applies to the related clients

Version 1.2.0

ChangesAttribute

Description

Compatibility of Kantar Media Streaming Sensor libs Special feature

Strating with KMA_SpringStreams 1.2.0, Spirng normal and streaming sensor can be imported and measure in one application

App name retrieving Fix

Spirng libs will be tolerant even if the app name is not registered correctly in application

User-agent String New Feature

Starting with KMA_SpringStreams 1.1.1, the default user-agent string of the device is inserted into http client parameters to be collected by the backend box. The user-agent string will be used for device type recognition.

Availablity of retrieving IFV Fix

Fixed the crash caused by unavailable call of retrieving IFV (idforVendor). This bug crashes the app in iOS versions below 6.0.0.

Reorganization of imports Improvement

Reorganized the header files, includes, imports, in order to avoid potential duplicate-symbols-error in case the -all_load flag is set in the main application.

Force to apply aid Special feature

This update is only applied to some of our clients based on their requirements. Kantar Media Sensor lib will produce a compile error to force the usage of advertising id (with the adSupportFramework imported into application)

Version 1.1.0

ChangesAttributeDescription
PanelApp Switch: Url Scheme New Feature

Since KMA_SpringStreams 1.1.0, the lib will try to call a corresponding PanelApp (by URL Scheme, happens in the initialization phase, only called once if ifv is not changed since last lauch), and send ifv (identifier_for_vendor) and related parameters to the PanelApp. This mechanism is designed for identifying each single device owned by the end user. (ifv is unique for each vendor, but not globally)

For adapting this mechanism, the clients of KMA_SpringStreams lib has to implement their own PanelApp and also import KMA_Spring/KMA_SpringStreams lib into it.

arm64 bits support New Feature

Since KMA_SpringStreams 1.1.0, the lib will support arm64 bit architecture, KMA_SpringStreams lib will be applicable for latest iOS devices.

Customized special fields Changes

More customized parameteres/special fields are inserted into measuring http request, applied to our lib accordingly based on the different domains.

Version 1.0.1

ChangesAttributeDescription
Identifier of DeviceNew FeatureThe identifier of the device would be advertisement id + identifier_for_vendor(https://developer.apple.com/library/ios/documentation/uikit/reference/UIDevice_Class/Reference/UIDevice.html#//apple_ref/occ/instp/UIDevice/identifierForVendor) if your application contains video advertisement, otherwise the identifier of the device would be only identifier for vendor. This change responses to the modification of Apple Developers' Policy, advertisement ids are not accepted if no video adversements are involved in the application.

Version 1.0.0

ChangesAttributeDescription
OfflineModeNew FeatureIf the app is configured to offlineMode, Kantar Media Streaming Sensor library would hold all requests in a local buffer and send them until the device goes back online. Kantar Media Streaming Sensor lib checks the internet connection regularly by using a Timer and send the data as soon as possible. Please notice:
  1. Old requests would be droped if too many requests pump into local buffer for the limitation in buffer size. The default buffer size is 500. The data will be stored in a local file, so we would not lose the requests even if the applicaiton terminated.
  2. Kantar Media Streaming Sensor lib tries to send the requests in a fixed rate, 10 seconds by default, and sends them if device is online. This is achieved by using Apple NSTimer.

    This mode can be switched on and off by using public API.
    See also
    KMA_SpringStreams.offlineMode
memory leakFixIf the method Stream.stop is called in some cases a memory leak will occur
Problem maxstatesFixProblem fixed if maxstates is reached
KMA_StreamAdapter and Meta ObjectChangeKMA_StreamAdapter is now a protocol and Meta is now a class implementation
Method KMA_Stream.setDurationRemoveThe duration has to be delivered by the method getDuration (KMA_StreamAdapter-p)