View source for Implementing Viewability with AppSDK

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}}  {{CurrentBreadcrumb}}
[[Category:Digital]]

== The Viewability Metric integration ==
This feature is currently in development for the APP SDK
<!--
=== Initializing the Nielsen AppSDK to measure the Viewability ===
The integrator to support the viewability metrics in the application has to provide a tag value of the player view to let Nielsen AppSDK know that there is a player that needs to be tracked. It’s called the ‘containerId’ and it should be passed in application info dictionary as string while initializing the Nielsen AppSDK.

==== Android ====
{| class="wikitable"
|-
! #	!! Parameter Name	!! Description !! Supported Values !! Example
|-
| 1	|| containerId ||View ID of the UI element used as player view in application. getId() method of View class can be used to get this value.	||A positive integer used to identify the view. || 2131558561
|}


==== iOS ====
{| class="wikitable"
|-
! #	!! Parameter Name	!! Description !! Supported Values !! Example
|-
| 1	|| containerId ||The tag of the UIView that represents the Player View	||The string value representing the NSInteger value with maximum value of NSIntegerMax that is related on 32- or 64-bit applications. || "100" <br> "2131558561"
|}

For iOS it is required to link additional frameworks that are needed for viewability engine:<br>
<code>JavaScriptCore.framework</code> <br>
<code>WebKit.framework</code>

The Nielsen AppSDK uses a tracking WebView (TWV) approach. The main idea is that the TWV getting injected under the player view that is found by the Nielsen AppSDK and the TWV is in a JS execution environment, where all the calculation related to views is happening. The Nielsen AppSDK injects the TWV once the playing is started. After injecting, the Nielsen AppSDK keeps tracking main properties of the player view that could be used for measuring the viewability value: the frame, alpha value, the view is hidden or not, does it have superview or not.
'''The use of TWV is required due to the IAB Open Measurement SDK’s approach to expose the JS execution environment.''' 

=== Sample SDK Initialization Code ===
{{ExampleCode|
|Swift  = 
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
    class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
    let appInformation:[String: String] = [
           "appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
            "appversion": "1.0",
            "appname": "app name here",
            "sfcode": "dcr",
            "containerId":"647863",
            "nol_devDebug": "DEBUG"
        ]
        return NielsenAppApi(appInfo:appInformation, delegate:delegate)
    }
}
</syntaxhighlight>


Sample code using AVPlayer.
<br />
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate  {
    
    let avPlayerViewController = AVPlayerViewController()
    var avPlayer:AVPlayer?
    var nielsenAppApi: NielsenAppApi!

  override func viewDidLoad() {
        super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

            }
  }
</syntaxhighlight>
|Objective C = 
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>
<syntaxhighlight lang="objective-c">    
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
    NSDictionary *appInformation = @{
                                     @"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
                                     @"appversion": "1.0",
                                     @"appname": "app name here",
                                     @"sfcode": "dcr",
                                     @"containerId": "647863",
                                     @"nol_devDebug": @"DEBUG"
                                     };
    return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>


The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject 

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>
|Android = 

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">  

try
{
  // Prepare AppSdk configuration object (JSONObject)
  JSONObject appSdkConfig = new JSONObject()
          .put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
          .put("appversion", "1.0")
          .put("appname", "Sample App Name")
          .put("sfcode", "dcr"),
          .put("containerId", "647863"),
          .put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
  Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.


The integration of Nielsen App SDK will depend on type of client app.<br />
* Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on property page of the App’s project).
}}

=== Getting the Viewability Metric data ===
All the Viewability Metric data is presented in D-pings of DCR and DTVR processors.
The D-ping has follow parameters:
* invs - video series
* inau - audability series
* inss - device screen size
* ines - player size series
* invp – application size series

