Device Targeting

The tvlabs:constraints capability provides a powerful way to target your test scripts to specific devices on the TV Labs platform. It supports two formats: Kibana Query Language (KQL) query strings and key-value objects.

Constraint Query

info

For more information about Kibana Query Language, see the Elastic documentation.

For a query to be valid, the platform_key must be unambiguous. If multiple platform keys could match the query, the request will fail.

A valid query must not:

• Use a glob pattern for a platform key e.g. platform_key:*os
• Be contained in a list of values e.g. platform_key:(tizen or web_os)
• Contain an OR condition that can evaluate to multiple platform keys e.g. platform_key:android_tv and make:nvidia or platform_key:roku
• Contain a NOT condition for a platform key e.g. not platform_key:web_os

Available Fields

Field	Description	Supported Comparisons	Supports Glob Pattern
platform_key	An unambiguous platform key (see available values in the Platforms section)	:	No
make	The device manufacturer (e.g., Samsung)	:	Yes
device_type	The device type (tv, stb, or mobile)	:	Yes
model	The device model (e.g., Express 4K+)	:	Yes
year	The device model year (e.g., 2024)	: < > <= >=	Yes
platform_os_variant	The platform OS variant (e.g., fire_tv)	:	Yes
chromedriver_version	The ChromeDriver version (e.g., 76.0.0.0)	: < > <= >=	Yes
account_region	The Teleport region of the device's logged in account	:	Yes
version field	Any of the platform's version fields below (e.g., os_version, chromium_version)	: < > <= >=	Yes
platform_os_version	(Deprecated) The platform's OS version. Use the platform's own OS version field below instead (e.g., platform_version on Tizen)	: < > <= >=	Yes

Version Fields

Every software version a device reports can be targeted by name. Which fields exist depends on the platform, and a query naming a field its platform does not report is rejected with the list of fields that platform does report.

Comparisons (< > <= >=) work against however many dotted numeric components the device reports and the query provides. Both sides are compared component by component after padding the shorter one with zeros, so os_version>=8.0 matches a device reporting 8.0.1 and os_version<8.1 excludes it, the same way 8.0.0/8.1.0 would. The same holds for chromium_version, which always has four: chromium_version>=108 asks for 108.0.0.0. Letters are ignored, so a webOS device reporting webOSTV 6.0 matches os_version>=6. Equality (:) and glob patterns match the reported string as written.

A version with no digits at all can only be matched exactly, ignoring case: yocto_version:"kirkstone" matches a device reporting kirkstone, while yocto_version>=kirkstone matches nothing.

The first field in each table is the platform's OS version, which platform_os_version used to name.

Tizen (tizen)

Field	Description	Example
platform_version	The Tizen platform version	8.0
platform_build_version	The Tizen platform build	20230929.1
product_version	The TV's product software version	3.1.0
sdbd_version	The SDB daemon version	2.2.31
sdbd_cap_version	The SDB capability protocol version	1.0
sdbd_plugin_version	The SDB plugin version	3.9.7
chromium_version	The Chromium the TV's web runtime is built on	94.0.4606.31
webkit_version	The WebKit version the TV's web runtime reports	537.36

webOS (web_os)

Field	Description	Example
os_version	The webOS product version	webOSTV 6.0
firmware_version	The TV firmware version	23.20.50
chromium_version	The Chromium the TV's web runtime is built on	87.0.4280.22
webkit_version	The WebKit version the TV's web runtime reports	537.36

Android TV and Android mobile (android_tv, android_mobile)

