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 APIs, specifically:

/vod/editorials
/vod/series
/btv/series
/btv/programmes
/search (using Search Facade)

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

CODE

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

JSON

{
    "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

CODE

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

JSON

{
    "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

CODE

https://<hostname>/search/v1/search?q=south park&provider:AMAZON&includeDeepLinks=true

To include deep links in the search results, either add an includeDeepLinks=true query parameter, as shown above, or omit it (it defaults to true).

JS

{
  "results": [
    {
      "id": "AMAZON_184925",
      "title": "South Park Season 02",
      "type": "series",
      "source": "platform",
      "locale": "en_GB"
    }
  ],
  "totalRecords": 1
}

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