Using session variables

To configure AWS Elemental MediaTailor to send session data to the Ad Decision Server (ADS), in the template ADS URL, specify one or more of the variables listed in this section. You can use individual variables, and you can concatenate multiple variables to create a single value. MediaTailor generates some values and obtains the rest from sources like the manifest and the player's session initialization request.

The following table describes the session data variables you can use in your template ADS request URL configuration. The section numbers listed in the table correspond to the 2019a version of the Society of Cable Telecommunications Engineers (SCTE)-35 specification, Digital Program Insertion Cueing Message For Cable, For details about ad prefetch, see Prefetching ads.

Name	Available for ad prefetch	SCTE-35 specification section	Description
`[avail.index]`	Yes		A number that represents the position of an ad avail in an index. At the start of a playback session, MediaTailor creates an index of all the ad avails in a manifest and stores the index for the remainder of the session. When MediaTailor makes a request to the ADS to fill the avail, it includes the ad avail index number. This parameter enables the ADS to improve ad selection by using features like competitive exclusion and frequency capping.
`[avail.random]`	Yes		A random number between 0 and 10,000,000,000, as a long number, that MediaTailor generates for each request to the ADS. Some ad servers use this parameter to enable features such as separating ads from competing companies.
`[scte.archive_allowed_flag]`	Yes	10.3.3.1	An optional Boolean value. When this value is 0, recording restrictions are asserted on the segment. When this value is 1, recording restrictions are not asserted on the segment.
`[scte.avail_num]`	Yes	9.7.2.1	The value parsed by MediaTailor from the SCTE-35 field `avail_num`, as a long number. MediaTailor can use this value to designate linear ad avail numbers.
`[scte.avails_expected]`	Yes	9,7.2.1	An optional long value that gives the expected count of avails within the current event.
`[scte.delivery_not_restricted_flag]`	Yes	10.3.3.1	An optional Boolean value. When this value is 0, the next five bits are reserved. When this value is 1, the next five bits take on the meanings as described in the SCTE-35 specification.
`[scte.device_restrictions]`	Yes	10.3.3.1	An optional integer value that signals three pre-defined, independent, and non-hierarchical groups of devices. For more information about this variable, see the segments_expected description in the SCTE-35 specification.
`[scte.event_id]`	Yes	9.1 and 9.7.2.1	The value parsed by MediaTailor from the SCTE-35 field `splice_event_id`, as a long number. MediaTailor uses this value to designate linear ad avail numbers or to populate ad server query strings, like ad pod positions.
`[scte.no_regional_blackout_flag]`	Yes	10.3.3.1	An optional Boolean value. When this value is 0, regional blackout restrictions apply to the segment. When this value is 1, regional blackout restrictions do not apply to the segment.
`[scte.segment_num]`	Yes	10.3.3.1	An optional integer value that numbers segments within a collection of segments. For more information about this variable, see the segment_num description in the SCTE-35 specification.
`[scte.segmentation_event_id]`	Yes	10.3.3.1	MediaTailor exposes this variable as scte.event_id.
`[scte.segmentation_type_id]`	Yes	10.3.3.1	An optional 8-bit integer value that specifies the segmentation type. For more information about this variable, see the segmentation_type_id description in the SCTE-35 specification.
`[scte.segmentation_upid]`	`segmentation_upid_type`: Yes `private_data`: Yes	segmentation_upid: 10.3.3.1 Managed Private UPID: 10.3.3.3	Corresponds to the SCTE-35 `segmentation_upid` element. The `segmentation_upid` element contains `segmentation_upid_type` and `segmentation_upid_length`. MediaTailor supports the following `segmentation_upid` types: ADS Information (0x0E) - Advertising information. For more information, see the segmentation_upid description in the SCTE-35 specification. Managed Private UPID (0x0C) - The Managed Private UPID (MPU) structure as defined in the SCTE-35 specification. MediaTailor supports binary or DASH XML SCTE representations. You can use this structure in a podbuster workflow. To do so, specify a 32-bit (4 byte) `format_identifier`, and include the following parameters in the `private_data` attribute: `ABCD{"assetId":"my_program","cueData":{"cueType":"theAdType","key":"pb","value":"123456"}}` MediaTailor parses the values from the preceding JSON, and passes them into the `scte.segmentation_upid.assetId`, `scte.segmentation_upid.cueData.key`, and `scte.segmentation_upid.cueData.value` dynamic variables. User Defined (0x01) - A user defined structure. For more information, see the segmentation_upid description in the SCTE-35 specification.
`[scte.segmentation_upid.assetId]`	Yes		Used in conjunction with the Managed Private UPID (0xC) `segmentation_ upid_type` for podbuster workflows. MediaTailor derives this value from the `assetId` parameter in the MPU's `private_data` JSON structure. For more information, see Managed Private UPID JSON structure for a podbuster workflow.
`[scte.segmentation_upid.cueData.key]`	Yes		Used in conjunction with the Managed Private UPID (0xC) `segmentation_ upid_type` for podbuster workflows. MediaTailor derives this value from the `cueData.key` parameter in the MPU's `private_data` JSON structure. For more information, see Managed Private UPID JSON structure for a podbuster workflow.
`[scte.segmentation_upid.cueData.value]`	Yes		Used in conjunction with the Managed Private UPID (0xC) `segmentation_ upid_type` for podbuster workflows. MediaTailor derives this value from the `cueData.key` parameter in the MPU's `private_data` JSON structure. For more information, see Managed Private UPID JSON structure for a podbuster workflow.
`[scte.segments_expected]`	Yes	10.3.3.1	An optional integer value that gives the expected count of individual segments within a collection of segments. For more information about this variable, see the segments_expected description in the SCTE-35 specification.
`[scte.sub_segment_num]`	Yes	10.3.3.1	An optional integer value that identifies a particular sub-segment within a collection of sub-segments. For more information about this variable, see the sub_segment_num description in the SCTE-35 specification.
`[scte.sub_segments_expected]`	Yes	10.3.3.1	An optional integer value that gives the expected count of individual sub-segments within a collection of sub-segments. For more information about this variable, see the sub_segments_expected description in the SCTE-35 specification.
`[scte.unique_program_id]`	Yes	9.7.2.1	The integer value parsed by MediaTailor from the SCTE-35 `splice_insert` field `unique_program_id`. The ADS uses the unique program ID (UPID) to provide program-level ad targeting for live linear streams. If the SCTE-35 command is not splice insert, MediaTailor sets this to an empty value.
`[session.avail_duration_ms]`	Yes		The duration in milliseconds of the ad availability slot. The default value is 300,000 ms. AWS Elemental MediaTailor obtains the duration value from the input manifest as follows: For HLS, MediaTailor obtains the duration from the `#EXT-X-CUE-OUT: DURATION` or from values in the `#EXT-X-DATERANGE` tag. If the input manifest has a null, invalid, or 0 duration for the ad avail in those tags, MediaTailor uses the default. For DASH, MediaTailor obtains the duration value from the event duration, if one is specified. Otherwise, it uses the default value.
`[session.avail_duration_secs]`	Yes		The duration in seconds of the ad availability slot, or ad avail, rounded to the nearest second. MediaTailor determines this value the same way it determines `[session.avail_duration_ms]`.
`[session.client_ip]`	No		The remote IP address that the MediaTailor request came from. If the `X-forwarded-for` header is set, then that value is what MediaTailor uses for the `client_ip`.
`[session.id]`	No		A unique numeric identifier for the current playback session. All requests that a player makes for a session have the same id, so it can be used for ADS fields that are intended to correlate requests for a single viewing.
`[session.referer]`	No		Usually, the URL of the page that is hosting the video player. MediaTailor sets this variable to the value of the `Referer` header that the player used in its request to MediaTailor. If the player doesn't provide this header, MediaTailor leaves the `[session.referer]` empty. If you use a content delivery network (CDN) or proxy in front of the manifest endpoint and you want this variable to appear, proxy the correct header from the player here.
`[session.user_agent]`	No		The `User-Agent` header that MediaTailor received from the player's session initialization request. If you're using a CDN or proxy in front of the manifest endpoint, you must proxy the correct header from the player here.
`[session.uuid]`	No		Alternative to `[session.id]`. This is a unique identifier for the current playback session, such as the following: `e039fd39-09f0-46b2-aca9-9871cc116cde`

