DCR Static Android SDK - Revision history

NickParrucci: /* DCR Static Duration Measurement per Section/Page/Asset */

2023-03-30T21:06:25Z

DCR Static Duration Measurement per Section/Page/Asset

← Older revision		Revision as of 21:06, 30 March 2023
Line 131:		Line 131:
	<span class="mw-customtoggle-myDivisionDiag" style="color: cornflowerblue"> Show flow diagram for above description </span>		<span class="mw-customtoggle-myDivisionDiag" style="color: cornflowerblue"> Show flow diagram for above description </span>
	<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionDiag">		<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivisionDiag">
	[[File:~~dcrstaticflow~~.png\|500px]]		[[File:DCRstaticflow.png\|500px]]
	</div>		</div>
	<br>		<br>
Line 195:		Line 195:

	'''Note:''' Even though the assetid has changed, a new view event would not be recognized unless staticEnd() is called in between loadMetadata calls, because the section name did not change.		'''Note:''' Even though the assetid has changed, a new view event would not be recognized unless staticEnd() is called in between loadMetadata calls, because the section name did not change.


	== Handling Foreground and Background states ==		== Handling Foreground and Background states ==

NickParrucci at 21:04, 30 March 2023

2023-03-30T21:04:48Z

@@ Line 126: / Line 126: @@
 | segC || Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
 |}
 == Handling Foreground and Background states ==

ColinBrown: /* SDK Initialization */

2022-03-18T05:59:43Z

SDK Initialization

@@ Line 23: / Line 23: @@
 || Nielsen-specified || Optional || "DEBUG"
 |}
 === Configure API calls - play ===

ColinBrown: /* Initialize SDK */

2022-03-18T05:58:15Z

Initialize SDK

← Older revision		Revision as of 05:58, 18 March 2022
Line 10:		Line 10:
	{{Android_Implementation}}		{{Android_Implementation}}

	==~~= Initialize~~ SDK ===		== SDK Initialization ==
	~~Initialize~~ App SDK ~~as soon as~~ the ~~application is launched~~. ~~Refer~~ to ~~[[iOS SDK API Reference#Initialization~~\|~~Initalization]]~~ for ~~details on initializing an AppSDK object~~ and ~~the parameters~~ required.		The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1. (Version 4.0 for Android)

			The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
			{\| class="wikitable"
			\|-
			! Parameter / Argument !! Description !! Source !! Required? !! Example
			\|-
			\| appid \|\| Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. \|\| Nielsen-specified \|\| Yes \|\| PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
			\|-
			\| nol_devDebug \|\| Enables Nielsen console logging. Only required for testing
			\|\| Nielsen-specified \|\| Optional \|\| "DEBUG"
			\|}

	=== Configure API calls - play ===		=== Configure API calls - play ===

ColinBrown at 05:57, 18 March 2022

2022-03-18T05:57:35Z

← Older revision		Revision as of 05:57, 18 March 2022
Line 1:		Line 1:
	{{Breadcrumb\|}} {{Breadcrumb\|Digital}} {{Breadcrumb\|US DCR & DTVR}} {{CurrentBreadcrumb}}		{{Breadcrumb\|}} {{Breadcrumb\|Digital}} {{Breadcrumb\|US DCR & DTVR}} {{CurrentBreadcrumb}}
	[[Category:Digital]]		[[Category:Digital]]

			== Overview ==
			This guide covers DCR Static Only Implementation information for the Nielsen SDK. If implementation measurement for Video, please refer to our [[DCR_Video_Android_SDK\|Video Guide]].

	{{Android_Prerequisites}}		{{Android_Prerequisites}}

			__TOC__
	{{Android_Implementation}}		{{Android_Implementation}}

ColinBrown at 05:55, 18 March 2022

2022-03-18T05:55:20Z

@@ Line 2: / Line 2: @@
 [[Category:Digital]]
-=== Prerequisites ===
+{{Android_Prerequisites}}
-=== Import Library ===
+{{Android_Implementation}}
 === Initialize SDK ===

LaMarHolmes at 18:12, 20 October 2021

2021-10-20T18:12:06Z

← Older revision		Revision as of 18:12, 20 October 2021
Line 56:		Line 56:

	[[File:Sdk_dataflow.jpg]]		[[File:Sdk_dataflow.jpg]]

			=== Configure Metadata ===
			Map the Nielsen keys to variables so that the content metadata is dynamically updated.

			The Nielsen reserved keys are:
			{\| class="wikitable"
			\|-
			! Key !! Description !! Data Type !! Value !! Required?
			\|-
			\| type \|\| asset type \|\| fixed \|\| <code>'static'</code> \|\| Yes
			\|-
			\| assetid \|\| Unique ID for each article \|\| dynamic \|\| custom <br>(no [[Special Characters]]) \|\| No
			\|-
			\| section \|\| section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values \|\| dynamic \|\| custom \|\| Yes
			\|-
			\| segA \|\| custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) \|\| dynamic \|\| custom \|\| No
			\|-
			\| segB \|\| custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) \|\| dynamic \|\| custom \|\| No
			\|-
			\| segC \|\| custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) \|\| dynamic \|\| custom \|\| No
			\|}

			The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.

			'''Aggregation Limits'''
			There are limits on the number of unique values that can be aggregated on in reporting. The specific limitations by key are:
			{\| class="wikitable"
			\|-
			! Key !! Aggregation Limit
			\|-
			\| section \|\| maximum of 25 unique values (section <= 25)
			\|-
			\| segA \|\| Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
			\|-
			\| segB \|\| Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
			\|-
			\| segC \|\| Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
			\|}

	== Handling Foreground and Background states ==		== Handling Foreground and Background states ==