Field	Description	Example
android_version	The Android release	12
api_version	The Android API level	32
security_patch	The security patch level	2024-01-05
build_id	The build ID	STTL.240206.002
build_display_id	The build ID as shown in settings	STTL.240206.002.A1
build_incremental	The incremental build number	11407591
build_fingerprint	The full build fingerprint	google/sabrina/...
fire_version	The Fire OS version (Fire TV only)	7.6.9.4
fire_build_name	The Fire OS build name (Fire TV only)	PS7694
fire_os_major	The Fire OS major version (Fire TV only)	7
fire_build_number	The Fire OS build number (Fire TV only)	0006
fire_build_serial	The Fire OS build serial (Fire TV only)	20240223
shield_experience_version	The Shield Experience version (NVIDIA Shield only)	9.1.1
chromium_version	The Chromium version of the installed WebView	138.0.7204.244

Roku (roku)

Field	Description	Example
software_version	The Roku OS version	14.1.4
software_build	The Roku OS build	5217
build_number	The full build number	14.1.4.5217
lightning_base_build_number	The Lightning base build number	14.1.4.5217
ui_software_version	The UI software version	14.1.4
ui_software_build	The UI software build	5217
ui_build_number	The UI build number	14.1.4.5217
grandcentral_version	The Grand Central version	10.1.34
brightscript_debugger_version	The BrightScript debugger protocol version	3.3.0
trc_version	The TRC version (devices that support TRC)	3.0
trc_channel_version	The TRC channel version (devices that support TRC)	4.1.5

Vizio SmartCast (smartcast)

Field	Description	Example
os_version	The SmartCast OS version	4.20.10.1
firmware_version	The TV firmware version	4.20.10.1
conjure_version	The Conjure API version	3.1.0
scpl_version	The SCPL version	1.0.6
cast_version	The Chromecast built-in version	1.56.500000
airplay_version	The AirPlay version	2.0
apple_tv_version	The Apple TV app version	1.6.6
bluetooth_version	The Bluetooth stack version	5.0
vizio_ndk_version	The Vizio NDK version	2.3.0
sc_config_version	The SmartCast configuration version	20240110
chromium_version	The Chromium the TV's web runtime is built on	105.0.5195.68
webkit_version	The WebKit version the TV's web runtime reports	537.36

Apple TV (tv_os) and iOS (ios)

Field	Description	Example
os_version	The tvOS or iOS version	17.4
os_build	The OS build	21L227

Amazon Vega (vega)

Field	Description	Example
os_version	The Vega OS version	1.2
software_version	The device software version	1.2.0.4
build_fingerprint	The full build fingerprint	amazon/...
kernel_version	The Linux kernel version	5.15.41
oe_version	The OpenEmbedded release	4.0.12
release_id	The release ID	20240501
branch_code	The build branch code	1.2
build_date	The build date	20240501

Entertainment OS (Sky and Xumo)

Field	Description	Example
rdk_version	The RDK release	8.6p3s1
yocto_version	The Yocto release	kirkstone
sky_version	The Sky firmware build	QSE042.003.00U
branch	The build branch	support_8.6
image_name	The firmware image name	SKTL21MEI_E042.003.00.8.6p3s1_DEV
wpe_webkit_version	The WPE WebKit release	2.38.8+gitAUTOINC+680d0afd32-r12.1
as_version	The application services version	RDK8.6.00.315.7
mw_version	The middleware version	8.6p3s1
network_version	The network stack version	2.00
version_number	The box's version code	32C00A
apps_service_gatewayd	The apps service gateway version	85.3.0
as_analytics_service_tag	The analytics service tag	AS_ANALYTICS_RDK8.6.69.3
as_apps_service_tag	The apps service tag	85.3.0
as_network_service_tag	The network service tag	NETWORK_REL_RDK8.6.99.1
as_peripherals_tag	The peripherals service tag	AS_PERIPHERALS_RDK8.6.76.1
as_player_tag	The player service tag	AS_PLAYER_REL_RDK8.6.288.3
as_proxy_service_tag	The proxy service tag	AS_PROXY_REL_000.181
as_system_service_tag	The system service tag	AS_SYSTEM_REL_RDK8.6.308.7
as_voice_service_tag	The voice search service tag	AS_VOICE_SEARCH_RDK8.6.86.1
jspp_tag	The JSPP tag	1.47.7
lib_as_service_tag	The application services library tag	AS_LIB_SERVICE_REL_RDK8.6.124.1
mw_local_store_tag	The middleware local store tag	SKY_MWLOCALSTORE_000.21

