Articles in this section

See more

iOS/tvOS AV Player - Gen 3

Avatar
Tony Gentile
Follow

Datazoom is a high-availability real-time data collection solution. This document summarizes how to integrate the iOS/tvOS AV Player with the Datazoom platform.


  1. Login to Datazoom here:  https://app.datazoom.io


  2. Add a Collector as indicated here:  How to add a Collector

    2 - Select Collectors to edit.png

  3. Copy the config key that was created at the end of the process
    Click the icon indicated below to copy the Configuration Key

    Copy icon.png


apple_dz_avplayer_adapter

The DzAVPlayerAdapter is designed to provide integration support for the AVPlayer implementations.

Description

The DzAVPlayerAdapter project offers a set of utilities and functionalities to facilitate seamless integration with AVPlayer implementations. It provides common code and abstraction layers to streamline the integration of Datazoom's tracking capabilities into AVPlayer-powered applications.

Installation

To use the DzAVPlayerAdapter project in your application, include the following dependency in your project's Gradle file:

Cocoapods

pod 'DzAVPlayerAdapter', '~> 0.0.1'

Swift package manager

TODO: Gitlab link + version

Usage

To integrate the DzAVPlayerAdapter project into your project:

Initialize DzAVPlayerAdapter by providing your Datazoom API key and configuring necessary settings.

Initialization

 let configBuilder = Config.Builder(configurationId: configId)
 configBuilder.logLevel(logLevel: .verbose)
 configBuilder.isProduction(isProduction: isProduction)
 
 Datazoom.shared.doInit(config: configBuilder.build())

Create Context

If you want to track events from your AVPlayer, you need to create a context and assign your player to it so that the SDK can track events and metadata from your specified player.

/**
  *  Creates a player context. A player context is used to embed the player with Datazoom and is responsible for player-specific events.
  *  - Parameters:
  *      - player: The AVPlayer instance.
  *      - eventSpace: The event space to be used to create the player context. This parameter is optional. If not provided, a default event space will be created.
  *  - Returns: The DzAdapter.
 * @see <a href="https://help.datazoom.io/">Datazoom Help</a>
 */
func createContext(
    player: AVPlayer,
    eventSpace: BaseContext = Datazoom.shared.createBaseContext()
) -> DzAdapter
Example
Datazoom.shared.createContext(player: yourAVPlayer)

Custom Metadata - Context

Context custom metadata is used to attach metadata, which is a Dictionary of your choice, to each event sent from the given context you created using the Datazoom object. For more information, please refer to the Datazoom documentation on metadata.

API looks like

/**
 * Sends metadata to Context.
 *
 * - Parameters:
        - metadata: a Dictionary that will be attached to each event being sent from SDK, for more information on this topic, please visit our
 *   documentation.
 */
func setMetadata(metadata: <String, Any>)
Example
yourAVPlayerContext.setMetadata(
    [
        "property": "custom property",
        "property2": "custom property2",
    ]
)

You can also retrieve your current metadata by calling the following API:

/**
 * Returns the metadata that is being sent with each event in given context.
 *
 * @return The metadata that is being sent with each event in given context.
 */
func getMetadata() -> <String, Any>
Example
yourAVPlayerContext.getMetadata()

Casting

We have ability to send casting event, we don't track any communication you have with chromecast receiver. We expect you to invoke context/adapter following function with a boolean sending casting state.

func sendCastEvent(isCasting: Boolean)
Example
yourAVPlayerContext.sendCastEvent(isCasting = {castingState})

Custom Events - Context

To send events in the global scope, you can use the following method, with each parameter explained below.

/**
 * Sends an event to given context.
 *
 *   - Parameters:
 *      - name: The name of the event.
 *      - payload: a Dictionary that will be attached to each event being sent from given context, for more information on this topic, please visit our   documentation.
 */
func generateEvent(name: String, payload: <String, Any>)
Example
Datazoom.shared.generateEvent(
    name = "login",
    eventMap =
        [
            "property": "custom property",
            "property2": "custom property2",
        ]
)

Custom Events - Global

To send events in the global scope, you can use the following method, with each parameter explained below.

/**
 * Sends an event to Datazoom.
 *
 *  - Parameters:
 *      - name: The name of the event.
 *      - payload: a Dictionary that will be attached to each event being sent from SDK, for more information on this topic, please visit our documentation.
 */
fun generateEvent(name: String, payload: <String, Any>)
Example
Datazoom.shared.generateEvent(
    name = "login",
    eventMap =
        [
            "property": "custom property",
            "property2": "custom property2",
        ]
)

Custom Metadata - Global

Global metadata is used to attach metadata, which is a HashMap of your choice, to each event sent from any context you created using the Datazoom object. For more information, please refer to the Datazoom documentation on metadata.

API looks like

/**
 * Sends metadata to Datazoom.
 * 
 *  - Parameters:
 *      - metadata: a Dictionary that will be attached to each event being sent from SDK, for more information on this topic, please visit our
 *   documentation.
 */
fun setMetadata(metadata: <String, Any>)
Example
Datazoom.shared.setMetadata(
    [
        "property": "custom property",
        "property2": "custom property2",
    ]
)

Get all player context

Datazoom support having multiple contexts, you can create multiple contexts, Datazoom keep track of all created context and give ability to get if you need anytime of your app lifecycle.

API looks like

/**
 * Returns a list of all player contexts.
 *
 * @return A list of all player contexts. You can retrieve list of all player contexts at anytime in player lifecycle.
 */
fun playerContexts() -> [DzAdapter]
Example
Datazoom.shared.playerContexts()

Destroy Context

If you want to destroy a context, there are multiple ways to do it. Ideally, you should ask the Datazoom object to destroy the context by either providing your context ID or the context/adapter itself.

/**
 * Removes a player context.
 *
 * @param adapter The adapter to be used to remove the context.
 */
fun removeContext(adapter: DzAdapter)

or

/**
 * Removes a player context.
 *
 * @param id The id of the player context to be removed. its the same id returned by
 * @sample createContext(adapter: DzAdapter): String
 */
fun removeContext(id: String)

Please make sure that once the context is removed from Datazoom, you do not use it for communication because it will no longer be able to communicate with the server, and you might miss critical events.

Example
  Datazoom.shared.removeContext("contextId")

or

  Datazoom.shared.removeContext(context)

Listening SDK events

 Datazoom.shared.sdkEvents.watch { event in
    guard let eventDescription = event?.description as? String else { return }
    if eventDescription.contains("SdkInit") {
        // SDK initialized
    } else if eventDescription.contains("SdkError") {
        // SDK error 
    } else if eventDescription.contains("AdapterCreated") {
        // Adapter created 
     }
}

Supported Client Events

SdkInit

The "SdkInit" event signals the successful initialization of the SDK and the receipt of the API key used during initialization. Upon receiving this event, users can confidently proceed with utilizing the SDK's functionalities, knowing that the SDK is ready for use with the provided API key. Ensure to handle this event appropriately in your application code to synchronize operations requiring the SDK's readiness

SdkError

The "SdkError" event is triggered when an error occurs during the operation of the SDK. This event provides crucial information about the nature of the error, such as error codes or descriptive messages, allowing users to identify and handle errors effectively within their applications.

AdapterCreated

The "AdapterCreated" event signifies the successful creation of an adapter within the SDK. This event provides notification to users that the adapter, responsible for interfacing with external systems or components, is ready for use. Utilize this event to synchronize operations dependent on the availability of the adapter within your application code.

Issues

If you encounter any issues or have suggestions for improvements, please open an issue on the GitHub repository.


Related articles

Comments

0 comments

Please sign in to leave a comment.