Device Targeting

info

An API to explore available values for tvlabs:constraints is coming soon.

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:fire_tv
• 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_version	The platform OS version (e.g., 10.0.0)	: < > <= >=	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

Examples

Device Targeting

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

platform_key:web_os
AND platform_os_version>=8.0.0
AND model:(C* OR UT*)
AND NOT model:C1PUB

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:fire_tv
AND model:"Fire TV Stick 4K MAX"

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

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

info

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

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 that supports ChromeDriver version 76 or higher:

{
  platform_key: 'web_os',
  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)
platform_os_requirement	The platform OS version requirement (e.g., >= 10.0.0)
platform_os_variant	The platform OS variant (e.g., fire_tv)
chromedriver_requirement	The ChromeDriver version requirement (e.g., >= 76.0.0.0)
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