DCR & DTVR Android Adobe Launch Extension

From Engineering Client Portal

Revision as of 00:27, 12 January 2019 by Admin3 (talk | contribs)

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png DCR & DTVR breadcrumbArrow.png DCR & DTVR Android Adobe Launch Extension

Adobe Launch Extensions

Adobe Launch Extensions are building blocks for mobile application development. The necessary functionality can be implemented independently and put to separate Extensions, but make them able to communicate using Events. These extensions live on Artifactory servers and can be used by clients who develop their mobile applications.

Nielsen AppSDK Extension

Nielsen provides the Adobe Launch Extension based on AppSDK for measuring the video/audio content. It has the name Nielsen AppSDK Extension and is available for android and iOS mobile platforms.

Extension Installation and Configuration

Adobe has developed an Extension to simplify adding Nielsen measurement into your video stream. The first step is to create and publish a property which is outlined in the Getting Started Guide.

Configure the Extension

If the user doesn’t want to set the configuration in the code and wants to make the configuration more flexible and changeable on the fly, it can be configured through the interface. In order to do that, go to the collection of installed extensions of the property. icon The configuration allows to set different configuration for iOS and Android platforms: icon

Build the Extension

After the Extension is configured, it can be “built” under the “library” on the Publishing page with other “libraries”. It is the main step for adding the configuration to the main configuration file and to register the package under specific App Id after building it.

Add a New library

Select to add a new library

icon

Set the name, chose Environment (Production, Staging, Development):

icon

Save and Build

Add all changed resources. When you get the Extension configured, it will appear in the list of changed resources. Select the Latest revision and press “Select & Create a New Revision” button: icon

Confirm

Once built, it will appear in the list of Development libraries:

icon

View in Library

Once it is set up, the user will be prompted to the Environments page where it can be Installed.

icon

Obtain Mobile Installation Instructions

You will then be provided the Mobile Installation Instructions.

icon

How to install the Nielsen AppSDK using Gradle for Android

Below are the steps which needs to be performed by app developers to integrate nielsen app sdk within an android application.

Update grade.properties

The first step is to add the credentials received from Nielsen into your gradle.properties file, generally near the end of the file. We recommend using the version in your home folder (Global Properties). Grade looks for gradle.properties files in this sequence:

  • gradle.properties in project root directory.
  • gradle.properties in GRADLE_USER_HOME directory.
  • system properties, e.g. when -Dgradle.user.home is set on the command line.

Properties from one file will override the properties from the previous ones (so file in gradle user home has precedence over the others, and file in sub-project has precedence over the one in project root).

Reference: https://gradle.org/docs/current/userguide/build_environment.html

machine raw.githubusercontent.com
nielsen_user=<Nielsen App SDK client>
nielsen_authCode=<Auth token>


Your Credentials are:

machine raw.githubusercontent.com
login NielsenSdkRepo
password edec0d01b953171c704188c1d8fc0aa4217ec506

Add Nielsen Maven Repository

Please add the nielsen maven repository inside the repositories section of your app's module build.gradle file like below:

android{ 
repositories {
   //Copy below code inside repository section of app’s build.gradle file
maven { url 'https://raw.githubusercontent.com/NielsenDigitalSDK/nielsenappsdk-extension-android/master/'
   credentials {
      //Make sure you add nielsen_user and nielsen_passwd with respective nielsen provided
     // values to global gradle.properties file
       username = project.property("nielsen_user")
       password = project.property("nielsen_authCode")
   }
   authentication {
       basic(BasicAuthentication)
   }
}
}

}

Add gradle dependency

Please add nielsen app sdk as compile time dependency inside build.gradle file as below

grade 4.x and above

For gradle version starting with 4.x add below line inside dependencies section of build.gradle file.

implementation 'com.nielsenappsdk.extension:${flavour}:${version}'

grade prior to 4.x

For gradle version previous to 4.x add below line inside dependencies section of build.gradle file.

compile 'com.nielsenappsdk.extension:${flavour}:${version}'

Adding Dependency

Below is an example for dependency

dependencies { ....
implementation 'com.nielsenappsdk.extension:global:1.0.0'
}

Ensuring you have the latest release information

It is recommended to use the most recent version of the NielsenSDK by using the following:

dependencies { ....
implementation 'com.nielsenappsdk:global:+'
}


In addition, please add below gradle task inside your build.gradle (Module:app) or build.gradle(Project:My-app) file to fetch latest release details of nielsen app sdk as below:

