Ancillary Android Modules

Phenix provides additional modules that extend the functionality of the Phenix SDK.

The phenix-sdk-nielsen-android helper module can be used to integrate Nielsen measurements into your Android app.

When you are subscribing to a stream which provides Nielsen ID3 tags, you can use it to easily integrate with the Nielsen App SDK. This functionality applies to H264 formatted real time video streams only.

The phenix-sdk-nielsen-android module uses the subscribeToNielsenId3Tag method from the Phenix SDK. It transforms the data that method provides in the way the Nielsen App SDK expects it.

In addition to this module there is a low-level API that provides direct access to the raw ID3 tags including the full ID3 and ID3 frame headers. The ID3 header is 10 bytes long and looks like the example shown below, where each box represents a byte. See more detailed documentation here.

Nielsen's Android App SDK expects to receive just the value of the ID3 tag as a string, without ID3 headers. So integrating with that SDK using the raw API, without using the helper module, would look like this:

channelExpress?.joinChannel(options,
  { requestStatus: RequestStatus?, service: RoomService? -> },
  { requestStatus: RequestStatus?, subscriber: ExpressSubscriber?, renderer: Renderer? ->
    val nielsenAppSdk = /* Create instance and initialize an instance of the Nielsen App SDK here */
    nielsenId3Subscription = subscriber?.subscribeToNielsenId3Tag(
      { nielsenId3Tag: NielsenId3Tag ->
        val id3HeaderLength = 10
        val id3MajorVersion = nielsenId3Tag.data[3].toInt()
        val id3FrameHeaderLength = if(id3MajorVersion == 2) 6 else 10
        val nielsenId3TagString = String(nielsenId3Tag.data, id3HeaderLength + id3FrameHeaderLength, 249, Charset.forName("UTF-8"))
        nielsenAppSdk.sendID3(nielsenId3TagString);
      },
      { nielsenId3Error: NielsenId3Error ->
	 CLIENT_FUNCTION_TO_USE_HANDLE_ERRORMESSAGE(nielsenId3Error.message)
      })
  })
}

In order to use this module, add both the phenix-sdk-android and phenix-sdk-nielsen-android artifacts to your Gradle project. Both should have the same version string. Refer to the readme for more information.

First, subscribe to a channel using ChannelExpress. When you call joinChannel(), pass in a callback that contains the following code.

let nielsenAppSdk = /* Create instance and initialize an instance of the Nielsen App SDK here */
this@ChannelExpressRepository.nielsenIntegration = NielsenIntegration(expressSubscriber!!, {tag: String ->
    nielsenAppSdk.sendID3(tag)
}, {errorMessage: String ->
    Log.e("Nielsen ID3 error [$errorMessage]")
})

In the example code above, the application needs to keep a reference on the nielsenSubscription member for as long as the Nielsen integration is needed on that particular Channel. Once it is destroyed the integration will stop processing Nielsen ID3 tags.

For details on creation and initialization of the Nielsen App SDK, refer to the documentation provided by Nielsen.