Deep links

As content becomes available from a number of providers, each with their own streaming and playback services, it is increasingly the role of an operator to become the central hub for all video services. Some operators have agreements with third-party Content Providers (CPs) to carry content on the operator's platform and to consume the content through the host's application. Others will provide reference to their content, to be redirected, and consumed through, a third-party app.

A "deep link" is a pointer from the assets in the core platform to one or more other providers, such as Disney+, Amazon Prime Video, or Netflix.

The deep links are not "first-class" entities, but are embedded within the standard metadata API, specifically:

/vod/editorials
/vod/series
/btv/series
/btv/programmes
/search

Deep link item specification

Parameter Type/example Description

id string
Example: NFX_123 The identifier of the deep link.

name string
Example: Cowspiracy The name of the deep link content.

contentRef string
Example: GLOBAL_123 The reference to the editorialContent linked

period Period{...} The time period for which the link is valid

provider string
Example: Netflix The source provider (e.g. AMAZON)

deviceType [string] A list of devices for which the deep link is applicable

resolution [string] The available resolutions of the deep-linked content

original boolean
Example: false Whether the linked content is an original source

type string The content type

action string The action to take upon accessing this link, e.g., open another application

url string
Example: https://netflix.com/abc/xyz The URL of the deep link

playbackOptions

[{

`price`	number Example: `5.99`
`definition`	number Example: `HD`
`currency`	string Example: `GBP`
`license`	string

}]

Additional options about the linked content, e.g., price of subscription

playbackParams string Opaque params for use with the target platform

VoD editorials

The VoD editorials can have one or more links embedded within them. It is possible to query by two of the link fields:

link.provider – the source of the deep link
link.deviceType – the device(s) applicable for the link

Deep links can be filtered by device type

This restricts the deep links returned to those suitable for the specified client.

?filter={"link.deviceType": "Android"}

Deep links can be filtered by a content provider

This restricts the deep links returned to those from a specific provider.

?filter={"link.provider": "Netflix"}

Example with response

/metadata/delivery/v2/GLOBAL/vod/editorials?filter={"link.provider": "AMAZON"}

JS

{
    "editorials": [
        {
            "id": "AMAZON_EP005927330001",
            "contentLinkId": "EP005927330001",
            "Description": "Charlie's life turns upside down when his brother and nephew move in; at the supermarket, Charlie discovers he can use 10-year-old Jake to attract women.",
            "Title": "Pilot",
            "Synopsis": "Charlie discovers that a man raising a 10-year-old boy attracts the attention of women.",
            "ShortTitle": "Pilot",
            "technicals": [],
            "links": [
                {
                    "id": "AMAZON_EP005927330001_Deeplink",
                    "provider": "AMAZON",
                    "action": "details",
                    "contentRef": "AMAZON_EP005927330001",
                    "title": "Two and Half Men",
                    "type": "universalLink",
                    "url": "https://app.primevideo.com/watch?gti=amzn1.dv.gti.b2b6560e-fa65-0285-8a45-c1c6695caec0&time=auto&ref_=atv_cf_strg_ap",
                    "original": false,
                    "period": {
                        "start": 1613923200.0,
                        "end": 8962185600.0,
                        "duration": 7348262400
                    },
                    "playbackOptions": []
                }
            ]
        }
    ],
    "total_records": 1
}

Series/seasons

Similarly to VoD, a series or season can have deep links embedded.

Deep links can be filtered by device type

This will return series that have at least one deep link for an Android device:

?filter={"links.deviceType": "Android"}

Deep links can be filtered by a content provider

This will return series that have at least one deep link for the provider Netflix:

?filter={"links.provider": "Netflix"}

Example with response

/metadata/delivery/GLOBAL/vod/series?filter={"links.provider": "DPLUS"}

JS

{
    "total_records": 1,
    "series": [
        {
            "id": "DPLUS_184925",
            "Title": "Two and a Half Men",
            "links": [
                {
                    "id": "DPLUS_184925_Deeplink",
                    "provider": "DPLUS",
                    "action": "details",
                    "contentRef": "DPLUS_184925",
                    "title": "Two and Half Series",
                    "type": "universalLink",
                    "url": "https://www.disneyplus.com/movies/the-day-the-series-stopped/17Xan8d2xiPV",
                    "original": false,
                    "period": {
                        "start": 1613923200.0,
                        "end": 8962185600.0,
                        "duration": 7348262400
                    },
                    "playbackOptions": []
                }
            ]
        }
    ]
}

Search

The search API is kept minimal, as it is for other use cases. You can, however, opt to search within certain content providers (for example – I want to search within Disney content), or to exclude certain content providers from a search (I want to avoid searching within Disney).

Search for any content

?q=south park

Search for content that belongs to the primary operator (GLOBAL)

?q=south park&fq=providers:GLOBAL

Search for content that belongs to Netflix

?q=south park&fq=providers:Netflix

Exclude content that belongs to Netflix

?q=south park&fq=-providers:Netflix

Example with response

/metadata/solr/GLOBAL/search?q=providers:AMAZON

JS

{
    "responseHeader": {
        "status": 0,
        "QTime": 67
    },
    "response": {
        "numFound": 2,
        "start": 0,
        "docs": [
            {
                "uid": "AMAZON_184925|en_GB|vod|series",
                "id": "AMAZON_184925",
                "locale": "en_GB",
                "scope": "vod",
                "entity": "series",
                "provider": "GLOBAL",
                "isSeason": false,
                "isSeries": true,
                "isEpisode": false,
                "series": "",
                "title": "Two and a Half Men",
                "title_o": "Two and a Half Men",
                "rating.code": "TVPG",
                "rating.precedence": -1,
                "isPublished": true,
                "providers": [
                    "GLOBAL",
                    "AMAZON"
                ]
            }
        ]
    }
}

Recommending deep links

In the same way that the NAGRA platform enables operators to have VoD or BTV items "recommended", it is also possible to make personalised recommendations that include "deep linked" content. See the Recommendations Façade section for further guidance on this.

Deep link item specification

VoD editorials

Deep links can be filtered by device type

Deep links can be filtered by a content provider

Example with response

Series/seasons

Deep links can be filtered by device type

Deep links can be filtered by a content provider

Example with response

Search

Search for any content

Search for content that belongs to the primary operator (GLOBAL)

Search for content that belongs to Netflix

Exclude content that belongs to Netflix

Example with response

Recommending deep links

See also