Roku Developer Help - Query Variables

Query Variables for Content and Ad URLs

This Instant TV Channel Help article is only applicable to Custom SDK Roku channels.

Instant TV Channel provides query variables that can be used in the URLs for content items, ads, MRSS feeds, and VAST tags. Any query variable in a URL is converted to a value generated within the Roku device before the device uses the URL to fetch the item.

%ADVERTISINGID - An 8-4-4-4-12 IETF-RFC 4122 UUID that can be used to uniquely identify the particular Roku device running the channel if the firmware version is greater than 3.1 and if the user has Ad ID Tracking enabled. This UUID is persistent but it can be reset by the user from the device's Settings menu or by performing a factory reset on the device. If the device's firmware version is 3.1 or lower, or if the user has Ad ID Tracking disabled, then an all-zero UUID is used.: Example
Original URL: http://www.example.com/preroll.xml?trackingid=%ADVERTISINGID
Converted URL: http://www.example.com/preroll.xml?trackingid=71467db9-861d-4a4e-b207-fd4476d8f04a

%CHANNELID - The unique ID of the Roku channel, as displayed on the Instant TV Channel "Channels" page. This query variable provides an 8-4-4-4-12 IETF-RFC 4122 UUID that can be used to uniquely identify a particular Roku channel.: Example
Original URL: http://www.example.com/preroll.xml?chid=%CHANNELID
Converted URL: http://www.example.com/preroll.xml?chid=01467db9-861d-4a4e-b207-fd4476d8f40a

%CHANNELTITLE - The Title of the Roku channel, stripped of any non-alphanumeric characters. The value returned by this query variable is from the channel's Pkg file, which may not be the same value that is in the title parameter of the Instant TV Channel Theme page if the channel needs to be re-packaged.: Example (Theme title parameter set to "My Roku Channel")
Original URL: http://www.example.com/preroll.xml?rokutitle=%CHANNELTITLE
Converted URL: http://www.example.com/preroll.xml?rokutitle=MyRokuChannel

%CONTENTID - The ContentId parameter of the content item currently selected, stripped of any non-alphanumeric characters.: Example
Original URL: http://www.example.com/preroll.xml?pid=%CONTENTID
Converted URL: http://www.example.com/preroll.xml?pid=vid1234

%CONTENTTITLE - The Title parameter of the content item currently selected, URL encoded.: Example (Content Title parameter set to "My Movie")
Original URL: http://www.example.com/preroll.xml?title=%CONTENTTITLE
Converted URL: http://www.example.com/preroll.xml?title=My%20Movie

%COUNTRYCODE - The 2-character ISO-3166-1 country code representing the country associated with the user's Roku account. A valid code is provided only if the Roku device's firmware is version 4.3 or greater. %COUNTRYCODE is automatically converted as follows:

US - United States

CA - Canada

GB - Great Britain

IE - Ireland

OT - Rest of world

XX - Device firmware is less than 4.3: Example
Original URL: http://www.example.com/video.mp4?country=%COUNTRYCODE
Converted URL: http://www.example.com/video.mp4?country=US

%DEVID - The Client ID of the Roku device, or the serial number if the device is running older obsolete firmware. The Client ID is different for each channel but it is persistent and CANNOT BE RESET BY THE USER. This query variable can be used to uniquely identify a particular Roku device.: Example
Original URL: http://www.example.com/video.mp4?id=%DEVID
Converted URL: http://www.example.com/video.mp4?id=12345678-1234-1234-1234-123456789012

%DHEIGHT - The display height in pixels. Firmware levels lower than 6.1 will always return "480".: Example
Original URL: http://www.example.com/tag.xml?h=%DHEIGHT
Converted URL: http://www.example.com/tag.xml?h=720

%DMODE - The display resolution. Possible values are "1080p", "720p", or "480i".: Example
Original URL: http://www.example.com/picture.png?rez=%DMODE
Converted URL: http://www.example.com/picture.png?rez=720p

%DTYPE - The type of display that is attached to the Roku device. Possible values are "HDTV", "4:3 standard", or "16:9 anamorphic". The value is URL encoded.: Example
Original URL: http://www.example.com/image.jpg?display=%DTYPE
Converted URL: http://www.example.com/image.jpg?display=4%3A3%20standard

%DWIDTH - The display width in pixels. Firmware levels lower than 6.1 will always return "720".: Example
Original URL: http://www.example.com/tag.xml?w=%DWIDTH
Converted URL: http://www.example.com/tag.xml?w=1920

%EXTERNALIP - The external IP address of the Roku device. This is the address seen by the Internet and all other computers outside device's local network. Firmware levels lower than 6.1 will always return "1.2.3.4".: Example
Original URL: http://www.example.com/tag.xml?ip=%EXTERNALIP
Converted URL: http://www.example.com/tag.xml?ip=192.168.1.20

%FWVER - The firmware version of the Roku device.: Example
Original URL: http://www.example.com/poster.png?firmware=%FWVER
Converted URL: http://www.example.com/poster.png?firmware=045.03E04016A

%ISADIDTRACKINGDISABLED - Whether or not the user has requested that ad ID tracking be disabled by unchecking the SYSTEM - PRIVACY - PERSONALIZE ADS checkbox. %ISADIDTRACKINGDISABLED is automatically converted as follows:

