Precision API User Guide

Conviva Precision allows video publishers to maximize the value of their multi CDN/multi resource video delivery strategy; improving QoE, adding resilience to their service, while managing CDN costs. Conviva Precision is powered by a flexible business policies engine together with real time QoE measured at every viewer device. It provides a Video AI API to recommend the best CDN or Resource to deliver Video for each and every viewer. A Resource can be just a CDN, a CDN from a given Origin, a POP or Edge from an Internal CDN, etc.

Use the Precision API Reference to view detailed API information.

Prerequisites

Before getting started with Precision, ensure these requirements are met.

• Conviva Conviva VSI is implemented on at least one player. Precision's recommendation service API is built on the data that is collected through the VSI integration.
• Multiple CDN/Multiple Delivery Resource architecture.

Benefits/Use Cases of Precision

The benefits of optimizing a multi-CDN/multi-resource strategy with Conviva Precision include:

• Maximize Service Uptime: Fall back to an alternate CDN when and where the primary is underperforming.
• Minimize CDN Costs: Send more traffic to the cheaper CDN without compromising QoE. Easily switch traffic during or after contract negotiations.
• Optimize Viewer QoE: Use each CDN where and when it performs the best, within constraints defined by the business policies.
• Self Healing and Generic Resource Optimization: Define delivery resources based on stream URL path patterns and configure Precision to choose the best performing resource for each and every viewer based on encoding policy, redundant resource, and multiple CDNs.
• Guarantee QoE during High-Concurrency Events: Balance traffic based on how well CDNs handle peak load.
• From Single to Multi-CDN Risk Free: Introduce new CDNs and run POCs without risking QoE.
• Internal CDN Offload: Use a third party CDN only when traffic spikes to a level above the internal CDN capacity or when the internal CDN experiences performance problems.

Self Healing and Generic Resource Optimization

Conviva Precision allows video publishers to further maximize the value of their multi-CDN/multi-resource video delivery strategy by allowing optimization of generic resources, which can be a CDN serving content from a given (redundant) origin. In this case, Precision can be configured to optimize the selection of the CDN along with the best origin server (for example, a live channel which is in Origin 1 will be served through CDN A) based on business policies, QoE, and resource traffic shares.

Resource Mapping

With redundant resource origins available to multiple CDNs, resource mappings based on stream URL can be used to indicate the CDN and resource origin (e.g. data center):

• https://CDN1-DC1-LIVE-HLS.example.com/pathToContent.m3u8
  • Path Pattern: CDN1-DC1-LIVE-HLS
  • Resource: CDN1 DC1 LIVE HLS
  • CDN: CDN1
• https://CDN1-DC2-LIVE-HLS.example.com/pathToContent.m3u8
  • Path Pattern: CDN1-DC2-LIVE-HLS
  • Resource: CDN1 DC2 LIVE HLS
  • CDN: CDN1
• https://CDN2-DC1-LIVE-HLS.example.com/pathToContent.m3u8
  • Path Pattern: CDN2-DC1-LIVE-HLS
  • Resource: CDN2 DC1 LIVE HLS
  • CDN: CDN2
• https://CDN2-DC2-LIVE-HLS.example.com/pathToContent.m3u8
  • Path Pattern: CDN2-DC2-LIVE-HLS
  • Resource: CDN2 DC2 LIVE HLS
  • CDN: CDN2

VRL Sample Request for Multi CDN and Resource Origin Optimization

In the resource selection process, the candidate resources (c3.r1 to c3.r4) are shown above. These are the resources which can serve the asset being requested. Precision selects the best resource based on business policies and QoE. Traffic shares can also be enforced per resource to make sure Precision takes resource access capacity into account. This enables you to also configure optimization for situations where a resource is not selected based only on traffic or QoE comparison, ensuring the most optimized available resource and CDN combination is used.

Example VRL Request

1
https://vrl.m.conviva.com/?c3.vr=2&c3.rt=p&c3.im=p&c3.um=i&c3.ck=2d140fe495d9f8e824faa884f68ddb8141a42ddb&c3.ip=68.71.35.162&c3.os=WIN&c3.vi=ViewerID&c3.at=LIVE_EVENT&c3.vp=l&c3.r1=CDN1-DC1-LIVE-HLS&c3.r2=CDN1-DC2-LIVE-HLS&c3.r3=CDN2-DC1-LIVE-HLS&c3.r4=CDN2-DC2-LIVE-HLS

Precision Policies

Conviva policies govern the CDN switching decisions to optimize QoE with CDN cost management. Policy constraints enable different policy models for the most optimized switching methods:

