Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[SDK README - api.video-android-databus] Bugfix/documentation #268

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[SDK README - api.video-android-databus] Bugfix/documentation #268

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 27 additions & 93 deletions sdks/player/apivideo-android-player-analytics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,121 +1,55 @@
---
## THIS FILE IS AUTOMATICALLY GENERATED. DO NOT EDIT. IF YOU NEED TO CHANGE THIS FILE, CREATE A PR IN THE SOURCE REPOSITORY.
title: api.video Android Player analytics plugin
meta:
description: The official api.video Android Player analytics plugin for api.video. [api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.
title: api.video Android player analytics
meta:
description: The official api.video Android player analytics library for
api.video. [api.video](https://api.video/) is the video infrastructure for product builders.
Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live
streaming features in your app.
---

# api.video Android Player analytics plugin

[api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.

## Project description

Android library to manually call the api.video analytics collector.

This is useful if you are using a video player for which we do not yet provide a ready-to-use
monitoring module.
This library sends player events from the player to api.video.

## Getting started

### Installation

#### Gradle

In your module `build.gradle`, add the following code in `dependencies`:
For ExoPlayer, add the following code in your module `build.gradle`:

```groovy
dependencies {
implementation 'video.api:android-player-analytics:2.0.2'
implementation 'video.api.player.analytics:android-player-analytics-exoplayer:3.0.0'
}
```

### Permissions

In your `AndroidManifest.xml`, add the following code in `<manifest>`:

```xml

<uses-permission android:name="android.permission.INTERNET" />
```

## Sample application

A demo application demonstrates how to use player analytics library.
See [`/example`](https://github.com/apivideo/api.video-android-player-analytics/tree/main/example)
folder.

## Documentation

### Options

The analytics module constructor takes a `Options` parameter that contains the following options:

| Option name | Mandatory | Type | Description |
|--------------------:|-----------|-----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| mediaUrl | ** | | |
| yes** | String | url of the media (eg. `https://vod.api.video/vod/vi5oDagRVJBSKHxSiPux5rYD/hls/manifest.m3u8`) | |
| videoInfo | ** | | |
| yes** | VideoInfo | information containing analytics collector url, video type (vod or live) and video id | |
| metadata | no | ```Map<String, String>``` | object containing [metadata](https://api.video/blog/tutorials/dynamic-metadata/) |
| onSessionIdReceived | no | ```((sessionId: String) -> Unit)?``` | callback called once the session id has been received |
| onPing | no | ```((message: PlaybackPingMessage) -> Unit)?``` | callback called before sending the ping message |

Options instantiation is made with either mediaUrl or videoInfo.

Once the module is instantiated, the following methods have to be called to monitor the playback
events.

### ApiVideoPlayerAnalytics API

#### Event time or current time

If you know the event timestamp, you can use it as the `eventTime` parameter. If you don't know the
event timestamp, you can set the `currentTime` parameter with a scheduler.

**`play(eventTime: Float = currentTime): Future<void>`**

method to call when the video starts playing for the first time (in the case of a resume after
### Code sample

paused, use `resume()`)
Register the ExoPlayer player analytics agent with:

**`resume(eventTime: Float = currentTime): Future<void>`**
```kotlin
import androidx.media3.exoplayer.ExoPlayer
import video.api.analytics.exoplayer.extensions.addDatabusAgent

method to call when the video playback is resumed after a pause
val exoplayer = ExoPlayer.Builder(context).build()
val listener =
exoplayer.addApiVideoAnalyticsListener() // Register the ApiVideo exoplayer analytics listener so it sends player events to api.video.

// Remove the analytics listener when you don't need it anymore.
exoplayer.removeAnalyticsListener(listener)
```

**`ready(eventTime: Float = currentTime): Future<void>`**

method to call once the player is ready to play the media


**`end(eventTime: Float = currentTime): Future<void>`**

method to call when the video is ended


**`seek(from: Float, to: Float): Future<void>`**

method to call when a seek event occurs, the `from` and `to` parameters are mandatory and should

contains the seek start & end times in seconds

**`pause(eventTime: Float = currentTime): Future<void>`**

method to call when the video is paused


**`destroy(eventTime: Float = currentTime): Future<void>`**

method to call when the video player is disposed (eg. when the use closes the navigation tab)


**`currentTime`**

field to call each time the playback time changes (it should be called often, the accuracy of the
For a custom domain collector, use:

collected data depends on it) if you don't know event time.
```kotlin
val agent =
exoplayer.addDatabusAgent(collectorUrl = "https://collector.mycustomdomain.com") // Register the Databus agent so it sends player events to api.video.
```

### API documentation
## FAQ

A complete [API documentation](https://apivideo.github.io/api.video-android-player-analytics/) is available.
If you have any questions, ask us in the [community](https://community.api.video).
Loading