Please note: The build.gradle (Module:app) can overwrite the build.gradle(Project:My-app).

task NielsenSdkReleaseCheck {
   def login_details = project.property("nielsen_user")+":"+project.property("nielsen_authCode")
   def p = ['curl', '-u',login_details ,"https://raw.githubusercontent.com/NielsenDigitalSDK/nielsenappsdk-android/master/com/nielsenappsdk/global/NielsenAppSdk-ReadMe.md"].execute().text
   project.logger.log(LogLevel.ERROR,p)
}
preBuild.dependsOn('NielsenSdkReleaseCheck')

Sync

If you are finished with all previous steps then you can sync your build.gradle and after successful build you are ready to use nielsen app sdk library in your code.



Integration

To use nielsen app sdk extension in your android code you need to register your extension inside your Application class or very first activity like below. Please make sure that you register it only once in complete life cycle of your application.

//Register Nielsen extension and configure adobe launch mobile core
  MobileCore.setApplication(this);
  MobileCore.setLogLevel(LoggingMode.DEBUG); //Log level can be changed to your required one 

   //Register NielsenSdkExtension 
   NielsenSdkExtension.registerExtension();
   //Pass application context to NielsenSdkExtension
   NielsenSdkExtension.setApplicationContext(getApplicationContext());
   //Register notify listener to listen errors or messages informed by extension
   NielsenSdkExtension.registerNotifyEventListener(ExtensionErrorListener.class);
   Identity.registerExtension();
   Lifecycle.registerExtension();
   Signal.registerExtension();
   UserProfile.registerExtension();
   MobileCore.start(new AdobeCallback()
  {
       @Override
       public void call(Object o) 
       {
MobileCore.configureWithAppID("adobe launch configuration id");
       }
   });

Communication

The communication with the Extension happens by two separate flows: API and Events. The first one just redirects Extension’s class-access methods to direct instances of the NielsenAppSDK. The second one works with ACPCore’s EventHub - the core of the extension. Through the Hub the Core receives all the events and notifies the listeners if they are subscribed for them.

NOTE: be aware of mixing the approaches. Because of different architectures for API approach and Event approach (and the asynchronous nature of Events), it is not guaranteed that events and API will be handled in order of their call.

The list of APIs (the meaning of each event and API is described later in this document)

Public APIs exposed by extension

+ (NSDictionary *)instantiateSDKWithConfiguration:(NSDictionary *)configuration;
+ (NSDictionary *)instantiateSDKWithRemoteConfiguration;
+ (NSDictionary *)removeSDKWithIdentifier:(NSString *)identifier;
+ (NSDictionary *)trackEvent:(NSDictionary *)event forSDKWithIdentifier:(NSString *)identifier;
+ (NSDictionary *)optOutStatusForSDKWithIdentifier:(NSString *)identifier;
+ (NSDictionary *)appDisableForSDKWithIdentifier:(NSString *)identifier;
+ (NSDictionary *)setAppDisable:(BOOL)appDisable forSDKWithIdentifier:(NSString *)identifier;
+ (NSDictionary *)debugForSDKWithIdentifier:(NSString *)identifier;
+ (NSDictionary *)setDebug:(BOOL)debug forSDKWithIdentifier:(NSString *)identifier;
+ (NSDictionary *)demographicIdForSDKWithIdentifier:(NSString *)identifier;
+ (NSDictionary *)optOutURLForSDKWithIdentifier:(NSString *)identifier;
+ (NSDictionary *)meterVersionForSDKWithIdentifier:(NSString *)identifier;
+ (void)registerListenerForSDKNotifier:(Class)aClass;

Events

  1. InstantiateSDKWithLocalConfigEvent
  2. InstantiateSDKWithRemoteConfigEvent
  3. RemoveSDKInstanceEvent
  4. TrackSDKEvent
  5. GetOptoutStatusEvent
  6. GetAppDisableEvent
  7. SetAppDisableEvent
  8. GetDebugEvent
  9. SetDebugEvent
  10. GetDemographicIdEvent
  11. GetOptoutURLEvent
  12. GetMeterVersionEvent

In order to fire the event, the next API of the ACPCore should be used:

NSError *error = nil;
NSString *name = @...;
NSString *type = @com.nielsen.eventType.instanceControl;
NSString *source = @com.nielsen.eventSource.instanceControl;
NSDictionary *payload = @{
    identifier: the identifier under which the instance is kept
or
    data: {appid:..., ...}
};
ACPExtensionEvent *newEvent = [ACPExtensionEvent extensionEventWithName:name
                                                                                                                            type:type 
                                                                                                                        source:source
                                                                                                                            data:payload 
                                                                                                                            error:&error];