{| class="wikitable"
|-
! #	!! Parameter Name	!! Description !! Supported Values !! Example
|-
| 1	|| invs ||Video series in percentage in view values	||Array of arrays object || { <br> [100, 0, 1512300013, 10],<br>   [50, 10, 1512300023, 5] <br> ]
|-
| 2	|| inau ||Audability series in percentage values || Array of arrays object ||{ <br> [0, 0, 1512300013, 10],<br>   [100, 10, 1512300023, 5] <br> ]
|-
| 3	|| inss ||Device Screen Size || The string in format <width>x<height> || 320x568 ]
|-
| 4	|| ines ||Player size series	||Array of arrays object || { <br>   [“320x205”, 0, 1512300013, 10],<br>    [“150x100”, 10, 1512300023, 5] <br> ]
|-
| 5	|| invp ||Viewport series (application size)	||Array of arrays object || { <br>    [“768x1024”, 0, 1512300013, 10],<br>     [“418x768”, 10, 1512300023, 5] <br> ]
|}

An example of the D-ping with viewability metric data is presented below:

<syntaxhighlight = "c">
http://secure-cert.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=APRP3&ch=APRP3_NA_P&asn=defChnAsset&sessionId=
&tl=MyEpisode&prv=1&c6=vc,NA&ca=APRP3_NA_BIG_BUNNY&cg=MyProgram
&c13=asid,TF2D48D99-9B58-B05C-E040-070AAB3176DB&c32=segA,NA&c33=segB,NA&c34=segC,NA&
c15=apn,MTVR-EXO-QA&sup=1&segment2=539&segment1=usa&forward=0&ad=1&
cr=4_00_99_D1_11111&c9=devid,2fd530f10598cd9f4b4ad8fc35f8c1cec1b78a4dae19d648bf74830a768c0902&enc=true
&c1=nuid,14f000ed61b00da1a2d443faeaf1a51870657677520fd1c1490a70f63781ddf5&at=timer&rt=video
&c16=sdkv,aa.5.1.1&c27=cln,300&crs=0&lat=&lon=&c29=plid,TF2D48D99-9B58-B05C-E040-070AAB3176DB
&c30=bldv,aa.5.1.1.28&st=dcragf&c7=osgrp,DROID&c8=devgrp,TAB&c10=plt,MBL&c40=adbid,
&c14=osver,Android7.1.1&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,
&c11=agg,1&c12=apv,exo.5.1.1.28&c51=adl,0&c52=noad,0&sd=6000&devtypid=htc-Nexus-9
&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=BIG_BUNNY&c3=st,c
&c64=starttm,1506681882&adid=BIG_BUNNY&c58=isLive,false
&c59=sesid,fOeLAlHmGtKBD2OWAtrvM2W1UzrnM1506681885&c61=createtm,1506682185&c63=pipMode,
&c62=sendTime,1506682242&c68=bndlid,com.nielsen.sampleexomtvrqa&nodeTM=&logTM=&c73=phtype,Tablet
&c74=dvcnm,Google+Nexus+9&c76=adbsnid,&df=-1&c77=adsuprt,1&evdata=PL%3A1506681882762%3A0
&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,http%3A%2F%2Fwww.nielseninterNielsen AppSDK.com%2FBBB%2Fprog_index.m3u8&uoo=&vtoff=57&
invs=[0,1,1507579800,14],[50,15,1507579815,75],[25,90,1507579890,15],[50,105,1507579905,25],
[100,130,1507579930,150],[0,280,1507579980,25]]&inau=[[100,1,1507579800,60],[0,61,1507579860,15]
,[100,76,1507579875,200]]&invp=[["800x600",1,1507579800,200]]&inss=1920x1360&ines=
[["480x360",1,1507579800,200]]&rnd=1506682245191
</syntaxhighlight>

== Understanding the Viewability Metrics ==
The viewability metric introduced in Nielsen AppSDK is representing the visibility of a video in the player along a playback. The viewability metric as a whole will be broken into 5 measurements. Four of them are related to visibility values – screen size, application size (viewport), element size (player) and percentage of visibility on the screen. The last one is related to volume of the video – the mutability/volume value, so called Audability.
 
