What are the guidelines for adding ADS session variables with values provided from segmentation UPID tokens in MediaTailor?

3 minute read

I want to add ADS session variables with values provided from segmentation UPID tokens in AWS Elemental MediaTailor. What are the guidelines for doing this?

Short description

MediaTailor can send specific data within the SCTE-35 segmentation unique program ID (UPID). MediaTailor parses the UPID and sends the tokens to the ad decision server (ADS) as session variables. If the payloads are formatted correctly, then you can send a variety of private data payloads.


The following are guidelines on the segmentation UPID formatting requirements and example segmentation UPIDs. The functionality works for DASH and HLS. DASH requires the binary marker to work with XML EventStreams.


  • The segmentation UPID must have the following:
    A segmentation_upid_type of 12.
    A format_identifier, consisting of any four bytes.
  • The MediaTailor solution works with any ADS platform and the number of tokens isn't fixed.
  • The decoded SCTE-35 segmentation UPID can contain one or more colon delimiters. If there is no colon delimiter, then the UPID is considered a single value. Colon delimiters allow for one or more values.
  • The number of template variables and decoded UPID tokens must be equal, as shown in the following examples:
  • ADS URL template variables default to empty if they find an invalid string, for example, https://domain/ads?sur0=&sur1=&sur2=.
  • The limits and format structure follows the ANSI/SCTE 35 2019 section specification. This specification is as follows:
MPU() {         format_identifier          private_data }32N*8uimsbfuimsbf

format_identifier is a 32-bit unique identifier as defined in ISO/IEC 13818-1 and registered with the SMPTE Registration Authority.

private_data is a variable length, byte-aligned set of data as defined by the registered owner of the format_identifier field value. The length is defined by the segmentation_upid_length, which includes the format_identifier field length.

Example of segmentation UPID usage

SCTE source


Decoded SCTE

MediaTailor parses the UPID and assumes the first four bytes are the format_identifier. If the format_identifier is missing, then the private_data truncates the first four bytes. This might cause problems with the ADS expecting a different value. For example, if the UPID is written as 123456 instead of ABCD123456 (where ABCD is the format_identifier), then MediaTailor interprets 1234 as the format identifier and the rest of the UPID as 56. This causes the ADS call to be made with 56 instead of 123456.

"segmentation_upid_type": 12,
                  "segmentation_upid_type_name": "MPU",
                  "segmentation_upid_length": 29,
                  "segmentation_upid": {
                        "format_identifier": "0x796a6974",
                        "private_data": "0x3a34363137353231383a34363137353231382f353a34303533"

Decoded UPID (Private data)


The preceding bytes, if present, are the ASCII encoded HyLDA (FreeWheel) fields separated by colons.

In this example, the tokens map to session variables where the token order is :Airing ID:Break ID:Channel ID. The token is then sent to the ad server (ADS). This example uses FreeWheel as the ad server. MediaTailor also works with other ad servers.

Example segmentation UPIDs

  • :DS8291:33129DS:SAD123 is considered valid.
  • :46175218:46175218/5:4053 is considered valid.
  • :46175218::4053 is considered invalid due to the use of the double colon with no value in between.
  • :461752@a:46175218/5:4053 is considered valid.
  • :: is considered invalid due to the use of the double colon with no values before, between, or at the end.

Example session variables




Related information

Using session variables

AWS OFFICIALUpdated 2 years ago