From 7cf4a875ead33a4a39cca4b89ec6ee17ca0f6b00 Mon Sep 17 00:00:00 2001 From: ThibaultBee Date: Thu, 18 Jul 2024 10:01:32 +0000 Subject: [PATCH] Bugfix/documentation --- .../apivideo-android-player-analytics.md | 120 ++++-------------- 1 file changed, 27 insertions(+), 93 deletions(-) diff --git a/sdks/player/apivideo-android-player-analytics.md b/sdks/player/apivideo-android-player-analytics.md index 33eca2a6..ce140263 100644 --- a/sdks/player/apivideo-android-player-analytics.md +++ b/sdks/player/apivideo-android-player-analytics.md @@ -1,20 +1,17 @@ --- ## 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 @@ -22,100 +19,37 @@ monitoring module. #### 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 ``: - -```xml - - -``` - -## 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``` | 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`** - -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`** +```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`** - -method to call once the player is ready to play the media - - -**`end(eventTime: Float = currentTime): Future`** - -method to call when the video is ended - - -**`seek(from: Float, to: Float): Future`** - -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`** - -method to call when the video is paused - - -**`destroy(eventTime: Float = currentTime): Future`** - -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).