Almost all viewability data is presented in series type fashion except of one – the screen size.
These values are tracked second by second, and each change of the concrete value is presented by the new segment inside of the array:

<syntaxhighlight lang="ruby">
[<element>, …, <element>], where <element>
is
[<value>, <play head of the video in seconds>, <time interval since 1970>, <duration>]

</syntaxhighlight>


For better understanding of the approach let’s see an example: if the user in the application drags the player from 100% of the visibility beyond the bounds of the screen after 10 seconds of watching it to 50% for 5 seconds and the user changes the volume from 0 to 100 while dragging the player, the next viewability data will be created:
* video series: '''[[100, 0, <timestamp>, 10], [50, 10, <timestamp + 10>, 5]]'''
* audio series: '''[[0, 0, <timestamp>, 10], [100, 10, <timestamp + 10>, 5]]'''
* viewport series: '''[[“320x568”, 0, <timestamp>, 15]]'''
* player size series: '''[[“320x205”, 0, <timestamp>, 15]]'''
* screen size: '''320x568'''

For most of the cases the viewport value will match the screen size value, but there could be cases when viewport value and screen size will not be same, as example, the split screens functionality for iPad, when the application could be presented on a half of a screen when it supported. In that case the viewport value will be 2 times lesser than screen size value.


== The Viewability Approach Limitations ==
==== Android ====
The dynamic injection logic works fine in most of the cases. However, there may be some scenarios, where this logic could break the client UI. Few of these scenarios are listed below:
 
'''1'''. If the client app uses a LinearLayout with android:layout_weight / android:weightSum properties used for the player view. (Possible side effect : The complete UI layout balance is disturbed and the views don't get repositioned as desired)

'''2'''. If the client app uses a RelativeLayout with and it's child views (including the player view) use the relative positioning properties like android:layout_below, android:layout_above, android:layout_toLeftOf etc. to position themselves in the view tree. (Possible side effect : The complete UI layout balance is disturbed and the views don't get repositioned as desired)

'''3.''' If the client app uses the property <code>xmlns:android="http://schemas.android.com/apk/res/android"</code> for any of it's intermediate ViewGroup. (Possible side effect : The target player view's parent is fetched as a wrong ViewGroup)

'''4.''' There is also a common problem, where the total child view count of the View Tree is increased as we inject the Transparent WebView and FrameLayout (wherever needed) and also the index of the views changes. If any client app has a tightly coupled logic w.r.t. these counts/indexes, it could break UI logic. Though it's less likely that the client apps would rely on these initial static counts/indexes, but still we can't say with surety that they would not rely on these values.


==== iOS ====
'''1'''. As “Player in player” functionality uses different from UIView approach (CALayer is used), the OMID library doesn't handle picture moving with layers and it doesn't recognize frame change, so it means that even if the player is on the top of the screen, it (PiP) doesn't use the view that was tagged by the user. The view stays on his previous position, so if some view will cover tagged view, and PiP view will move from it, the OMID will take obstruction into account and the viewability value will be calculated with new intersection for tagged view, not for PiP controller.

'''2.''' The next limitation is related to showing the keyboard. When the keyboard has appeared, viewability value becomes 0 because of the way of implementing the keyboard. In iOS, a keyboard getting shown using a new UIWindow object. It appears on top of the screen with the size of the screen and "hides" all views under it. Even the UIWindow object's background is transparent, OMID doesn't take it into account because of alpha value set to bigger than 0.

'''3.''' When the UIAlertController is shown, even if it has transparent background, the viewability becomes 0 because of the implementation of the controller - it covers the full screen.

'''4.''' The Reachability mode is not supported for tracking the geometry change in Application. That means that if the user double taps on Home button and the player will go beyond the screen bounds, the percentage in view value will get changed.

'''5.''' The Slide Over (the new iOS 11 functionality) is not supported.

'''6.''' The Apple TV is not supported.
-->