• Distribution Policies

  • Restricting predefined traffic shares between resources so only the best CDN in a delivery pattern gets more traffic there (quality driven).
  • Allowing custom traffic shares, which may be ignored when custom QoE deterioration delta is reached (constrained optimization).

• Throttling Policies

  • Limit traffic on a specific resource to a custom throttling threshold.

• Optimization Logic
• Using only the most recent 5 minutes of data, where last minute weighs more than the minute before, and so on. (Failure Detection Module).
• Evaluating different KPIs in sequence and at different thresholds. (Failure Detection Module).
• Using more historical data, where more recent data weights more. (Baseline Optimization).
• Optimizing for a KPI which can be composed of single or combined QoE metrics. (Baseline Optimization).

High-Level Integration Flow

An example of a high-level integration flow shows the VRL request and response from the CMS. The exact structure of a VRL message and corresponding response from Conviva vary based on the deployed services.

1. Player requests to the CMS a stream URL to playback.
2. VRL (Virtual Resource Locator) request contains parameters to enable respective policies (for example, Client IP, Stream Protocol, Live or VOD, custom tags). VRL is composed in the CMS and sent to Conviva. VRL Specification must be followed.
3. VRL Response is a function of Business Policies and the Real Time and recent historical QoE data. VRL response can be a priority list of resources / CDNs, or stream URL directly. A 500ms timeout should be set, falling back to a default valid URL returned by CMS to Player.
4. Stream URL passed to the Player. More than one URL can be passed to the player in case a fallback logic is available in the player.
5. 1. Playback starts from chosen CDN or Resource, the respective Conviva VSI monitoring session is created.
   2. The Conviva VSI session started and correlated to the Precision Decision by means of a Request Identifier (c3.ri) which is returned in the VRL response and appended to the stream URL as a query parameter (recommended) or Client IP address (alternative).

This illustration compares the resource selection process with and without VRL requests/replies.

If there are redundant resource origins, Precision can also be configured to optimize the selection of the CDN along with the best resource origin (data center) based on business policies, QoE, and resource traffic shares.

VRL Protocol

In the resource selection process, the CMS (the publisher) decides whether to use the ‘Priority List’ information provided by Precision for decision making or advisory data. In a typical deployment, the highest priority resource (and optionally the recommended set of bitrates) is propagated to each viewing device without modification and Conviva Precision acts as an automated real-time decision-making service. Alternatively, the CMS can utilize the information provided through VRL as part of its own resource selection logic and/or manifest generation service – in this mode, Conviva is providing “advice” but the CMS/publisher maintains the decision-making control.

VRL Request

The VRL uses query parameters to encode all of the information that Conviva Precision needs to select session parameters (resource and/or bitrates). Some query parameters are required; some are (strongly) recommended; others are optional based on availability. Required, mandatory parameters are explicitly called out in their definitions.

VRL Format

This is the format for a typical VRL. Use this format whenever the VRL includes Conviva-specific query parameters:

VRL Size

A VRL should be no longer than 2,048 bytes. A longer VRL might be truncated to the first 2,048 bytes. Therefore, all required parameters must be ordered in the query-string ahead of other parameters in case of truncation.

VRL Path

VRL is used to communicate between two headend systems. No player streamer is involved and the response is a standard JSON, thus any file extension can be used. However, for simplicity, we recommend you always use the literal value: “/a.mp4”

VRL Query Parameters

All Conviva-specific information in the VRL is encoded in URL query parameters. Here are the rules associated with forming the query parameters:

• Each query parameter defines a key-value pair.
• The key is a pre-defined string in the table below.
• The value is either customer-specific or a pre-defined enumerated value.
• All query parameter values must be properly URL encoded.
• Any non-ASCII query parameter values must use UTF-8 encoding.
• Each query parameter key must be of the form PFX.KEY.
• Default value for PFX is c3.
• In the rare case where your CDN URL’s own query parameters conflict with ‘c3.’ you can override PFX with another prefix defined by the optional special query string key CONVIVA_PREFIX. The examples that follow use PFX = c3.
• For custom key-value pairs, use the form PFX.ext.key.
• Omitting required parameters will result in an error.

CDN Selection

1
https://vrl.m.conviva.com/a.ism/Manifest?c3.vr=2&c3.rt=p&c3.im=p&c3.um=d&c3.ck=2d140fe495d9f8e824faa884f68ddb8141a42ddb&c3.vp=l&c3.ip=90.216.134.196&c3.r1=CDN_A&c3.r2=CDN_B&c3.r3=CDN_C&c3.vi=12345&c3.at=ON_DEMAND&c3.ext.DEVICE_TYPE=MOBILE&c3.ext.PLATFORM=IOS&c3.ext.SERVICE_KEY=432213&c3.ext.CONTENT_ID=123

Resource Optimization

1
https://vrl.m.conviva.com/?c3.vr=2&c3.rt=p&c3.im=p&c3.um=i&c3.ck=2d140fe495d9f8e824faa884f68ddb8141a42ddb&c3.ip=68.71.35.162&c3.os=WIN&c3.vi=ViewerID&c3.at=LIVE_EVENT&c3.vp=l&c3.r1=CDN1-DC1-LIVE-HLS&c3.r2=CDN1-DC2-LIVE-HLS&c3.r3=CDN2-DC1-LIVE-HLS&c3.r4=CDN2-DC2-LIVE-HLS

VRL Query Parameters

VRL Response

Important: All CDN Resources (aliases or URLs) must be configured in the Precision Policy Engine before Precision is deployed to production.

VRL Priority List Response

For either success or error, Precision responds with a JSON-formatted response. This table describes the fields in the response.

Successful Response

For a successful Priority List response, Precision responds with a list of resources. The list includes the selected resource, the CDN name, and the priority of this resource. Resource with highest priority should be used.

The response also includes a request identifier (c3.ri).

Important: Key and value of c3.ri MUST be appended as an additional query parameter, as-is, to the end of all of the CDN URLs that are generated and sent to the video player. This parameter allows for the Conviva VSI session to be correlated with the respective Precision response. As this happens, the Conviva platform adds the tags from the VRL request to the VSI session, which enables optimization by any parameter included in the VRL request.

Error Response

If an error occurs while processing a VRL request, an appropriate HTTP Status code is returned with a message body that contains a JSON-format message string that describes the error scenario.

1
2
3
4
5
6
{
 “is_error”: true,
 “error_code”: “ErrorCode”,
 “error_message”: “ErrorMessageString",
 “vrl”: “TheRequestVRLThatGeneratedThisResponse”
}

CDN Selection

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
    {"c3.ri":"5688238005746815660",
    "is_error":false,
    "resource_list":[
    {
    "cdn":"CDN_A",
    "priority":1,
    "resource":"CDN A”
    },
    {
    "cdn":”CDN_B",
    "priority":2,
    "resource":"CDN B"
    },
    {
    "cdn":"CDN_C",
    "priority":3,
    "resource":"CDN C"
    }
    ],
    "vrl":
    "https://vrl.m.conviva.com/a.ism/Manifest?c3.vr=2&c3.rt=p&c3.im=p&c3.um=d&c3.ck=2d140fe495d9f8e824faa884f68ddb8141a42ddb&c3.vp=l&c3.ip=90.216.134.196&c3.r1=CDN_A&c3.r2=CDN_B&c3.r3=CND_C&c3.vi=12345&c3.at=ON_DEMAND&c3.ext.DEVICE_TYPE=MOBILE&c3.ext.PLATFORM=IOS&c3.ext.SERVICE_KEY=432213&c3.ext.CONTENT_ID=123"}

Resource Optimization

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
    {"c3.ri":"5693023080729431544",
    "is_error":false,
    "resource_list":[
    {
    "cdn":"INHOUSE",
    "priority":1,
    "resource":"CDN1-DC1-LIVE-HLS"
    },
    {
    "cdn":"INHOUSE",
    "priority":2,
    "resource":"CDN1-DC2-LIVE-HLS"
    },
    {
    "cdn":"INHOUSE",
    "priority":3,
    "resource":"CDN2-DC1-LIVE-HLS"
    },
    {
    "cdn":"INHOUSE",
    "priority":4,
    "resource":"CDN2-DC2-LIVE-HLS"
    }
    ],
    "vrl":
    "https://vrl.m.conviva.com/?c3.vr=2&c3.rt=p&c3.im=p&c3.um=i&c3.ck=2d140fe495d9f8e824faa884f68ddb8141a42ddb&c3.ip=68.71.35.162&c3.os=WIN&c3.vi=ViewerID&c3.at=LIVE_EVENT&c3.vp=l&c3.r1=CDN1-DC1-LIVE-HLS&c3.r2=CDN1-DC2-LIVE-HLS&c3.r3=CDN2-DC1-LIVE-HLS&c3.r4=CDN2-DC2-LIVE-HLS"}

Error Scenarios

Precision API Reference

Use the Precision API reference to view detailed API information.

Conviva Precision API Reference