From d9b1e4e09125ad098571d2c7c16651799fee4909 Mon Sep 17 00:00:00 2001
From: Lukas Knoch-Girstmair <lukas.knoch-girstmair@bitmovin.com>
Date: Wed, 3 Jul 2024 14:44:10 +0200
Subject: [PATCH] Add changelog and basic documentation for SSAI tracking

---
 CHANGELOG.md |  2 ++
 README.md    | 31 +++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df719f1..79a8c60 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
+### Added
+- `ConvivaAnalyticsIntegration.ssai` namespace to enable server side ad tracking
 
 ### Fixed
 - Potential exception when determining the IMA SDK version on ad start
diff --git a/README.md b/README.md
index 82f8409..fe03037 100644
--- a/README.md
+++ b/README.md
@@ -133,6 +133,37 @@ A session can be ended using following method call:
 `convivaAnalyticsIntegration.endSession()`
 Since the `BitmovinPlayer` automatically pauses the video if no background playback is configured the session creation after the app is in foreground again is handled automatically.
 
+#### Server Side Ad Tracking
+
+In order to track server side ads you can use the functions provided in `ConvivaAnalyticsIntegration.getSsai()`. The following example shows basic server side ad tracking:
+```java
+SsaiApi ssai = convivaAnalyticsIntegration.getSsai();
+
+ssai.reportAdBreakStarted();
+
+SsaiApi.AdInfo adInfo = new SsaiApi.AdInfo();
+adInfo.setPosition(AdPosition.PREROLL);
+adInfo.setTitle("My ad title");
+adInfo.setDuration(30);
+ssai.reportAdStarted(adInfo);
+
+...
+
+ssai.reportAdFinished();
+ssai.reportAdBreakFinished();
+```
+
+In addition to the metadata provided in the `AdInfo` object at ad start, the following metadata will be auto collected from the main content metadata:
+- ConvivaSdkConstants.STREAM_URL
+- ConvivaSdkConstants.ASSET_NAME
+- ConvivaSdkConstants.IS_LIVE
+- ConvivaSdkConstants.DEFAULT_RESOURCE 
+- ConvivaSdkConstants.ENCODED_FRAMERATE
+- streamType
+- integrationVersion
+
+Metadata in the `AdInfo` overwrites all auto collected metadata.
+
 #### Clean up
 
 At end of app instance lifecycle, the convivaAnalyticsIntegration should be released: