Ancillary iOS Modules

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

The PhenixSdkNielsen helper module can be used to integrate Nielsen measurements into your iOS or tvOS 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 PhenixSdkNielsen 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, {status, roomService in}) {
  let nielsenAppSdk = /* Create instance and initialize an instance of the Nielsen App SDK here */
  self.nielsenSubscription = subscriber.subscribe(
      	    toNielsenId3Tag: { (nielsenId3Tag: PhenixNielsenId3Tag?) in
            guard let data = nielsenId3Tag?.data else { return }

     // The ID3 header and frame header specification can be found at
            // https://id3.org/id3v2.3.0#ID3v2_header
            let id3HeaderLength = 10
            let id3HeaderMajorVersionOffset = 3
            let id3MajorVersion = data[id3HeaderMajorVersionOffset]
            let id3FrameHeaderLength = if id3MajorVersion == 2 { 6 } else { 10 }
            let rangeStart = id3HeaderLength + id3FrameHeaderLength

            guard let nielsenId3TagString = String(
                	data: data.subdata(in: rangeStart..<(rangeStart + 249)), 
			encoding: .utf8)
            else { return }
            nielsenAppSdk.sendID3(nielsenId3TagString)
      	  },
      	  { 
    (nielsenId3Error: PhenixNielsenId3Error?) in
            guard let errorMessage = nielsenId3Error?.message else { return }
            CLIENT_FUNCTION_TO_USE_HANDLE_ERRORMESSAGE(errorMessage)
         })
}

If using CocoaPods, add both the PhenixSdk and PhenixSdkNielsen CocoaPods to your project. Make sure to use the same version string for both.

If using SPM, the Swift repository provides both these modules. Refer to the respective readme files (CocoaPods, SPM) for details.

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 */
self.nielsenSubscription = NielsenIntegration(subscriber: subscriber, nielsenCallable: {(tag: String) -> Void in
    nielsenAppSdk.sendID3(tag)
}, nielsenErrorHandler: {(errorMessage: String) -> Void in
    DispatchQueue.main.async {
        AppDelegate.terminate(
            afterDisplayingAlertWithTitle: "Something went wrong!",
            message: "Error processing Nielsen ID3 tag (\(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.