newrelic/video-agent-android

Video Agent for Android

New Relic Video Agent for Android

The New Relic Video Agent for Android contains multiple modules necessary to instrument video players and send data to New Relic.

Modules

There are three modules available:

NewRelicVideoCore

Contains all the base classes necessary to create trackers and send data to New Relic. It depends on the New Relic Agent.

NRExoPlayerTracker

The video tracker for ExoPlayer2 player. It depends on NewRelicVideoCore.

NRIMATracker

The video tracker for Google IMA Ads library. It depends on NewRelicVideoCore.

Installation

Prerequisites

Install the New Relic Android Agent, and any other needed dependency, like ExoPlayer or Google IMA.

Install automatically using JitPack

Add the following line inside your root build.gradle:

allprojects {
    repositories {
        ...
        
        // Add this line at the end of your repositories
        maven { url 'https://jitpack.io' }
    }
}

And inside your app's build.gradle, add the following dependencies:

dependencies {
    ...

    // Add this to install the NewRelicVideoCore (required)
    implementation 'com.github.newrelic.video-agent-android:NewRelicVideoCore:master-SNAPSHOT'
    
    // Add this to install the ExoPlayer tracker
    implementation 'com.github.newrelic.video-agent-android:NRExoPlayerTracker:master-SNAPSHOT'
    
    // Add this to install the Google IMA library tracker
    implementation 'com.github.newrelic.video-agent-android:NRIMATracker:master-SNAPSHOT'
}

To install an specific version, replace the master-SNAPSHOT by a version tag.

Install manually using AAR files

1. Clone this repo.
2. Open it with Android Studio.
3. Click on View > Tool Windows > Gradle to open the gradle tool window.
4. In there, unfold NRVideoProject > Tasks > build and double-click on assemble. This will generate the AAR libraries inside the module's folder build > outputs > aar.
5. In your project, click on File > New > New Module, Import .JAR/.AAR Package and then Next.
6. Enter the location of the generated AAR file then click Finish.
7. Repeat steps 5 and 6 with all the AAR files you want to include.
8. In you app module's build.gradle file, add the following:

dependencies {
	...
	implementation project(":NewRelicVideoCore")
	implementation project(":NRExoPlayerTracker")
	implementation project(':NRIMATracker')
}

Install manually using source code

1. Clone this repo.
2. In your project, click File > New > Import Module.
3. Enter the location of the library module directory (located in the repo you just cloned) then click Finish.
4. Repeat steps 2 and 3 with all the modules you want to include.
5. In you app module's build.gradle file, add the following:

dependencies {
	...
	implementation project(":NewRelicVideoCore")
	implementation project(":NRExoPlayerTracker")
	implementation project(':NRIMATracker')
}

Usage

To start the video agent with ExoPlayer tracker only:

Java

Integer trackerId = NewRelicVideoAgent.getInstance().start(new NRTrackerExoPlayer(player));

Kotlin

val trackerId = NewRelicVideoAgent.getInstance().start(NRTrackerExoPlayer(player))

To start the video agent with ExoPlayer and IMA trackers:

Java

Integer trackerId = NewRelicVideoAgent.getInstance().start(new NRTrackerExoPlayer(player), new NRTrackerIMA());

Kotlin

val trackerId = NewRelicVideoAgent.getInstance().start(NRTrackerExoPlayer(player), NRTrackerIMA())

Documentation

To generate the javadocs, open the project in Android Studio and then go to Tools > Generate JavaDoc..., select Whole Project, then select the Output directory and click OK.

For more detail on the Events and Data Model generated by Video Agent for Android and for advanced concepts such as creating custom trackers, reference the Advanced Topics manual.

Examples

The app folder contains a usage example that shows the basics of video tracking using ExoPlayer.

Testing

The Test folder contains the test apps.

Support

New Relic has open-sourced this project. This project is provided AS-IS WITHOUT WARRANTY OR DEDICATED SUPPORT. Issues and contributions should be reported to the project here on GitHub.

We encourage you to bring your experiences and questions to the Explorers Hub where our community members collaborate on solutions and new ideas.

Contributing

We encourage your contributions to improve New Relic Video Agent! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project. If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at [email protected].

A note about vulnerabilities

As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.

If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.

License

New Relic Video Agent is licensed under the Apache 2.0 License.

video-agent-android's Issues

viewId is cleared upon every AD_BREAK_ events

Upon heavy usage of our video data by building different dashboards with multiple widgets, we noticed that some of our events had no viewIds during ads.

After a bit of research, we stumbled upon this line in the library: https://github.com/newrelic/video-agent-android/blob/master/NewRelicVideoCore/src/main/java/com/newrelic/videoagent/core/tracker/NRVideoTracker.java#L197

The viewId is actually cleared on any AD_BREAK_* event, which kind of skew our data when playing around for widget related to ads.

What is the reasoning behind this approach? We noticed iOS also doing it, but not Web.

Please note, I will enter the same issue in both repositories (iOS and Android).

Where's 1.0.1 in jitpack?

Their log says its all

https://jitpack.io/com/github/newrelic/video-agent-android/1.0.1/build.log

Check/enforce underlying agent version >=6.0.0

Check/enforce underlying agent version >=6.0.0

Support for Media 3?

Is there a timeline on when this and NR in general shall support Android Media 3 library instead of ExoPlayer 2?

Update to new ExoPlayer instead of the now deprecated SimpleExoPlayer

Looks like this happened in this version: 2.16.0 (2021-11-04)

Current version of Exo as of now: 2.17.1 (2022-03-10)

totalAdPlaytime must count the total ad break time

757d203

New Relic 6.9.1 breaks this library

Due to the linked build.gradle directive, the build picked up 6.9.1 and all of a sudden our video events were no longer received by New Relic. Not sure why (yet), but once we excluded and used 6.8.0 (which we had in production earlier), everything worked magically again.

video-agent-android/app/build.gradle

Line 55 in 97fa0ca

implementation 'com.newrelic.agent.android:android-agent:+'

    implementation("com.github.newrelic.video-agent-android:NewRelicVideoCore:0.99.6") {
        exclude(group = "com.newrelic.agent.android")
    }
    implementation("com.github.newrelic.video-agent-android:NRExoPlayerTracker:0.99.6") {
        exclude(group = "com.newrelic.agent.android")
    }
    implementation("com.github.newrelic.video-agent-android:NRIMATracker:0.99.6") {
        exclude(group = "com.newrelic.agent.android")
    }