Examples

Device Targeting

Target any webOS device with version 8.0 or higher, and model starting with C or UT but excluding model C1PUB:

platform_key:web_os
AND os_version>=8.0
AND model:(C* OR UT*)
AND NOT model:C1PUB

Target any Tizen device whose web runtime is Chromium 94 or newer:

platform_key:tizen
AND chromium_version>=94.0.0.0

Target any Roku on Roku OS 14 that supports TRC:

platform_key:roku
AND software_version>=14
AND trc_version:*

Target any Vizio V-series device newer than 2021:

platform_key:vizio
AND model:V*
AND year>2021

Target Roku devices not manufactured by Roku:

platform_key:roku
AND NOT make:Roku

Target any Android TV device that is a physical television (not a set-top box):

platform_key:android_tv
AND device_type:tv

Target any Tizen device that supports ChromeDriver:

platform_key:tizen
AND chromedriver_version:*

Escaping Special Characters

Unquoted values must escape \():<>"* characters. Every character will be treated as a literal in quoted values.

Target a value with spaces in the value:

platform_key:android_tv
AND model:"Fire TV Stick 4K MAX"

Alternatively, the spaces may be escaped without quoting the value:

platform_key:android_tv
AND model:Fire\ TV\ Stick\ 4K\ MAX

info

Targeting one of your organization's own devices directly? See Dedicated Devices.

Narrow constraints take longer to fill. See Device Fulfillment for how requests are matched and how to get a specific variant faster.

Tags

Some devices are reserved behind a tag. A tagged device only accepts sessions whose tvlabs:constraints capability opts into that tag with a tag:<slug> term. Leave the tag out and your request will never match those devices, so access is opt-in rather than something you fall into by accident.

Rules for tag:<slug> terms:

• The query must also constrain platform_key. A tag term with no platform key is rejected.
• Only equality is supported (tag:test-flight). Glob patterns, lists, OR, and NOT are not.
• Combine multiple tags with AND. The device must carry every tag you list.

Target devices reserved under test-flight on webOS:

platform_key:web_os
AND tag:test-flight

Target devices reserved under both test-flight and beta:

platform_key:web_os
AND tag:test-flight
AND tag:beta

Legacy Constraints

An alternative constraint format uses key-value objects instead of query strings.

Example tvlabs:constraints capability to target any webOS device on webOS 6 or higher that supports ChromeDriver version 76 or higher:

{
  platform_key: 'web_os',
  version_requirements: { os_version: '>= 6.0' },
  chromedriver_requirement: '>= 76.0.0.0'
}

Available Fields

Key	Description
platform_key	Required. The platform key of the device (see available values in the Platforms section)
make	The device manufacturer (e.g., Samsung)
device_type	The device type (tv, stb, or mobile)
model	The device model (e.g., Express 4K+)
year	The device model year (e.g., 2024)
version_requirements	An object of version field to requirement (e.g., { os_version: '>= 6.0', chromium_version: '>= 87.0.0.0' }). Requirements combine clauses with and/or (e.g., >= 6.0 and < 8.0)
platform_os_requirement	(Deprecated) The platform OS version requirement (e.g., >= 10.0.0). Use version_requirements with the platform's OS version field instead
platform_os_variant	The platform OS variant (e.g., fire_tv)
chromedriver_requirement	(Deprecated) The ChromeDriver version requirement (e.g., >= 76). Use the constraint query's chromedriver_version instead
supports_chromedriver	Whether the device supports ChromeDriver
minimum_chromedriver_major_version	(Deprecated) The minimum major version of ChromeDriver
tags	An array of tag slugs opting into reserved devices (e.g. ['test-flight']). See Tags above