Consolidate legacy docs

README.md

@@ -6,19 +6,24 @@ Adobe Analytics for Audio and Video is an add-on to the base Analytics offering
 
 Starting with v2.2 release, the Video Heartbeat Library (VHL) SDKs are renamed to Media SDKs to support Audio and Video tracking. The Media 2.2 SDK is fully backwards compatible with the VHL 2.x SDK series. The name change does not represent a functional break, simply a change in naming convention.
 
-Starting with v3.0, the SDK uses Media Collection API for tracking. The 3.x SDK is not backward compatible with 2.x SDK series.
-For more information on media collection endpoint, contact your Adobe representative.
+Starting with v3.0, the SDK uses Media Collection API for tracking. The 3.x SDK is not backward compatible with the 2.x SDK.
 
-For additional information regarding Adobe Analytics for Audio and Video, please visit our [documentation](https://docs.adobe.com/content/help/en/media-analytics/using/media-overview.html)
+For additional information regarding Adobe Analytics for Audio and Video, see the [Streaming Media services documentation](https://experienceleague.adobe.com/docs/media-analytics/using/media-overview.html).
 
-### Links for API documentation.
+## SDK documentation and guides
 
-[Android](https://adobe-marketing-cloud.github.io/media-sdks/reference/android/)
+See the [docs/](./docs/) folder for setup guides, migration references, and validation docs organized by SDK version:
 
-[iOS](https://adobe-marketing-cloud.github.io/media-sdks/reference/ios/)
+| Version | Status | Platforms |
+|---|---|---|
+| [3.x](https://experienceleague.adobe.com/docs/media-analytics/using/implementation/overview.html) | Supported (Analytics only) | JavaScript, Chromecast, Roku |
+| [2.x](./docs/2.x/) | End of support Aug 31, 2021 | Android, iOS, JavaScript |
+| [1.x](https://github.com/Adobe-Marketing-Cloud/video-heartbeat/tree/master/docs) | Deprecated | Android, iOS, JavaScript, Apple TV, Chromecast, Roku, TVML |
 
-[Javascript (Browser)](https://adobe-marketing-cloud.github.io/media-sdks/reference/javascript/)
+### Links for API documentation
 
-[Javascript 3.x (Browser)](https://adobe-marketing-cloud.github.io/media-sdks/reference/javascript_3x/index.html)
-
-[Chromecast](https://adobe-marketing-cloud.github.io/media-sdks/reference/chromecast/)
+* [Android](https://adobe-marketing-cloud.github.io/media-sdks/reference/android/)
+* [iOS](https://adobe-marketing-cloud.github.io/media-sdks/reference/ios/)
+* [Javascript (Browser)](https://adobe-marketing-cloud.github.io/media-sdks/reference/javascript/)
+* [Javascript 3.x (Browser)](https://adobe-marketing-cloud.github.io/media-sdks/reference/javascript_3x/index.html)
+* [Chromecast](https://adobe-marketing-cloud.github.io/media-sdks/reference/chromecast/)

docs/2.x/README.md

@@ -0,0 +1,112 @@
+# Media SDK 2.x Setup Overview
+
+> **End of Support:** The Media SDK 2.x reached end of support on August 31, 2021. Migrate to the [Adobe Experience Platform Mobile SDK](https://developer.adobe.com/client-sdks/home/) or the [Edge Network implementation](https://experienceleague.adobe.com/docs/media-analytics/using/implementation/overview.html).
+
+After you download the Media SDK for your video app or player, follow the information in this section to setup and implement the Media SDK.
+
+## General Implementation Guidelines
+
+There are three main SDK components used in tracking with streaming media services:
+
+* Media Heartbeat Config: The `MediaHeartbeatConfig` contains the basic settings for reporting.
+* Media Heartbeat Delegate: The `MediaHeartbeatDelegate` controls playback time and the QoS object.
+* Media Heartbeat: The `MediaHeartbeat` is the primary library containing members and methods.
+
+## Implement the Streaming Media SDK
+
+To setup and use the Streaming Media SDK, complete the following implementation steps:
+
+1. Create a `MediaHeartbeatConfig` instance and set your configuration parameter values.
+
+   |  Variable Name | Description | Required | Default Value |
+   |---|---|:---:|---|
+   | `trackingServer` | Tracking server for media analytics. This is different from your analytics tracking server. | Yes | Empty String |
+   | `channel` | Channel name | No | Empty String |
+   | `ovp` | Name of the online media platform through which content gets distributed | No | Empty String |
+   | `appVersion` | Version of the media player app/SDK | No | Empty String |
+   | `playerName` | Name of the media player in use. For example, "AVPlayer", "HTML5 Player", "My Custom Player" | No | Empty String |
+   | `ssl` | Indicates whether calls should be made over HTTPS | No | `false` |
+   | `debugLogging` | Indicates whether debug logging is enabled | No | `false` |
+
+1. Implement the `MediaHeartbeatDelegate`.
+
+    | Method name | Description | Required |
+    | --- | --- | :---: |
+    | `getQoSObject()` | Returns the `MediaObject` instance that contains the current QoS information. This method will be called multiple times during a playback session. Player implementation must always return the most recently available QoS data. | Yes |
+    | `getCurrentPlaybackTime()` | Returns the current position of the playhead. For VOD tracking, the value is specified in seconds from the beginning of the media item. For live streaming, if the player does not provide information about the content duration, the value can be specified as the number of seconds since midnight UTC of that day. Note: When using progress markers, the content duration is required and the playhead needs to be updated as number of seconds from the beginning of the media item, starting with 0. | Yes |
+
+   > The Quality of Service (QoS) object is optional. If QoS data is available for your player and you wish to track that data, then the following variables are required:
+
+   | Variable name | Description | Required |
+   | --- | --- | :---: |
+   | `bitrate` | The bitrate of media in bits per second. | Yes |
+   | `startupTime` | The start up time of media in milliseconds. | Yes |
+   | `fps` | The frames displayed per second. | Yes |
+   | `droppedFrames` | The number of dropped frames so far. | Yes |
+
+1. Create the `MediaHeartbeat` instance.
+
+   Use the `MediaHeartbeatConfig` and `MediaHeartbeatDelegate` to create the `MediaHeartbeat` instance.
+
+   > Make sure that your `MediaHeartbeat` instance is accessible and does not get deallocated until the end of the session. This instance will be used for all the following media tracking events.
+
+   > `MediaHeartbeat` requires an instance of `AppMeasurement` to send calls to Adobe Analytics.
+
+1. Combine all of the pieces.
+
+   The following sample code utilizes our JavaScript 2.x SDK for an HTML5 video player:
+
+   ```javascript
+   // Create local references to the heartbeat classes
+   var MediaHeartbeat = ADB.va.MediaHeartbeat;
+   var MediaHeartbeatConfig = ADB.va.MediaHeartbeatConfig;
+   var MediaHeartbeatDelegate = ADB.va.MediaHeartbeatDelegate;
+
+   //Media Heartbeat Config
+   var mediaConfig = new MediaHeartbeatConfig();
+   mediaConfig.trackingServer = "[your_namespace].hb.omtrdc.net";
+   mediaConfig.playerName = "HTML5 Basic";
+   mediaConfig.channel = "Video Channel";
+   mediaConfig.debugLogging = true;
+   mediaConfig.appVersion = "2.0";
+   mediaConfig.ssl = false;
+   mediaConfig.ovp = "";
+
+   // Media Heartbeat Delegate
+   var mediaDelegate = new MediaHeartbeatDelegate();
+
+   // Set mediaDelegate CurrentPlaybackTime
+   mediaDelegate.getCurrentPlaybackTime = function() {
+       return video.currentTime;
+   };
+
+   // Set mediaDelegate QoSObject - OPTIONAL
+   mediaDelegate.getQoSObject = function() {
+       return MediaHeartbeat.createQoSObject(video.bitrate,
+                                             video.startuptime,
+                                             video.fps,
+                                             video.droppedframes);
+   }
+   // Create mediaHeartbeat instance
+   this.mediaHeartbeat =
+     new MediaHeartbeat(mediaDelegate, mediaConfig, appMeasurementInstance);
+   ```
+
+## Validate
+
+Media Analytics tracking implementations generate two types of tracking calls:
+
+* Media and ad Start calls are sent directly to the Adobe Analytics (AppMeasurement) server.
+* Heartbeat calls are sent to the Media Analytics (heartbeats) tracking server, processed there, and passed on to the Adobe Analytics server.
+
+**Adobe Analytics (AppMeasurement) server**
+
+For more information about tracking server options, see [`trackingServerSecure`](https://experienceleague.adobe.com/en/docs/analytics/implementation/vars/config-vars/trackingserversecure).
+
+> An RDC tracking server or CNAME resolving to an RDC server is required for the Visitor ID service.
+
+**Media Analytics (Heartbeats) server**
+
+This always has the format "`[your_namespace].hb.omtrdc.net`". The value of "`[your_namespace]`" specifies your company, and is provided by Adobe.
+
+Media tracking works the same across all platforms, desktop and mobile. Audio tracking currently works on mobile platforms. For all tracking calls there are a few key universal variables to be validated.

docs/2.x/android-setup.md

@@ -0,0 +1,121 @@
+# Set up Android
+
+> **End of Support:** The Media SDK 2.x for Android reached end of support on August 31, 2021. Migrate to the [Adobe Experience Platform Mobile SDK](https://developer.adobe.com/client-sdks/home/) or the [Edge Network implementation](https://experienceleague.adobe.com/docs/media-analytics/using/implementation/overview.html). For additional information, see [Media Analytics SDK End-of-Support FAQs](https://experienceleague.adobe.com/docs/media-analytics/using/additional-resources/end-of-support-faqs.html).
+
+Learn how to set up streaming media services for Android devices.
+
+## Prerequisites
+
+* **Obtain valid configuration parameters for the Media SDK**: These parameters can be obtained from an Adobe representative after you set up your analytics account.
+* **Implement ADBMobile for Android in your application**: For more information about the Adobe Mobile SDK documentation, see the [Android SDK 4.x documentation](https://github.com/Adobe-Marketing-Cloud/mobile-services/blob/master/docs/android/overview.md)
+
+* **Provide the following capabilities in your media player:**
+   * *An API to subscribe to player events*: The Media SDK requires that you call a set of simple APIs when events occur in your player.
+   * *An API that provides player information*: This information includes details such as the media name and the play head position.
+
+## SDK Implementation
+
+1. Add your downloaded Media SDK to your project.
+
+    1. Expand the Android zip file (e.g., `MediaSDK-android-v2.*.zip`).
+    1. Verify that the `MediaSDK.jar` file exists in the `libs/` directory.
+
+    1. Add the library to your project.
+
+       **IntelliJ IDEA:**
+
+        1. Right click your project in the **Project navigation** panel.
+        1. Select **Open Module Settings**.
+        1. Under **Project Settings**, select **Libraries**.
+        1. Click **+** to add a new library.
+        1. Select **Java** and navigate to the `MediaSDK.jar` file.
+        1. Select the modules in which you plan to use the mobile library.
+        1. Click **Apply** and then **OK** to close the Module Settings window.
+
+       **Eclipse:**
+
+        1. In the Eclipse IDE, right-click on the project name.
+        1. Click **Build Path** > **Add External Archives**.
+        1. Select `MediaSDK.jar`.
+        1. Click **Open**.
+        1. Right-click the project again, and click **Build Path** > **Configure Build Path**.
+        1. Click the **Order** and **Export** tabs.
+        1. Ensure that the `MediaSDK.jar` file is selected.
+
+1. Import the library.
+
+   ```java
+   import com.adobe.primetime.va.simple.MediaHeartbeat;
+   import com.adobe.primetime.va.simple.MediaHeartbeat.MediaHeartbeatDelegate;
+   import com.adobe.primetime.va.simple.MediaHeartbeatConfig;
+   import com.adobe.primetime.va.simple.MediaObject;
+   ```
+
+1. Create the `MediaHeartbeatConfig` instance.
+
+   Here is a sample `MediaHeartbeatConfig` initialization:
+
+   ```java
+   // Media Heartbeat Initialization
+   config.trackingServer = _<SAMPLE_HEARTBEAT_TRACKING_SERVER>_;
+   config.channel = <SAMPLE_HEARTBEAT_CHANNEL>;
+   config.appVersion = <SAMPLE_HEARTBEAT_SDK_VERSION>;
+   config.ovp =  <SAMPLE_HEARTBEAT_OVP_NAME>;
+   config.playerName = <SAMPLE_PLAYER_NAME>;
+   config.ssl = <true/false>;
+   config.debugLogging = <true/false>;
+   ```
+
+1. Implement the `MediaHeartbeatDelegate` interface.
+
+   ```java
+   public class VideoAnalyticsProvider implements Observer, MediaHeartbeatDelegate{}
+   ```
+
+   ```java
+   // Replace <bitrate>, <startupTime>, <fps>, and
+   // <droppeFrames> with the current playback QoS values.
+   @Override
+   public MediaObject getQoSObject() {
+       return MediaHeartbeat.createQoSObject(<bitrate>,
+                                             <startupTime>,
+                                             <fps>,
+                                             <droppedFrames>);
+   }
+
+   //Replace <currentPlaybackTime> with the video player current playback time
+   @Override
+   public Double getCurrentPlaybackTime() {
+       return <currentPlaybackTime>;
+   }
+   ```
+
+1. Create the `MediaHeartbeat` instance.
+
+   Use the `MediaHeartbeatConfig` instance and the `MediaHeartbeatDelegate` instance to create the `MediaHeartbeat` instance.
+
+   ```java
+   // Replace <MediaHeartbeatDelegate> with your delegate instance
+   MediaHeartbeat _heartbeat =
+     new MediaHeartbeat(<MediaHeartbeatDelegate>, config);
+   ```
+
+   > Make sure that your `MediaHeartbeat` instance is accessible and *does not get deallocated until the end of the session*. This instance is used for all of the following tracking events.
+
+## Adding App Permissions
+
+Your app using the Media SDK requires the following permissions to send data in tracking calls:
+
+* `INTERNET`
+* `ACCESS_NETWORK_STATE`
+
+To add these permissions, add the following lines to your `AndroidManifest.xml` file in the application project directory:
+
+* `<uses-permission android:name="android.permission.INTERNET" />`
+* `<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />`
+
+## Migrating from version 1.x to 2.x in Android
+
+In versions 2.x, all of the public methods are consolidated into the `com.adobe.primetime.va.simple.MediaHeartbeat` class to make it easier on developers. Also, all configs are now consolidated into the `com.adobe.primetime.va.simple.MediaHeartbeatConfig` class.
+
+For information about migrating from 1.x to 2.x, see the [1.x to 2.x migration guide](./migration/1x-to-2x.md).