# Enabling overlay ads
<a name="overlay-ads-getting-started-enabling"></a>

MediaTailor support for overlay ads is enabled by default. A specific SCTE-35 ad-marker type in the manifest triggers the insertion of an overlay ad. Because some players might not support client-side rendering of overlay ads, you can disable the feature at the session level.

**To disable overlay-ad support using HLS or DASH playback prefixes:**
+ From the player, initialize a new MediaTailor playback session using a request in one of the following formats, according to your protocol:
  + Example: HLS format

    ```
    GET mediatailorURL/v1/master/hashed-account-id/origin-id/asset-id?aws.overlayAvails=off
    ```
  + Example: DASH format

    ```
    GET mediatailorURL/v1/master/hashed-account-id/origin-id/asset-id?aws.overlayAvails=off
    ```

**To disable overlay-ad support using the session-initialization prefix:**
+ On the player, construct a JSON message body for the session initialization request to MediaTailor:
  + To disable ad-overlay support, add an `overlays` object as a top-level key with a value of `off`. The default `overlays` value is `on`.
  + (Optional) Provide any parameters that MediaTailor then passes to the ADS inside an `adsParams` object. These parameters correspond to `[player_params.param]` settings in the ADS template URL of the MediaTailor configuration.

**Example : HLS**  

```
POST master.m3u8
    {
       "adsParams": {
           "deviceType": "ipad"
       },
       "overlayAvails": "off"
    }
```

**Example : DASH**  

```
POST manifest.mpd
    {
        "adsParams": {
           "deviceType": "androidmobile"
       },
       "overlayAvails": "off"
    }
```

# Manifest signaling
<a name="overlay-ads-manifest-signaling"></a>

MediaTailor trigger overlay-ads support when it sees a specific SCTE-35 marker in the manifest. The required signal is a splice command type 6, or time signal, that is a Provider Overlay Advertisement Start signal. This signal has a segmentation type id of `0x38`

The following example shows the `0x38` SCTE-35 marker in a JSON object.

```
{
  "tableId": 252,
  "selectionSyntaxIndicator": false,
  "privateIndicator": false,
  "sectionLength": 53,
  "protocolVersion": 0,
  "encryptedPacket": false,
  "encryptedAlgorithm": 0,
  "ptsAdjustment": 0,
  "cwIndex": 0,
  "tier": 4095,
  "spliceCommandLength": 5,
  "spliceCommandType": 6,
  "spliceCommand": {
    "specified": true,
    "pts": 1800392
  },
  "descriptorLoopLength": 31,
  "descriptors": [
    {
      "spliceDescriptorTag": 2,
      "descriptorLength": 29,
      "indentifier": "CUEI",
      "segmentationEventId": 158389361,
      "segmentationEventCancelIndicator": false,
      "programSegmentationFlag": true,
      "segmentationDurationFlag": true,
      "deliveryNotRestrictedFlag": false,
      "webDeliveryAllowedFlag": true,
      "noRegionalBlackoutFlag": true,
      "archiveAllowedFlag": true,
      "deviceResctrictions": 3,
      "segmentationDuration": 1350000,
      "segmentationUpidType": 9,
      "segmentationUpidLength": 7,
      "segmentationUpid": {
        "0": 111,
        "1": 118,
        "2": 101,
        "3": 114,
        "4": 108,
        "5": 97,
        "6": 121
      },
      "segmentationTypeId": 56,
      "segmentNum": 1,
      "segmentsExpected": 0
    }
  ],
  "crc": 2510422713
}
```

The following example shows the SCTE-35 signal represented as a binary (base 32/hexadecimal) value:

```
0xfc303500000000000000fff00506fe001b78c8001f021d435545490970d4717fdf00000dbba009076f7665726c6179380100000084226c4f
```

The following examples shows the SCTE-35 marker in both HLS and DASH manifests.

**Example : HLS manifest**  

```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:419
#EXT-X-DISCONTINUITY-SEQUENCE:3
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:09.231Z
#EXTINF:6.02,
https://aws.cloudfront.net/media/asset1/index1_00007.ts
#EXT-X-DISCONTINUITY
#EXT-X-KEY:METHOD=NONE
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:15.251Z
#EXTINF:6.0,
https://aws.cloudfront.net/media/asset1/index1_00001.ts
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:21.251Z
#EXTINF:4.0,
https://aws.cloudfront.net/media/asset1/index1_00002.ts
#EXT-X-DISCONTINUITY
#EXT-X-DATERANGE:ID="1692073825251-30-1",START-DATE="2023-08-15T04:30:25.251Z",DURATION=10.0,PLANNED-DURATION=10.0,SCTE35-OUT=0xfc303500000000000000fff00506fe001b78c8001f021d435545490970d4717fdf00000dbba009076f7665726c6179380100000084226c4f
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:25.251Z
#EXTINF:2.0,
https://aws.cloudfront.net/media/asset1/index1_00003.ts
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:27.251Z
#EXTINF:6.0,
https://aws.cloudfront.net/media/asset1/index1_00004.ts
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:33.251Z
#EXTINF:2.0,
https://aws.cloudfront.net/media/asset1/index1_00005.ts
#EXT-X-DISCONTINUITY
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:35.251Z
#EXTINF:4.0,
https://aws.cloudfront.net/media/asset1/index1_00006.ts
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:39.251Z
#EXTINF:6.02,
https://aws.cloudfront.net/media/asset1/index1_00007.ts
```

**Example : DASH manifest**  

```
<?xml version="1.0"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" availabilityStartTime="2023-08-15T16:34:05.911Z" minBufferTime="PT30S" minimumUpdatePeriod="PT2S" profiles="urn:mpeg:dash:profile:isoff-live:2011" publishTime="2023-08-15T16:34:17.950Z" suggestedPresentationDelay="PT20S" timeShiftBufferDepth="PT1M30S" type="dynamic" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd">
  <Period xmlns="urn:mpeg:dash:schema:mpd:2011" id="1692117245944_1" start="PT0.033S">
    <BaseURL>https://aws.cloudfront.net/out/v1/abc/123/def/</BaseURL>
    <EventStream schemeIdUri="urn:scte:scte35:2013:xml" timescale="90000">
      <Event duration="900000">
        <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="0" tier="4095">
          <scte35:TimeSignal>
            <scte35:SpliceTime ptsTime="0"/>
          </scte35:TimeSignal>
          <scte35:SegmentationDescriptor segmentNum="0" segmentationDuration="900000" segmentationEventCancelIndicator="false" segmentationEventId="1" segmentationTypeId="56" segmentsExpected="0" subSegmentNum="0" subSegmentsExpected="0">
            <scte35:SegmentationUpid segmentationUpidFormat="hexBinary" segmentationUpidType="14">63736f7665726c6179</scte35:SegmentationUpid>
          </scte35:SegmentationDescriptor>
        </scte35:SpliceInfoSection>
      </Event>
    </EventStream>
    <AdaptationSet bitstreamSwitching="true" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
      <Representation bandwidth="3000000" codecs="avc1.4D4028" frameRate="30/1" height="1080" id="1" width="1920">
        <SegmentTemplate initialization="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_1_0_init.mp4" media="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_1_0_$Number$.mp4" presentationTimeOffset="0" startNumber="1" timescale="30000">
          <SegmentTimeline>
            <S d="60000" r="6" t="1000"/>
            <S d="30000" t="421000"/>
          </SegmentTimeline>
        </SegmentTemplate>
      </Representation>
      <Representation bandwidth="2499968" codecs="avc1.4D4028" frameRate="30/1" height="1080" id="2" width="1920">
        <SegmentTemplate initialization="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_2_0_init.mp4" media="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_2_0_$Number$.mp4" presentationTimeOffset="0" startNumber="1" timescale="30000">
          <SegmentTimeline>
            <S d="60000" r="6" t="1000"/>
            <S d="30000" t="421000"/>
          </SegmentTimeline>
        </SegmentTemplate>
      </Representation>
      <Representation bandwidth="2200000" codecs="avc1.4D401F" frameRate="30/1" height="720" id="3" width="1280">
        <SegmentTemplate initialization="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_3_0_init.mp4" media="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_3_0_$Number$.mp4" presentationTimeOffset="0" startNumber="1" timescale="30000">
          <SegmentTimeline>
            <S d="60000" r="6" t="1000"/>
            <S d="30000" t="421000"/>
          </SegmentTimeline>
        </SegmentTemplate>
      </Representation>
    </AdaptationSet>
    <AdaptationSet lang="eng" mimeType="audio/mp4" segmentAlignment="0">
      <Label>Alternate Audio</Label>
      <Representation audioSamplingRate="48000" bandwidth="128000" codecs="mp4a.40.2" id="9">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
        <SegmentTemplate initialization="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_audio_9_0_init.mp4" media="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_audio_9_0_$Number$.mp4" presentationTimeOffset="0" startNumber="1" timescale="48000">
          <SegmentTimeline>
            <S d="98304" t="0"/>
            <S d="96256" t="98304"/>
            <S d="95232" t="194560"/>
            <S d="96256" r="2" t="289792"/>
            <S d="95232" t="578560"/>
            <S d="46080" t="673792"/>
          </SegmentTimeline>
        </SegmentTemplate>
      </Representation>
    </AdaptationSet>
  </Period>
</MPD>
```

# Ad Decision Server (ADS) response
<a name="overlay-ads-ads-response"></a>

The ADS response must contain one valid tracking event. At minimum, the tracking event can be an `Impression` tracking event. The tracking event should contain at least one `NonLinear` ad. This ad is the overlay ad, taking the form of a static, HTML, or iFrame resource.

```
<vmap AdBreak breaktype="linear" breakId="csoverlay"
```

If the VAST response is a VMAP with `breakType` of `nonlinear`, the avail metadata is inside the `nonLinearAvails` root object. If the VAST response is a VMAP with a `breakType` of `linear`, or is a plain VAST response without VMAP, the avail metadata is inside the `avails` root object.

The following VAST response is a wrapped VMAP response with a `breakType` value of `linear`.

In addition to the wrapped VMAP response, MediaTailor also supports a wrapped VMAP response with a `breakType` value of `nonlinear`, and a plain VAST response.

```
<?xml version="1.0" encoding="utf-8"?>
<vmap:VMAP xmlns:vmap="http://www.iab.net/vmap-1.0" version="1.0">
  <vmap:AdBreak breakType="linear" breakId="csoverlay">
    <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="1">
      <vmap:VASTAdData>
        <VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.0" xsi:noNamespaceSchemaLocation="vast.xsd">
          <Ad sequence="1">
            <InLine>
              <AdSystem>2.0</AdSystem>
              <AdTitle>2</AdTitle>
              <Impression><![CDATA[https://adserver.com/beacon=impression]]></Impression>
              <Creatives>
                <Creative>
                  <NonLinearAds>
                    <NonLinear width="640" height="360" id="18">
                      <StaticResource creativeType="text/js_ref"><![CDATA[https://client-side-ads.com/tags/static/ctv-generic/overlay001.json?iv_geo_country%3DUS%26]]></StaticResource>
                    </NonLinear>
                  </NonLinearAds>
                </Creative>
              </Creatives>
            </InLine>
          </Ad>
        </VAST>
      </vmap:VASTAdData>
    </vmap:AdSource>
    <vmap:TrackingEvents>
      <vmap:Tracking event="breakStart"><![CDATA[https://adserver.com/beacon=breakstartimpression]]></vmap:Tracking>
      <vmap:Tracking event="breakEnd"><![CDATA[https://adserver.com/beacon=breakendimpression]]></vmap:Tracking>
    </vmap:TrackingEvents>
  </vmap:AdBreak>
</vmap:VMAP>
```

**Example 1: DASH manifest source to MediaTailor**  

```
<?xml version="1.0" encoding="utf-8"?>
<MPD xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd" id="201" type="dynamic" publishTime="2022-11-07T19:59:05+00:00" minimumUpdatePeriod="PT2S" availabilityStartTime="2022-11-07T06:57:11.250000+00:00" minBufferTime="PT10S" suggestedPresentationDelay="PT20.000S" timeShiftBufferDepth="PT58.999S" profiles="urn:mpeg:dash:profile:isoff-live:2011">
  <Period start="PT46827.601S" id="0" duration="PT88.321S">
  ...
  </Period>
  <Period start="PT46915.922S" id="45" duration="PT6.006S">
    <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2014:xml+bin">
    <Event duration="540000" id="144">
        <scte35:Signal>
            <scte35:Binary>SCTE35-binary</scte35:Binary>
        </scte35:Signal>
    </Event>
    </EventStream>
    ... 
  </Period>
  <Period start="PT46921.928S" id="49"> 
  ...
  </Period>
</MPD>
```

**Example 2: MediaTailor personalized DASH manifest containing an ad ID decoration**  

```
<?xml version="1.0" encoding="utf-8"?>
<MPD xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd" id="201" type="dynamic" publishTime="2022-11-07T19:59:05+00:00" minimumUpdatePeriod="PT2S" availabilityStartTime="2022-11-07T06:57:11.250000+00:00" minBufferTime="PT10S" suggestedPresentationDelay="PT20.000S" timeShiftBufferDepth="PT58.999S" profiles="urn:mpeg:dash:profile:isoff-live:2011">
  <Period start="PT46827.601S" id="0" duration="PT88.321S">
  ...
  </Period>
  <Period start="PT46915.922S" id="45" duration="PT6.006S">
  <EventStream schemeIdUri="urn:sva:advertising-wg:ad-id-signaling" timescale="90000">
    <Event presentationTime="13500000" duration="1351350">
    <![CDATA[{"version": 1,"identifiers": [{"scheme": "urn:smpte:ul:060E2B34.01040101.01200900.00000000","value": "adId","ad_position": "adId", "ad_type":"overlay","creative_id": "creativeId","tracking_uri": "trackingUri"}]}]]></Event>
  </EventStream>
  ...
  </Period>
  <Period start="PT46921.928S" id="49"> 
  ...
  </Period>
</MPD>
```