If the ADS requires a query parameter named deviceSession to be passed with the unique session identifier, the template ADS URL in AWS Elemental MediaTailor could look like the following:


https://my.ads.server.com/path?deviceSession=[session.id]

AWS Elemental MediaTailor automatically generates a unique identifier for each stream, and enters the identifier in place of session.id. If the identifier is 1234567, the final request that MediaTailor makes to the ADS would look something like this:


https://my.ads.server.com/path?deviceSession=1234567

If the ADS requires several query parameters to be passed, the template ADS URL in AWS Elemental MediaTailor could look like the following:


https://my.ads.server.com/sample?e=[scte.avails_expected]&f=[scte.segment_num]&g=[scte.segments_expected]&h=[scte.sub_segment_num]&j=[scte.sub_segments_expected]&k=[scte.segmentation_type_id]

The following DASH marker example XML fragment shows how to use scte35:SpliceInsert:


<Period start="PT444806.040S" id="123456" duration="PT15.000S">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="1350000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="180832" tier="4095">
        <scte35:SpliceInsert spliceEventId="1234567890" spliceEventCancelIndicator="false" outOfNetworkIndicator="true" spliceImmediateFlag="false" uniqueProgramId="1" availNum="1" availsExpected="1">
          <scte35:Program><scte35:SpliceTime ptsTime="5672624400"/></scte35:Program>
          <scte35:BreakDuration autoReturn="true" duration="1350000"/>
        </scte35:SpliceInsert>
      </scte35:SpliceInfoSection>

The following DASH marker example XML fragment shows how to use scte35:TimeSignal:


<Period start="PT346530.250S" id="123456" duration="PT61.561S">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="5310000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="183003" tier="4095">
        <scte35:TimeSignal>
          <scte35:SpliceTime ptsTime="3442857000"/>
        </scte35:TimeSignal>
        <scte35:SegmentationDescriptor segmentationEventId="1234567" segmentationEventCancelIndicator="false" segmentationDuration="8100000" segmentationTypeId="52" segmentNum="0" segmentsExpected="0">
          <scte35:DeliveryRestrictions webDeliveryAllowedFlag="false" noRegionalBlackoutFlag="false" archiveAllowedFlag="false" deviceRestrictions="3"/>
          <scte35:SegmentationUpid segmentationUpidType="12" segmentationUpidLength="2">0100</scte35:SegmentationUpid>
        </scte35:SegmentationDescriptor>
      </scte35:SpliceInfoSection>
    </Event>

The following DASH marker example XML fragment shows how to use scte35:Binary:


<Period start="PT444806.040S" id="123456" duration="PT15.000S">
  <EventStream schemeIdUri="urn:scte:scte35:2014:xml+bin" timescale="1">
    <Event presentationTime="1541436240" duration="24" id="29">
      <scte35:Signal xmlns="http://www.scte.org/schemas/35/2016">
        <scte35:Binary>/DAhAAAAAAAAAP/wEAUAAAHAf+9/fgAg9YDAAAAAAAA25aoh</Binary>
      </scte35:Signal>
    </Event>
    <Event presentationTime="1541436360" duration="24" id="30">
      <scte35:Signal xmlns="http://www.scte.org/schemas/35/2016">
        <scte35:Binary>QW5vdGhlciB0ZXN0IHN0cmluZyBmb3IgZW5jb2RpbmcgdG8gQmFzZTY0IGVuY29kZWQgYmluYXJ5Lg==</Binary>
      </scte35:Signal>
    </Event>

The following HLS tag example shows how to use EXT-X-DATERANGE:


#EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2014-03-05T11:
15:00Z",PLANNED-DURATION=59.993,SCTE35-OUT=0xFC002F0000000000FF0
00014056FFFFFF000E011622DCAFF000052636200000000000A0008029896F50
000008700000000

The following HLS tag example shows how to use EXT-X-CUE-OUT:


#EXT-OATCLS-SCTE35:/DA0AAAAAAAAAAAABQb+ADAQ6QAeAhxDVUVJQAAAO3/PAAEUrEoICAAAAAAg+2UBNAAANvrtoQ==  
#EXT-X-ASSET:CAID=0x0000000020FB6501  
#EXT-X-CUE-OUT:201.467

The following HLS tag example shows how to use EXT-X-SPLICEPOINT-SCTE35:


#EXT-X-SPLICEPOINT-SCTE35:/DA9AAAAAAAAAP/wBQb+uYbZqwAnAiVDVUVJAAAKqX//AAEjW4AMEU1EU05CMDAxMTMyMjE5M19ONAAAmXz5JA==

The following example shows how to use scte35:Binary decode:


{
  "table_id": 252,
  "section_syntax_indicator": false,
  "private_indicator": false,
  "section_length": 33,
  "protocol_version": 0,
  "encrypted_packet": false,
  "encryption_algorithm": 0,
  "pts_adjustment": 0,
  "cw_index": 0,
  "tier": "0xFFF",
  "splice_command_length": 16,
  "splice_command_type": 5,
  "splice_command": {
    "splice_event_id": 448,
    "splice_event_cancel_indicator": false,
    "out_of_network_indicator": true,
    "program_splice_flag": true,
    "duration_flag": true,
    "splice_immediate_flag": false,
    "utc_splice_time": {
      "time_specified_flag": false,
      "pts_time": null
    },
    "component_count": 0,
    "components": null,
    "break_duration": {
      "auto_return": false,
      "duration": {
        "pts_time": 2160000,
        "wall_clock_seconds": 24.0,
        "wall_clock_time": "00:00:24:00000"
      }
    },
    "unique_program_id": 49152,
    "avail_num": 0,
    "avails_expected": 0
    "segment_num": 0,
    "segments_expected": 0,
    "sub_segment_num": 0,
    "sub_segments_expected": 0
  },
  "splice_descriptor_loop_length": 0,
  "splice_descriptors": null,
  "Scte35Exception": {
    "parse_status": "SCTE-35 cue parsing completed with 0 errors.",
    "error_messages": [],
    "table_id": 252,
    "splice_command_type": 5
  }
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Using domain variables

Using player variables