ColinBrown at 19:44, 5 October 2020

2020-10-05T19:44:45Z

← Older revision		Revision as of 19:44, 5 October 2020
Line 125:		Line 125:
	Correct measurement of the foreground/background state is crucial to Static App measurement within Nielsen Digital Content Ratings (DCR).		Correct measurement of the foreground/background state is crucial to Static App measurement within Nielsen Digital Content Ratings (DCR).

	~~== Nielsen Measurement Opt~~-Out ~~Implementation ==~~		{{Template:Android_Privacy_and_Opt-Out}}
	As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.
	* When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content string obtained from [[optOutURL]]) should be displayed.
	* Use [[optOutStatus]] to retrieve the device’s Opt-Out status.
	* This Opt-out page should be displayed in a webview (within the app) and not in any external browser.
	* Capture the user’s selection in this page and pass it to the SDK through [[userOptOut]] for Nielsen to save the user’s preference.
	* For more details, refer to [[Android SDK API Reference#Android Opt-Out Implementation\|Android SDK API Reference - Android Opt-Out Implementation]] and Nielsen Digital Privacy.

	== Pre-Certification Checklists ==		== Pre-Certification Checklists ==

ColinBrown at 01:00, 10 September 2020

2020-09-10T01:00:48Z

← Older revision		Revision as of 01:00, 10 September 2020
Line 1:		Line 1:
	{{Breadcrumb\|}} {{Breadcrumb\|Digital}} {{Breadcrumb\|DCR & DTVR}} {{CurrentBreadcrumb}}		{{Breadcrumb\|}} {{Breadcrumb\|Digital}} {{Breadcrumb\|US DCR & DTVR}} {{CurrentBreadcrumb}}
	[[Category:Digital]]		[[Category:Digital]]

ColinBrown: /* Handling Foreground and Background states of App */

2020-06-15T20:56:51Z

Handling Foreground and Background states of App

← Older revision		Revision as of 20:56, 15 June 2020
Line 57:		Line 57:
	[[File:Sdk_dataflow.jpg]]		[[File:Sdk_dataflow.jpg]]

	== Handling Foreground and Background states ~~of App~~ ==		== Handling Foreground and Background states ==
	Foreground/Background ~~state measurement is a requirement~~ of ~~Nielsen AppSDK implementation which is especially crucial~~ for ~~static~~ measurement. ~~It may be implemented in multiple ways for Android:~~		There are a few approaches to managing the Foreground and Background states of an app available to use for state measurement.
	~~<br>'''~~1)~~'''~~ [[~~DCR_Static_Android_SDK~~#~~1) ForeGround/Background Measurement via AndroidManifest~~\|~~ForeGround/Background Measurement via AndroidManifest~~]] ~~- Enable the Nielsen SDK to measure background/foreground state by makingthe relevant update~~ to the ~~AndroidManifest.~~		* Utilizing the Androidx LifeCycleObserver (The recommended approach starting sdk version 7.1.0.0+)
	~~<br>'''2)''' [[DCR_Static_Android_SDK#2) Using~~ the ~~Android SdkBgFbDetectionUtility Class\|Using~~ the Android ~~SdkBgFbDetectionUtility Class]] - Integrate Nielsen’s SdkBgFgDetectionUtility class within your Custom Application Class~~.		* Utilizing the [[DCR_Video_Android_SDK#The_SdkBgFgDetectionUtility_class\|SdkBgFgDetectionUtility]] class
	~~<br>~~'''3)''' ~~[[DCR_Static_Android_SDK#3) Manual Background/ForeGround State Management\|Manual Background/ForeGround State Management]] - Custom implementation of~~ the ~~required methods within your application~~.		* Adding a tag to the Manifest XML
			* Manual Management
			=== The LifeCycleObserver ===
			AndroidX replaces the original support library APIs with packages in the androidx namespace, and Android Studio 3.2 and higher provides an automated migration tool. (Select '''Refactor> Migrate to AndroidX''' from the menu bar.)

	=== 1) ForeGround/Background Measurement via AndroidManifest ===		Starting with version 7.1.0, with AndroidX support, an additional utility is provided in the AppSDK - application background/foreground state detection by the AppSdk leveraging the Android Architecture component "LifeCycleObserver".

			The AppSdk is now capable of detecting the application UI visibility state transitions between background and foreground, without forcing the applications to register for AppSdk's AppSdkApplication class, which is responsible for handling the detection of application background/foreground state transitions at present.

			<blockquote>Please note, that if you already have an app designed that utilizes the depreciated SdkBgFgDetectionUtility Class, the AppSDK will ignore any calls to these methods if it can utilize the LifeCycleObserver. LifeCycleObserver based auto detection will take precedence. </blockquote>
			==== Adding the AndroidX dependency ====
			In order to make use of the app background/foreground state transition auto detection feature of AndroidX AppSdk, the app gradle file needs the androidx dependency. The AppSdk API calls - <code>appInForeground()</code> and <code>appInBackground()</code> will still be respected by AppSdk by executing the old AppSdk flow of handling "app in foreground" and "app in background" states as is.

			==== Using the LifeCycle Extension ====
			The following androidx dependency is required in the app gradle file:
			<syntaxhighlight lang="java">
			implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"
			</syntaxhighlight>

			<blockquote>
			If you would like to take advantage of this auto detection feature of AppSdk at the very initial stage (e.g. splash screen or at of app launch time), before the AppSdk is initialized, can do so by calling the following newly introduced AppSdk public api, passing the application context :
			<syntaxhighlight lang="java">
			public static void registerLifeCycleObserver(Context applicationContext)
			</syntaxhighlight>
			</blockquote>

			==== Log messages for the new auto detection ====

			When the AppSdk app successfully registers for the LifeCycleObserver : <code>Registered LifeCycleObserver for App Background/Foreground auto-detection</code>

			* When the app enters the foreground state :<code>App is in foreground, auto detected by AppSDK</code>
			* When the app enters the background state :<code>App is in background, auto detected by AppSDK</code>
			* If the client app doesn't have the "androidx" gradle dependency and AppSdk fails to register LifeCycleObserver :<code>AndroidX LifecycleObserver can not be observed. Please use androidx dependency to activate SDK auto-detection of app background/foreground state.</code>
			* When the appInForeground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - foreground</code>
			* When the appInBackground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - background</code>

			=== The SdkBgFgDetectionUtility class ===
			Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement. It may be implemented in multiple ways for Android. This includes
			* Enable the Nielsen SDK to measure background/foreground state by makingthe relevant update to the AndroidManifest.
			* Integrate Nielsen’s SdkBgFgDetectionUtility class within your Custom Application Class.
			* Custom implementation of the required methods within your application.

			==== ForeGround/Background Measurement via AndroidManifest ====
	The simplest way to measure the app background/foreground state is to add the following application tag to the Manifest XML. Integrating this into the Manifest XML will enable the SDK to measure app state directly. This approach is supported for Android 4.0 and up only; it requires that the application class is not in use for some other purpose.		The simplest way to measure the app background/foreground state is to add the following application tag to the Manifest XML. Integrating this into the Manifest XML will enable the SDK to measure app state directly. This approach is supported for Android 4.0 and up only; it requires that the application class is not in use for some other purpose.
	<syntaxhighlight lang="java">		<syntaxhighlight lang="java">
	<application android:name=~~”com~~.nielsen.app.sdk.~~AppSdkApplication”~~>		<application android:name="com.nielsen.app.sdk.AppSdkApplication">
	</syntaxhighlight>		</syntaxhighlight>

	=== 2) Using the Android SdkBgFbDetectionUtility Class ===		==== Using the Android SdkBgFbDetectionUtility Class ====
	For developers who are already using the application class, it is recommended that background/foreground state is implemented using the [[Android_Background_Foreground\|SdkBgFgDetectionUtility class]]. The [[Android_Background_Foreground\|SdkBgFgDetectionUtility class]] is compatible with Android 4+ and has been made available to Nielsen clients.		For developers who are already using the application class, it is recommended that background/foreground state is implemented using the [https://engineeringportal.nielsen.com/docs/Android_Background_Foreground SdkBgFgDetectionUtility class]. The [https://engineeringportal.nielsen.com/docs/Android_Background_Foreground SdkBgFgDetectionUtility class] is compatible with Android 4+ and has been made available to Nielsen clients. (You will need to copy/paste the code provided into a file).

	=== 3) Manual Background/ForeGround State Management ===		==== Manual Background/ForeGround State Management ====
	In cases where the developer is not able to use the AndroidManifest.xml solution nor the Nielsen provided [[Android_Background_Foreground\|SdkBgFgDetectionUtility class]] the developer will need to manually identify the change of state through the application and call the respective API (appInForeground() or appInBackground()) to inform the SDK regarding the change of state from background to foreground or foreground to background.		In cases where the developer is not able to use the AndroidManifest.xml solution nor the Nielsen provided [https://engineeringportal.nielsen.com/docs/Android_Background_Foreground SdkBgFgDetectionUtility class] the developer will need to manually identify the change of state through the application and call the respective API (appInForeground() or appInBackground()) to inform the SDK regarding the change of state from background to foreground or foreground to background.

	The SDK is informed about app state using the below methods.		The SDK is informed about app state using the below methods.