0 if the user has not requested that ad ID tracking be disabled (user's checkbox is checked).

1 if the user has requested that ad ID tracking be disabled (user's checkbox is unchecked) or if the Roku device's firmware is 3.1 or lower.: Example
Original URL: http://www.example.com/preroll.xml?disabletracking=%ISADIDTRACKINGDISABLED
Converted URL: http://www.example.com/preroll.xml?disabletracking=1

%MODEL - The model number of the Roku device.: Example
Original URL: http://www.example.com/livestream.m3u8?model=%MODEL
Converted URL: http://www.example.com/livestream.m3u8?model=4200X

%PALNONCE - A Google PAL / Ad Manager Nonce. Only available if RAF is enabled via the IncludeRAF Theme parameter and Google PAL is enabled via the Theme GooglePAL parameter.: Example
Original URL: http://www.adprovider.com/adtag.xml?u_paln=%PALNONCE
Converted URL: http://www.adprovider.com/adtag.xml?u_paln=YXNlbGM9MyZhc3Njc...dGNoPSZ3dGE9MA==

%POS - The current position in the main video content. Allows the main content position in seconds to be included in a video ad URL. %POS is automatically converted as follows:

0 if the video ad is a preroll, or if the URL is not for a video ad.

A positive integer indicating the number of seconds into the content if the video ad is a midroll.

-1 if the video ad is a postroll.: Example
Original URL: http://www.example.com/midroll.xml?position=%POS
Converted URL: http://www.example.com/midroll.xml?position=123

%RATING - The Rating parameter of the content item currently selected, URL encoded.: Example (Rating parameter set to "PG-13")
Original URL: http://www.example.com/preroll.xml?rating=%RATING
Converted URL: http://www.example.com/preroll.xml?rating=PG-13

Example (Rating parameter set to "Not Rated")
Original URL: http://www.example.com/preroll.xml?rating=%RATING
Converted URL: http://www.example.com/preroll.xml?rating=Not%20Rated

%RNDn - A random number. "n" must be 1 through 9. Can be used as a cache-buster to prevent images or other content from being cached in the Roku device or elsewhere.: Example
Original URL: http://www.example.com/image.jpg?random=%RND4
Converted URL: http://www.example.com/image.jpg?random=2837

Example
Original URL: http://www.example.com/poster.png?azar=%RND8
Converted URL: http://www.example.com/poster.png?azar=71836572

%SEQn - A sequential number, padded with leading zeros if necessary. "n" must be 1 through 9. The converted number is reset to "1" each time the channel is restarted. Can be used as a cache-buster to prevent images or other content from being cached in the Roku device or elsewhere.: Example
Original URL: http://www.example.com/image.png?number=%SEQ3
Converted URL: http://www.example.com/image.png?number=456

Example
Original URL: http://www.example.com/thumbnail.jpg?counter=%SEQ9
Converted URL: http://www.example.com/thumbnail.jpg?counter=000000021

%TIME - The time in epoch seconds (seconds since 1/1/1970).: Example
Original URL: http://www.example.com/picture.jpg?now=%TIME
Converted URL: http://www.example.com/picture.jpg?now=1378999160

%TOKEN - The Registration & Linking device token. If the Roku device has not been registered, a token of "0" is returned. This special query variable can be used to return customized MRSS feeds based on customer preferences specified on a remote server.: Example
Original URL: http://www.example.com/mrssfeed.xml?mytoken=%TOKEN
Converted URL: http://www.example.com/mrssfeed.xml?mytoken=9UR4TE54FWFBMFHB

%URL - The encoded URL for the main video content. This query variable allows the main content URL to be included within a video ad URL.: Example
Video Content URL: http://www.cdn.com/movie.mp4?x=2&y=3
Original URL: http://www.example.com/preroll.xml?contentid=%URL
Converted URL: http://www.example.com/preroll.xml?contentid=http%3A%2F%2Fwww.cdn.com%2Fmovie.mp4%3Fx%3D2%26y%3D3

%US_PRIVACY - Whether or not the user has requested that ad ID tracking be disabled by unchecking the SYSTEM - PRIVACY - PERSONALIZE ADS checkbox. %US_PRIVACY is automatically converted as follows:

"1-N-" if the user has not requested that ad ID tracking be disabled (user's checkbox is checked).

"1-Y-" if the user has requested that ad ID tracking be disabled (user's checkbox is unchecked) or if the Roku device's firmware is 3.1 or lower.: Example
Original URL: http://www.example.com/preroll.xml?us_privacy=%US_PRIVACY
Converted URL: http://www.example.com/preroll.xml?us_privacy=1-N-

%USERID - The unique ID of the Instant TV Channel account that was used to package the channel. This query variable provides an 8-4-4-4-12 IETF-RFC 4122 UUID that can be used to uniquely identify a particular developer.: Example
Original URL: http://www.example.com/video.mp4?uid=%USERID
Converted URL: http://www.example.com/video.mp4?uid=a1467db9-861d-4a4e-b207-fd4476d8f40b

%VER - The 6-digit Instant TV Channel Brightscript version number in YYMMDD (Year - Month - Day) format.: Example (150223 = February 23, 2015)
Original URL: http://www.example.com/poster.png?version=%VER
Converted URL: http://www.example.com/poster.png?version=150223

Multiple query variables can be combined in a single URL.: Example
Original URL: http://www.example.com/gridrow.xml?custid=%DEVID&hw=%MODEL&anticache=%SEQ8
Converted URL: http://www.example.com/gridrow.xml?custid=1GH399999999&hw=4200X&anticache=11148692

Want to know how to make a complete Roku channel in only a few minutes? Take a look at this Instant TV Channel Walk-Through for more information.

Suggestions, questions, or comments about this Roku developer guide can be sent to .