if (error)
{
    NSLog(@"Error constructing new event %@:%ld", [error domain], (long)[error code]);
    return;
}

[ACPCore dispatchEventWithResponseCallback:newEvent 
          responseCallback:^(ACPExtensionEvent * _Nonnull responseEvent) {
    //Use responseEvent.eventData to collect the result data
} error:&error];

if (error)
{
    NSLog(@"Error dispatching event %@:%ld", [error domain], (long)[error code]);
}

The Extension listens for specific events’ type and source and handles specific event names differently. The API and Event flows are mirroring each other. And they are mirroring NielsenAppSDK’s api.

Result

The result format that is returning with API flow and with Event flow is the same for both flows - this is a JSON object.

It consists of the result code, description and the identifier. { ‘identifier’ : ‘...’, //might not be there if the “remove” API or Event is made ‘code’ : 5001, ‘description’ : ‘...’ }

Possible error codes are:

typedef NS_ENUM(NSUInteger) {
    NielsenAppSDKExtensionResultCodeSuccess = 5001,
    NielsenAppSDKExtensionResultCodeUnexpected = 5002,
    NielsenAppSDKExtensionResultCodeNoRemoteConfiguration = 5003,
    NielsenAppSDKExtensionResultCodeNoLocalConfiguration = 5004,
    NielsenAppSDKExtensionResultCodeMissingParameter = 5005,
    NielsenAppSDKExtensionResultCodeSDKInstantiationFailure = 5006,
    NielsenAppSDKExtensionResultCodeNoSDKInstance = 5010,
    NielsenAppSDKExtensionResultCodeExceptionOccured = 5011,
    NielsenAppSDKExtensionResultCodeInvalidEventReceived = 5012
} NielsenAppSDKExtensionResultCode;

API and Events description

Instantiating the SDK

NielsenAppSDK can support multiple instances, and not to lose this feature, the Extension keeps SDK instances by the identifiers. When the user requests to create the instance, the Extension instantiates it and returning back the identifier which the user will use for further SDK control.

There are two ways of initializing the SDK with configuration: the configuration provided in the code and configuration that is set up on the Adobe Launch panel of your property.

To support four flows (API, Events, Local Configuration and the Remote Configuration) the next APIs and events are introduced: NSDictionary *result = [NielsenAppSDKExtension instantiateSDKWithConfiguration:@{“appid”:”...”, “sfcode”:”...”}] NSDictionary *result = [NielsenAppSDKExtension instantiateSDKWithRemoteConfiguration]

Event “InstantiateSDKWithLocalConfigurationEvent” “InstantiateSDKWithRemoteConfigurationEvent”

To provide the configuration for “InstantiateSDKWithLocalConfigurationEvent” event, put the configuration under the “data” key in the JSON object: { “data” : {“appid”:”...”, “sfcode”:”...”} }

The result of those APIs and events is a JSON object. It returns the identifier string under which a newly created instance is kept. Use the identifier to make further calls to control the NielsenAppSDK.

Removing the SDK instance

In order to remove the instance that the Extension is keeping, call the remove API or fire an event with providing the identifier.

NSDictionary *result = [NielsenAppSDKExtension removeSDKWithIdentifier:@the identifier under which instance is kept]

Event

“RemoveSDKInstanceEvent”

To provide the identifier for “RemoveSDKInstanceEvent” event, put the configuration under the “identifier” key in the JSON object:

{
	identifier : the identifier under which instance is kept
}

All result returned are in JSON object

Additional Resources

For more information on CocoaPods or How to set up the Profile in the Using Cocoapods page.

Tracking the SDK Event

To track NielsenAppSDK’s event call the track SDK Event API or fire an event with providing the identifier.

NSDictionary *result = [NielsenAppSDKExtension trackEvent:@{event:playhead, playheadPosition:0, ...} 
                            forSDKWithIdentifier:@the identifier under which instance is kept]

Event

“TrackSDKEvent”

To provide the identifier for “TrackSDKEvent” event, put the identifier under the “identifier” key in the JSON object and the event metadata: { “identifier” : “the identifier under which instance is kept”, “data” : {“event”:”playhead”, “playheadPosition”:”0”, ...} }

Retrieving the Opt Out Status

Enabling and disabling the SDK

Setting Debug mode for the SDK