Merge pull request #85 from Adobe-Marketing-Cloud/release-js-3.1.0

Media SDK JS 3.1.0 Release

sdks/js/3.x/ReleaseNotes.md

@@ -1,8 +1,12 @@
 # Release Notes for JavaScript Media SDK 3.x
 
+## 3.1.0 (January 6, 2025)
+- Added feature to override `playerName` configuration per tracker instance.
+- Added public constants for configuration keys.
+
 ## 3.0.2 (March 26, 2021)
 
-- Fix "Content-Type" HTTP header in Media Collection API requests. 
+- Fix "Content-Type" HTTP header in Media Collection API requests.
 
 ## 3.0.1 (October 8, 2020)
 

sdks/js/3.x/docs/APIReference.md

@@ -6,10 +6,6 @@
 
 #### configure
 
-> **_Note:_** 
-This method is for standalone Media SDK JavaScript v3.x.  
-For Media SDK Javascript v3.x with Tags extension, setup the configuration via Data Collection UI (Tags UI).
-
 Configures MediaSDK for tracking. This method should be called once before creating any tracker instances in a page.
 
 **Syntax**
@@ -19,7 +15,7 @@ ADB.Media.configure(mediaConfig, appMeasurement);
 ```
 
 |Variable Name | Type | Description |
-|---|---|---
+|---|---|---|
 | mediaConfig | [ADB.MediaConfig](#ADB.MediaConfig) | Valid media configuration |
 | appMeasurement | object | AppMeasurement instance |
 
@@ -44,21 +40,31 @@ Creates an instance of media to track the playback session. Returns `null` is ca
 **Syntax**
 
 ```javascript
-ADB.Media.getInstance()
+ADB.Media.getInstance(trackerConfig)
 ```
 
+| Variable Name | Type | Required | Description |
+| :--- | :--- | :---: |
+| `trackerConfig` | [Tracker configuration](#tracker-config) | No | Tracker configuration object. |
+
 **Example**
 
 ```javascript
 var tracker = ADB.Media.getInstance();
 ```
 
+To override channel or playerName per tracker instance, pass the override values in the tracker configuration object.
+
+**Example with tracker configuration**
 ```javascript
-// create an instance with custom channel example
-// this overrides the channel which was set during the configuration
-var tracker = ADB.Media.getInstance({"media.channel":"custom_channel_name"})
+const trackerConfig = {
+  [Media.TrackerConfig.Channel]: "custom_channel_name",
+  [Media.TrackerConfig.PlayerName]: "custom_player_name",
+}
+this._mediaTracker = Media.getInstance(trackerConfig);
 ```
 
+
 #### createMediaObject
 
 Creates an object containing media information. Returns empty object if invalid parameters are passed.
@@ -369,9 +375,9 @@ ADB.Media.trackEvent(event, info, contextData);
   // Standard metadata keys provided by adobe.
   adMetadata[ADB.Media.AdMetadataKeys.Advertiser]  ="Sample Advertiser";
   adMetadata[ADB.Media.AdMetadataKeys.CampaignId] = "Sample Campaign";
-  // Custom metadata keys  
+  // Custom metadata keys
   adMetadata["affiliate"] = "Sample affiliate";
-  
+
   tracker.trackEvent(ADB.Media.Event.AdStart, adObject, adMetadata);
 
 // AdComplete
@@ -439,8 +445,7 @@ ADB.Media.trackEvent(event, info, contextData);
 
 #### updatePlayhead
 
-Provide current media playhead to media tracker. For accurate tracking, call this method multiple times when the playhead changes. If the player does not notify playhead changes, call this method once every second with the most recent playhead.
-
+Provide current media playhead to media tracker. For accurate tracking, call this method whenever playhead changes during playback.
 
 **Syntax**
 
@@ -450,12 +455,18 @@ ADB.Media.updatePlayhead(time);
 
 | Variable Name | Description |
 | :--- | :--- |
-| `time` | Current playhead in seconds. <br /> For video-on-demand \(VOD\), the value is specified in seconds from the beginning of the media item. <br /> 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. <br /> 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. |
+| `time` | Current playhead in seconds.  <br /> For video-on-demand \(VOD\), the value is specified in seconds from the beginning of the media item. <br /> 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.  <br /> 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.|
 
 **Example**
 
 ```javascript
 tracker.updatePlayhead(13.3);
+
+// For live streams
+var UTCTimeInSeconds = Math.floor(Date.now() / 1000)
+var timeFromMidnightInSecond = UTCTimeInSeconds % 86400
+
+tracker.updatePlayhead(timeFromMidnightInSecond);
 ```
 
 #### updateQoEObject
@@ -498,6 +509,17 @@ tracker.destroy();
 
 ### Constants
 
+#### Tracker config
+
+This defines the configuration keys that can be set per tracker instance.
+
+```javascript
+ADB.Media.TrackerConfig = {
+  Channel: "media.channel",
+  PlayerName: "media.playerName"
+}
+```
+
 #### Media type
 
 This defines the type of a media that is currently tracked.
@@ -649,4 +671,4 @@ tracker.trackSessionStart(mediaObject);
 | `playerName` | No | Name of the media player in use  |
 | `appVersion` | No | Type the version of the media player application/SDK |
 | `debugLogging` | No | Enables or disables Media SDK logs (Default value : `false`)|
-| `ssl` | No | Sends pings over SSL (Default value : `true`)|
+| `ssl` | No | Sends pings over SSL (Default value : `true`)|

sdks/js/3.x/samples/MediaAnalyticsSample/script/app/analytics/video.analytics.provider.js

@@ -27,16 +27,16 @@
     });
 
     //Enable optin service for privacy management.
-    // var preOptInApprovalsConfig = {}; 
-    // preOptInApprovalsConfig[adobe.OptInCategories.ANALYTICS] = true; 
-    // preOptInApprovalsConfig[adobe.OptInCategories.ECID] = false; 
-    // preOptInApprovalsConfig[adobe.OptInCategories.MEDIA_ANALYTICS] = true; 
-        
-    // var visitor = Visitor.getInstance(Configuration.VISITOR.MARKETING_CLOUD_ORG_ID, { 
+    // var preOptInApprovalsConfig = {};
+    // preOptInApprovalsConfig[adobe.OptInCategories.ANALYTICS] = true;
+    // preOptInApprovalsConfig[adobe.OptInCategories.ECID] = false;
+    // preOptInApprovalsConfig[adobe.OptInCategories.MEDIA_ANALYTICS] = true;
+
+    // var visitor = Visitor.getInstance(Configuration.VISITOR.MARKETING_CLOUD_ORG_ID, {
     //     "doesOptInApply": true,
-    //     "preOptInApprovals": preOptInApprovalsConfig, 
-    //     "previousPermissions": preOptInApprovalsConfig, 
-    //     "isOptInStorageEnabled": true 
+    //     "preOptInApprovals": preOptInApprovalsConfig,
+    //     "previousPermissions": preOptInApprovalsConfig,
+    //     "isOptInStorageEnabled": true
     // });
 
     // Set-up the AppMeasurement component.
@@ -50,11 +50,11 @@
     var mediaConfig = new MediaConfig();
     mediaConfig.trackingServer = Configuration.HEARTBEAT.TRACKING_SERVER;
     mediaConfig.playerName = Configuration.PLAYER.NAME;
-    mediaConfig.channel = Configuration.HEARTBEAT.CHANNEL;    
+    mediaConfig.channel = Configuration.HEARTBEAT.CHANNEL;
     mediaConfig.appVersion = Configuration.HEARTBEAT.SDK;
     mediaConfig.ssl = true;
     mediaConfig.debugLogging = true;
-    
+
 
     Media.configure(mediaConfig, appMeasurement);
 
@@ -64,8 +64,11 @@
         }
         this._player = player;
 
-
-        this._mediaTracker = Media.getInstance();
+        const trackerConfig = {
+            [Media.TrackerConfig.Channel]: "custom_channel_name",
+            [Media.TrackerConfig.PlayerName]: "custom_player_name",
+        }
+        this._mediaTracker = Media.getInstance(trackerConfig);
 
         this._installEventListeners();
     }
@@ -76,7 +79,7 @@
             this._mediaTracker = null;
         }
 
-        if (this._player) {            
+        if (this._player) {
             this._player = null;
             this._uninstallEventListeners();
         }
@@ -100,10 +103,10 @@
             tvStation: "Sample TV station",
             programmer: "Sample programmer"
         };
-        
-        // Set standard Video Metadata        
+
+        // Set standard Video Metadata
         contextData[Media.VideoMetadataKeys.Episode] = "Sample Episode";
-        contextData[Media.VideoMetadataKeys.Show] = "Sample Show";        
+        contextData[Media.VideoMetadataKeys.Show] = "Sample Show";
 
         this._mediaTracker.trackSessionStart(mediaInfo, contextData);
     };
@@ -159,10 +162,10 @@
             campaign: "Sample ad campaign"
         };
 
-        // Set standard Ad Metadata        
+        // Set standard Ad Metadata
         adContextData[Media.AdMetadataKeys.Advertiser] = "Sample Advertiser";
         adContextData[Media.AdMetadataKeys.CampaignId] = "Sample Campaign";
-        
+
         this._mediaTracker.trackEvent(Media.Event.AdBreakStart, adBreakInfo);
         this._mediaTracker.trackEvent(Media.Event.AdStart, adInfo, adContextData);
     };
@@ -219,7 +222,7 @@
 
         this._mediaTracker.trackEvent(event, info);
     };
-    
+
 
     VideoAnalyticsProvider.prototype._onFullscreenChange = function () {
         var fullscreen = this._player.isFullscreen()
@@ -230,7 +233,7 @@
 
         this._mediaTracker.trackEvent(event, info);
     };
-    
+
     /////////
     // Private helper functions
     /////////
@@ -279,4 +282,4 @@
 
     // Export symbols.
     window.VideoAnalyticsProvider = VideoAnalyticsProvider;
-})();
+})();