App URL Specifications

Article summary

Did you find this summary helpful?

Thank you for your feedback

Application URL Specification

Introduction

X1 Apps should support a single launch URL that allows the platform to pass in standard parameter names, which are leveraged by editorial tiles and the voice remote to bring users to the correct content in the X1 App. If the X1 App supports deep linking, including launches through guard word voice search, it is then the app’s responsibility to route the user to the correct area of the app or perform the correct action. This can be achieved by implementing routing logic in the app itself.

URL Format

Apps may implement the deep linking scheme either using query parameters or as URI fragment (anchor) parameters.

For Single Page Apps, using URI fragments is preferred as it allows the app to be navigated to different pages, for example via in-app voice, without forcing a browser reload.

Query paramters:

{appPrefix}?launchpoint={launchpoint}&query={query}&assetId={assetId}&assetType={assetType}&entityId={entityId}&sectionName={sectionName}

URI fragment parameters:

{appPrefix}#launchpoint={launchpoint}&query={query}&assetId={assetId}&assetType={assetType}&entityId={entityId}&sectionName={sectionName}

Where appPrefix is the app's specific host and path. For example, https://www.tvapp.com/path/to/app.

Note that all parameters may be set in the URL even if they are not relevant for the specific launchpoint. The value for the parameter will be empty in this case.

Query parameters may be added or removed in the future. The order of the parameters is not static. Your X1 App must support the addition of new query params that come in any order.

Parameter Definitions

Parameter Name	Description
launchpoint	The action the app should perform at launch. See below for list of supported launchpoint values. Default to home if not specified.
query	User specified query value, for search.
assetId	The asset id, identified in the app's id space. This refers to a specific video resource that can be played.
assetType	The type of the asset to play. Optional, when assetId is provided. It can be omitted when the QLT service/router does not require the type to generate the app URL. Supported types: vod: VOD and single live event assets. linear: 24/7 linear streams.
entityId	An entity ID in the app's ID space, such as a movie, TV series, TV season, TV episode, playlist, event, artist, album, etc. In some cases, this will be the same value as assetId, but implementation will vary by app.
sectionName	A "section" name for the app to navigate to. The value is specific per app. Could be a navigation section like Guide, Settings, etc. If used, the app must publish a well defined list of sectionNames
lmt	Included with all Application URLs. The value is derived from the IAB Identifier For Advertising (IFA) for Over-the-Top Devices. See Limit Ad Tracking and CCPA Technical Requirements for more details. Supported Values: 0 = user can receive personalized advertising 1 = user cannot receive personalized advertising
us_privacy	Included with all Application URLs. The value is derived from the IAB CCPA Compliance Framework. These values are subject to change, as described in the linked documentation. See Limit Ad Tracking and CCPA Technical Requirements for more details. Supported Values: 1-N- = user has not opted-out of activities subject to Cal. Civ. Code §1798.135: Do Not Sell My Personal Information 1-Y- = user has opted-out of activities subject to Cal. Civ. Code §1798.135: Do Not Sell My Personal Information

Supported Launchpoint Values

Value	Description	Required Parameters	Optional Parameters
home	Default app start page.	N/A	N/A
detail	An entity detail page.	entityId	N/A
playback	Begin playing back the specified assetId.	assetId	assetType
search	Return search results for the specified query.	query	N/A
section	Navigate to a specific section of the app.	sectionName	N/A

Examples:

Inapplicable parameters will still be passed to the application, with no value set. Apps should be prepared to ignore parameters sent with no value. This is shown in the examples below for clarity.

For example q= will be provided when launchpoint=playback.

Given an app hosted at https://www.tvapp.com/x1:

Navigate to home page, ad opt-out not enabled:

https://www.tvapp.com/x1?launchpoint=home

https://www.tvapp.com/x1#launchpoint=home

Execute a search for "police academy":

https://www.tvapp.com/x1?launchpoint=search&query=police%20academy

https://www.tvapp.com/x1#launchpoint=search&query=police%20academy

Play an asset with id ABCD123

https://www.tvapp.com/x1?launchpoint=playback&assetId=ABCD123

https://www.tvapp.com/x1#launchpoint=playback&assetId=ABCD123

Play a explicitly specified linear asset with id channel2:

https://www.tvapp.com/x1?launchpoint=playback&assetId=channel2&assetType=linear

https://www.tvapp.com/x1#launchpoint=playback&assetId=channel2&assetType=linear

Navigate to the entity page for the TV Series specified by id 8fcb5798-86aa-4a06-8053-f9d3e131d0b9:

https://www.tvapp.com/x1?launchpoint=detail&entityId=8fcb5798-86aa-4a06-8053-f9d3e131d0b9

https://www.tvapp.com/x1#launchpoint=detail&entityId=8fcb5798-86aa-4a06-8053-f9d3e131d0b9

Navigate to to the app's Settings page:

https://www.tvapp.com/x1?launchpoint=section&sectionName=settings

https://www.tvapp.com/x1#launchpoint=sectionName=settings

Other Query Parameters & URI Fragments

If an app is using the URI fragment approach, any parameters not specified above will be set as query parameters before the hash mark. For example:

https://www.tvapp.com/x1?deviceModel=xi5&lmt=0&us_privacy=1-N-#launchpoint=playback&assetId=ABCD123

Was this article helpful?

What's Next

Cloud Cookies

Table of contents

Application URL Specification