Merge pull request #76 from bitmovin/ssai-docu-and-changelog

Add changelog and basic documentation for SSAI tracking

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

README.md

@@ -65,7 +65,7 @@ For more information about permissions and collected network types please look a
 
 The following example create a ConvivaAnalyticsIntegration object and attaches at Bitmovin Native SDK to it
 
-#### Basic Conviva Reporting
+### Basic Conviva Reporting
 
 ```java
 // Create your ConvivaConfig object
@@ -83,14 +83,14 @@ Source source = Source.create(sourceConfig);
 bitmovinPlayer.load(source);
 ```
 
-#### Optional Configuration Parameters
+### Optional Configuration Parameters
 ```java
 convivaConfig.setGatewayUrl("YOUR_DEBUG_GATEWAY_URL");
 convivaConfig.setDebugLoggingEnabled(true);
 
 ```
 
-#### Content Metadata handling
+### Content Metadata handling
 
 If you want to override some content metadata attributes or track additional custom or standard tags you can do so by adding the following:
 
@@ -116,15 +116,15 @@ convivaAnalyticsIntegration.updateContentMetadata(metadata);
 
 Those values will be cleaned up after the session is closed.
 
-#### Consecutive playback
+### Consecutive playback
 
 If you want to use the same player instance for multiple playback, just load a new source with player.load(…). The integration will close the active session.
 
 ```java
 player.load(…);
 ```
 
-#### Background handling
+### Background handling
 
 If your app stops playback when entering background conviva suggests to end the active session. Since the integration can't know if your app supports background playback this can't be done automatically.
 
@@ -133,7 +133,40 @@ 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.
 
-#### Clean up
+### 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
+- ConvivaSdkConstants.VIEWER_ID
+- ConvivaSdkConstants.PLAYER_NAME
+- streamType
+- integrationVersion
+
+Metadata in the `AdInfo` overwrites all auto collected metadata.
+
+### Clean up
 
 At end of app instance lifecycle, the convivaAnalyticsIntegration should be released: