Uplynk Ping API

connectors/uplynk/src/main/java/com/theoplayer/android/connector/uplynk/UplynkListener.kt

@@ -1,6 +1,8 @@
 package com.theoplayer.android.connector.uplynk
 
+import com.theoplayer.android.connector.uplynk.internal.network.PingResponse
 import com.theoplayer.android.connector.uplynk.network.AssetInfoResponse
+import com.theoplayer.android.connector.uplynk.network.PreplayLiveResponse
 import com.theoplayer.android.connector.uplynk.network.PreplayResponse
 
 /**
@@ -18,6 +20,15 @@ interface UplynkListener {
      */
     fun onPreplayResponse(response: PreplayResponse) {}
 
+    /**
+     * Called when a preplay response is received from Uplynk for live channel or an event.
+     *
+     * For more details, refer to the [Preplay API (Version 2) Documentation](https://docs.edgecast.com/video/index.html#Develop/Preplayv2.htm).
+     *
+     * @param response the `PreplayLiveResponse` object containing information relevant to the preplay request.
+     */
+    fun onPreplayLiveResponse(response: PreplayLiveResponse){}
+
     /**
      * Called when a preplay response is received from Uplynk and failed to be parsed
      *
@@ -40,4 +51,13 @@ interface UplynkListener {
      * @param exception the `Exception` occurred during the request
      */
     fun onAssetInfoFailure(exception: Exception) {}
+
+    /**
+     * Called when a ping response is received from Uplynk.
+     *
+     * For more details, refer to the [Ping API Documentation](https://docs.edgecast.com/video/#Develop/Pingv2.htm).
+     *
+     * @param exception the `Exception` occurred during the request
+     */
+    fun onPingResponse(pingResponse: PingResponse) {}
 }

connectors/uplynk/src/main/java/com/theoplayer/android/connector/uplynk/UplynkSsaiDescription.kt

@@ -14,8 +14,10 @@ data class UplynkSsaiDescription(
     val userId: String? = null,
     val contentProtected: Boolean = false,
     val preplayParameters: LinkedHashMap<String, String> = linkedMapOf(),
-    val assetInfo: Boolean = false
-): CustomSsaiDescription() {
+    val assetInfo: Boolean = false,
+    val assetType: UplynkAssetType = UplynkAssetType.ASSET,
+    val pingConfiguration: UplynkPingConfiguration = UplynkPingConfiguration()
+) : CustomSsaiDescription() {
 
     override val customIntegration: String
         get() = UplynkConnector.INTEGRATION_ID
@@ -25,6 +27,7 @@ data class UplynkSsaiDescription(
      */
     class Builder {
         private var prefix: String? = null
+
         /**
          * Sets the prefix to use for Uplynk Media Platform Preplay API and Asset Info API requests.
          *
@@ -35,6 +38,7 @@ data class UplynkSsaiDescription(
         fun prefix(prefix: String) = apply { this.prefix = prefix }
 
         private var assetIds = emptyList<String>()
+
         /**
          * Sets a list of asset IDs for Uplynk Media Platform Preplay API.
          *
@@ -43,6 +47,7 @@ data class UplynkSsaiDescription(
         fun assetIds(ids: List<String>) = apply { this.assetIds = ids }
 
         private var externalIds: List<String> = emptyList<String>()
+
         /**
          * Sets a list of external IDs for Uplynk Media Platform Preplay API.
          * If [assetIds] have at least one value this property is ignored and could be empty
@@ -52,6 +57,7 @@ data class UplynkSsaiDescription(
         fun externalIds(ids: List<String>) = apply { this.externalIds = ids }
 
         private var userId: String? = null
+
         /**
          * Sets a User ID for Uplynk Media Platform Preplay API.
          * If [assetIds] have at least one value this property is ignored and could be empty
@@ -69,6 +75,7 @@ data class UplynkSsaiDescription(
         fun contentProtected(contentProtected: Boolean) = apply { this.contentProtected = contentProtected }
 
         private var preplayParameters: LinkedHashMap<String, String> = LinkedHashMap()
+
         /**
          * Sets the parameters.
          *
@@ -81,13 +88,32 @@ data class UplynkSsaiDescription(
          * linkedMapOf("ad" to "exampleAdServer")
          * ```
          */
-        fun preplayParameters(parameters: LinkedHashMap<String, String>) = apply { this.preplayParameters = parameters }
+        fun preplayParameters(parameters: LinkedHashMap<String, String>) =
+            apply { this.preplayParameters = parameters }
 
         private var assetInfo: Boolean = false
+
         /**
          * Sets flag to request asset info.
          */
         fun assetInfo(shouldRequest: Boolean) = apply { this.assetInfo = shouldRequest }
+
+        private var assetType: UplynkAssetType = UplynkAssetType.ASSET
+
+        /**
+         * Sets the asset type.
+         *
+         *   - For all possibilities, see {@link UplynkAssetType}.
+         *
+         *   @param value The Verizon Media asset type. (<b>NonNull</b>)
+         *
+         */
+        fun assetType(value: UplynkAssetType) = apply { this.assetType = value }
+
+        private var pingConfiguration: UplynkPingConfiguration = UplynkPingConfiguration()
+
+        fun pingConfiguration(value: UplynkPingConfiguration) = apply { this.pingConfiguration = value }
+
         /**
          * Builds the [UplynkSsaiDescription].
          */
@@ -98,6 +124,73 @@ data class UplynkSsaiDescription(
             userId = userId,
             contentProtected = contentProtected,
             preplayParameters = preplayParameters,
-            assetInfo = assetInfo)
+            assetInfo = assetInfo,
+            assetType = assetType,
+            pingConfiguration = pingConfiguration
+        )
+    }
+}
+
+/**
+ * Describes the configuration of Verizon Media Ping features.
+ *
+ */
+@Serializable
+data class UplynkPingConfiguration(
+    /**
+     * Whether to increase the accuracy of ad events by passing the current playback time in Ping requests.
+     *
+     * @remark Only available when {@link UplynkSsaiDescription.assetType} is `'asset'`.
+     *
+     * @defaultValue `false`
+     *
+     */
+    val adImpressions: Boolean = false,
+
+    /**
+     * Whether to enable FreeWheel's Video View by Callback feature to send content impressions to the FreeWheel server.
+     *
+     * @remarks Only available when {@link UplynkSsaiDescription.assetType} is `'asset'`.
+     *
+     * @defaultValue `false`
+     */
+    val freeWheelVideoViews: Boolean = false,
+
+    /**
+     * Whether to request information about upcoming ad breaks in the Ping responses.
+     *
+     * @defaultValue false.
+     */
+    val linearAdData: Boolean = false) {
+    class Builder {
+        private var adImpressions: Boolean = false
+        fun adImpressions(value: Boolean) = apply { adImpressions = value }
+        private var freeWheelVideoViews: Boolean = false
+        fun freeWheelVideoViews(value: Boolean) = apply { freeWheelVideoViews = value }
+        private var linearAdData: Boolean = false
+        fun linearAdData(value: Boolean) = apply { linearAdData = value }
+
+        fun build() = UplynkPingConfiguration(
+            adImpressions = adImpressions,
+            freeWheelVideoViews = freeWheelVideoViews,
+            linearAdData = linearAdData
+        )
     }
 }
+
+enum class UplynkAssetType {
+    /**
+     * A Video-on-demand content asset.
+     */
+    ASSET,
+
+    /**
+     * A Live content channel.
+     */
+    CHANNEL,
+
+    /**
+     * A Live event.
+     */
+    EVENT;
+}

connectors/uplynk/src/main/java/com/theoplayer/android/connector/uplynk/internal/PingScheduler.kt

@@ -0,0 +1,68 @@
+package com.theoplayer.android.connector.uplynk.internal
+
+import com.theoplayer.android.connector.uplynk.internal.network.UplynkApi
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
+import kotlin.time.Duration
+import kotlin.time.DurationUnit
+import kotlin.time.toDuration
+
+internal class PingScheduler(
+    private val uplynkApi: UplynkApi,
+    private val uplynkDescriptionConverter: UplynkSsaiDescriptionConverter,
+    private val prefix: String,
+    private val sessionId: String,
+    private val eventDispatcher: UplynkEventDispatcher,
+    private val adScheduler: UplynkAdScheduler
+) {
+    private val NEGATIVE_TIME = (-1).toDuration(DurationUnit.SECONDS)
+
+    private var nextRequestTime: Duration = NEGATIVE_TIME
+    private var seekStart: Duration = NEGATIVE_TIME
+    private val job = SupervisorJob()
+    private val scope = CoroutineScope(Dispatchers.IO + job)
+
+    fun onTimeUpdate(time: Duration) {
+        if (nextRequestTime.isPositive() && time > nextRequestTime) {
+            nextRequestTime = NEGATIVE_TIME
+            performPing(uplynkDescriptionConverter.buildPingUrl(prefix, sessionId, time))
+        }
+    }
+
+    fun onStart() =
+        performPing(uplynkDescriptionConverter.buildStartPingUrl(prefix, sessionId, Duration.ZERO))
+
+
+    fun onSeeking(time: Duration) {
+        if (seekStart.isNegative()) {
+            seekStart = time
+        }
+    }
+
+    fun onSeeked(time: Duration) {
+        performPing(
+            uplynkDescriptionConverter.buildSeekedPingUrl(
+                prefix,
+                sessionId,
+                time,
+                seekStart
+            )
+        )
+        seekStart = NEGATIVE_TIME
+    }
+
+    fun destroy() {
+        job.cancel()
+    }
+
+    private fun performPing(url: String) = scope.launch {
+        val pingResponse = uplynkApi.ping(url)
+        nextRequestTime = pingResponse.nextTime
+        eventDispatcher.dispatchPingEvent(pingResponse)
+        if (pingResponse.ads != null) {
+            adScheduler.add(pingResponse.ads)
+        }
+    }
+}

connectors/uplynk/src/main/java/com/theoplayer/android/connector/uplynk/internal/UplynkAdIntegration.kt

@@ -8,7 +8,10 @@ import com.theoplayer.android.api.player.Player
 import com.theoplayer.android.api.source.SourceDescription
 import com.theoplayer.android.api.source.drm.DRMConfiguration
 import com.theoplayer.android.api.source.drm.KeySystemConfiguration
+import com.theoplayer.android.connector.uplynk.UplynkAssetType
 import com.theoplayer.android.connector.uplynk.UplynkSsaiDescription
+import com.theoplayer.android.connector.uplynk.internal.network.PreplayInternalLiveResponse
+import com.theoplayer.android.connector.uplynk.internal.network.PreplayInternalResponse
 import com.theoplayer.android.connector.uplynk.internal.network.UplynkApi
 import kotlin.time.DurationUnit
 import kotlin.time.toDuration
@@ -21,29 +24,44 @@ internal class UplynkAdIntegration(
     private val uplynkDescriptionConverter: UplynkSsaiDescriptionConverter,
     private val uplynkApi: UplynkApi
 ) : ServerSideAdIntegrationHandler {
+    private var pingScheduler: PingScheduler? = null
     private var adScheduler: UplynkAdScheduler? = null
     private val player: Player
         get() = theoplayerView.player
 
     init {
         player.addEventListener(PlayerEventTypes.TIMEUPDATE) {
-            adScheduler?.onTimeUpdate(it.currentTime.toDuration(DurationUnit.SECONDS))
+            val time = it.currentTime.toDuration(DurationUnit.SECONDS)
+            adScheduler?.onTimeUpdate(time)
+            pingScheduler?.onTimeUpdate(time)
+        }
+
+        player.addEventListener(PlayerEventTypes.SEEKING) {
+            pingScheduler?.onSeeking(it.currentTime.toDuration(DurationUnit.SECONDS))
+        }
+
+        player.addEventListener(PlayerEventTypes.SEEKED) {
+            pingScheduler?.onSeeked(it.currentTime.toDuration(DurationUnit.SECONDS))
         }
     }
 
     override suspend fun resetSource() {
         adScheduler = null
+        pingScheduler?.destroy()
     }
 
     override suspend fun setSource(source: SourceDescription): SourceDescription {
         adScheduler = null
+        pingScheduler?.destroy()
 
         val uplynkSource = source.sources.singleOrNull { it.ssai is UplynkSsaiDescription }
         val ssaiDescription = uplynkSource?.ssai as? UplynkSsaiDescription ?: return source
 
-        val preplayUrl = uplynkDescriptionConverter.buildPreplayUrl(ssaiDescription)
-        val internalResponse = uplynkApi.preplay(preplayUrl)
-        val minimalResponse = internalResponse.parseMinimalResponse()
+        val minimalResponse = if (ssaiDescription.assetType == UplynkAssetType.ASSET) {
+            requestVod(ssaiDescription).parseMinimalResponse()
+        } else {
+            requestLive(ssaiDescription).parseMinimalResponse()
+        }
 
         var newUplynkSource = uplynkSource.replaceSrc(minimalResponse.playURL)
 
@@ -62,14 +80,15 @@ internal class UplynkAdIntegration(
             add(0, newUplynkSource)
         })
 
-        try {
-            val externalResponse = internalResponse.parseExternalResponse()
-            eventDispatcher.dispatchPreplayEvents(externalResponse)
-            adScheduler = UplynkAdScheduler(externalResponse.ads.breaks, AdHandler(controller))
-        } catch (e: Exception) {
-            eventDispatcher.dispatchPreplayFailure(e)
-            controller.error(e)
-        }
+        pingScheduler = PingScheduler(
+            uplynkApi,
+            uplynkDescriptionConverter,
+            minimalResponse.prefix,
+            minimalResponse.sid,
+            eventDispatcher,
+            adScheduler!!
+        )
+        pingScheduler?.onStart()
 
         if (ssaiDescription.assetInfo) {
             uplynkDescriptionConverter
@@ -88,4 +107,36 @@ internal class UplynkAdIntegration(
 
         return newSource
     }
+
+    private suspend fun requestLive(ssaiDescription: UplynkSsaiDescription): PreplayInternalLiveResponse {
+        return uplynkDescriptionConverter
+            .buildPreplayLiveUrl(ssaiDescription)
+            .let { uplynkApi.preplayLive(it) }
+            .also {
+                try {
+                    val response = it.parseExternalResponse()
+                    eventDispatcher.dispatchPreplayLiveEvents(response)
+                    adScheduler = UplynkAdScheduler(listOf(), AdHandler(controller))
+                } catch (e: Exception) {
+                    eventDispatcher.dispatchPreplayFailure(e)
+                    controller.error(e)
+                }
+            }
+    }
+
+    private suspend fun requestVod(ssaiDescription: UplynkSsaiDescription): PreplayInternalResponse {
+        return uplynkDescriptionConverter
+            .buildPreplayVodUrl(ssaiDescription)
+            .let { uplynkApi.preplayVod(it) }
+            .also {
+                try {
+                    val response = it.parseExternalResponse()
+                    eventDispatcher.dispatchPreplayEvents(response)
+                    adScheduler = UplynkAdScheduler(response.ads.breaks, AdHandler(controller))
+                } catch (e: Exception) {
+                    eventDispatcher.dispatchPreplayFailure(e)
+                    controller.error(e)
+                }
+            }
+    }
 }