# Overlay ads
<a name="overlay-ads"></a>

For live-streaming workflows where you want to increase monetization without interrupting the viewing experience with mid-roll ads, you can leverage your current AWS Elemental MediaTailor integration to guide an advertising format that is rendered client-side. This type of advertising is known as *overlay ads*. Overlay ads are non-linear video ads that appear in the form of 'L-band ads,' 'non-linear video ads,' 'picture-in-picture ads,' 'motion overlays', 'in-content advertising', or 'frame ads.'

MediaTailor detects a SCTE-35 marker with segmentation type `id=0x38` as an in-band signal for an overlay ad-insertion opportunity. The SCTE-35 marker causes MediaTailor to send a request to the Ad Decision Server (ADS), which then responds with a non-linear ad payload in the VAST response. MediaTailor parses the VAST response in order to support overlay ad insertion. MediaTailor does not perform any stitching of linear ads, but rather signals to the player that there's a non-linear overlay ad available to play. This signaling allows the player to fetch and correlate the non-linear ads to play from the client-side tracking endpoint. The player then handles the display, reporting, and other tasks related to those ads. For example, the player's developer can use a device SDK from a vendor that supports overlay-ad formats. For more information about client-side tracking integrations, see [Client-side ad-tracking integrations](ad-reporting-client-side-ad-tracking-integrations.md).

![\[The image depicts a timeline of various ad types displayed alongside a content video. Linear ads play before and after the content video. The ad before the content video is called a pre-roll ad. The ad after the content video is called a post-roll ad. A non-linear ad overlaps a portion of the content video itself. The non-linear ad is called an overlay ad.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/client-side-overlays.png)


**Topics**
+ [Prerequisites for using overlay ads with MediaTailor](overlay-ads-prerequisites.md)
+ [Getting started using overlay ads with MediaTailor](overlay-ads-getting-started.md)
+ [Logging and metrics for overlay ads in MediaTailor](overlay-ads-logging-and-metrics.md)
+ [Billing for overlay ads in MediaTailor](overlay-ads-billing.md)

# Prerequisites for using overlay ads with MediaTailor
<a name="overlay-ads-prerequisites"></a>

The following prerequisites apply when using overlay ads with MediaTailor:
+ The workflow must be live, not video on demand (VOD).
+ The Ad Decision Server (ADS) response must be configured to return only non-linear ads in the VAST response. MediaTailor ignores any linear ads for the purposes of ad stitching.
+ The manifest must use a SCTE-35 time signal message with segmentation type `id=0x38` to invoke the overlay-ad feature.
+ The streaming provider must have control of the client-device application and be integrated with the MediaTailor client-side tracking API.

# Getting started using overlay ads with MediaTailor
<a name="overlay-ads-getting-started"></a>

This section explains how to get started using the overlay-ads feature of MediaTailor. You'll set up SCTE-35 signaling, configure Ad Decision Server (ADS) responses, and set up session-level control.

**Topics**
+ [Enabling overlay ads](overlay-ads-getting-started-enabling.md)
+ [Tracking overlay ads with client-side metadata](overlay-ads-client-side-tracking-metadata.md)

# 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>
```

# Tracking overlay ads with client-side metadata
<a name="overlay-ads-client-side-tracking-metadata"></a>

MediaTailor places the overlay ads in the `nonLinearAdsList` of the avail. The MediaTailor client-side tracking API has two root objects, called `avails` and `nonLinearAvails`. 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.

For more information about client-side tracking, see [Client-side ad tracking](ad-reporting-client-side.md).

The following example shows a plain VAST response or VMAP response with a `breakType` value of `linear`.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [
        {
          "beaconUrls": [
            "https://adserver.com/beacon=breakstartimpression"
          ],
          "eventType": "breakStart"
        },
        {
          "beaconUrls": [
            "https://adserver.com/beacon=breakendimpression"
          ],
          "eventType": "breakEnd"
        }
      ],
      "adMarkerDuration": null,
      "ads": [],
      "availId": "828",
      "availProgramDateTime": null,
      "duration": "PT0S",
      "durationInSeconds": 0,
      "meta": null,
      "nonLinearAdsList": [
        {
          "extensions": null,
          "nonLinearAdList": [
            {
              "adId": "",
              "adParameters": null,
              "adSystem": "2.0",
              "adTitle": "2",
              "apiFramework": null,
              "clickThrough": null,
              "clickTracking": null,
              "clickTrackingId": null,
              "creativeAdId": "",
              "creativeId": "18",
              "creativeSequence": "",
              "duration": null,
              "durationInSeconds": 0,
              "expandedHeight": null,
              "expandedWidth": null,
              "height": "360",
              "htmlResource": null,
              "iFrameResource": null,
              "maintainAspectRatio": false,
              "minSuggestedDuration": null,
              "scalable": false,
              "staticResource": "https://client-side-ads.com/tags/static/ctv-generic/overlay001.json?iv_geo_country%3DUS%26",
              "staticResourceCreativeType": "text/js_ref",
              "width": "640"
            }
          ],
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://adserver.com/beacon=impression"
              ],
              "duration": null,
              "durationInSeconds": 0,
              "eventId": null,
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": null,
              "startTimeInSeconds": 0
            }
          ]
        }
      ],
      "startTime": "PT1M46.08S",
      "startTimeInSeconds": 106.08
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": null,
  "nonLinearAvails": []
}
```

The following example shows a plain VMAP response with a `breakType` value of `nonlinear`.

```
{
  "avails": [],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": null,
  "nonLinearAvails": [
    {
      "adBreakTrackingEvents": [
        {
          "beaconUrls": [
            "https://adserver.com/beacon=breakstartimpression"
          ],
          "eventType": "breakStart"
        },
        {
          "beaconUrls": [
            "https://adserver.com/beacon=breakendimpression"
          ],
          "eventType": "breakEnd"
        }
      ],
      "adMarkerDuration": null,
      "ads": [],
      "availId": "828",
      "availProgramDateTime": null,
      "duration": "PT0S",
      "durationInSeconds": 0,
      "meta": null,
      "nonLinearAdsList": [
        {
          "extensions": null,
          "nonLinearAdList": [
            {
              "adId": "",
              "adParameters": null,
              "adSystem": "2.0",
              "adTitle": "2",
              "apiFramework": null,
              "clickThrough": null,
              "clickTracking": null,
              "clickTrackingId": null,
              "creativeAdId": "",
              "creativeId": "18",
              "creativeSequence": "",
              "duration": null,
              "durationInSeconds": 0,
              "expandedHeight": null,
              "expandedWidth": null,
              "height": "360",
              "htmlResource": null,
              "iFrameResource": null,
              "maintainAspectRatio": false,
              "minSuggestedDuration": null,
              "scalable": false,
              "staticResource": "https://client-side-ads.com/tags/static/ctv-generic/overlay001.json?iv_geo_country%3DUS%26",
              "staticResourceCreativeType": "text/js_ref",
              "width": "640"
            }
          ],
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://adserver.com/beacon=impression"
              ],
              "duration": null,
              "durationInSeconds": 0,
              "eventId": null,
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": null,
              "startTimeInSeconds": 0
            }
          ]
        }
      ],
      "startTime": "PT1M46.08S",
      "startTimeInSeconds": 106.08
    }
  ]
}
```

# Logging and metrics for overlay ads in MediaTailor
<a name="overlay-ads-logging-and-metrics"></a>

This section explains logging and metrics for overlay ads in MediaTailor. For more information about setting up logging, see [Monitoring and tagging AWS Elemental MediaTailor resources](monitoring.md).

**Topics**
+ [CloudWatch logs](#overlay-ads-logging-and-metrics-cloudwatch)
+ [CloudWatch metrics](#overlay-ads-logging-and-metrics-cloudwatch-metrics)

## CloudWatch logs
<a name="overlay-ads-logging-and-metrics-cloudwatch"></a>

CloudWatch collects the following log information about overlay ads:
+ `VAST_RESPONSE` - Shows information about the non-linear ads list.
+ `FILLED_PROVIDER_OVERLAY` - Shows information about the non-linear ads.

**Note**  
The `RAW_ADS_RESPONSE` is an optional event that shows the original response from the ADS. Using this event is especially helpful in a staging and testing environment. To enable this event on a configuration or account, submit a ticket to AWS Support.

## CloudWatch metrics
<a name="overlay-ads-logging-and-metrics-cloudwatch-metrics"></a>

MediaTailor collects overlay ad metrics separately from other ADS metrics. MediaTailor collects these metrics after successfully fetching the ads from the ADS. You don't have to poll the `GetTracking` API to collect the metrics.

The following table describes CloudWatch metrics for overlay ads:


| Metric | Description | 
| --- | --- | 
| AdDecisionServer.OverlayAds |  The count of overlay ads included in the ADS responses within the CloudWatch time period that you specified.  | 
| AdDecisionServer.OverlayErrors |  The number of non-HTTP `200` status code responses, empty responses, and timed-out responses that MediaTailor received from the ADS within the CloudWatch time period that you specified.  | 
| AdDecisionServer.OverlayFilled |  The number of avails that were successfully filled with at least one overlay ad: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/overlay-ads-logging-and-metrics.html) `SampleCount` tracks the number of avails filled. `Sum` tracks the number of successfully filled overlay avails.  | 
| AdDecisionServer.OverlayMinSuggestedDuration |  The sum of `minSuggestedDuration` durations, in milliseconds, of all ads that MediaTailor received from the ADS within the CloudWatch time period that you specified. If `minSuggestedDuration` isn't specified, the duration shown is the planned duration.  | 
| AdDecisionServer.OverlayLatency |  The response time, in milliseconds, for requests that MediaTailor makes to the ADS.  | 
| AdDecisionServer.OverlayTimeouts |  The number of timed-out requests to the ADS in the CloudWatch time period that you specified.  | 
| AdsBilled |  For more information about ads billed, see [Billing for overlay ads in MediaTailor](overlay-ads-billing.md).  | 
| Avail.\$1 |  Because MediaTailor doesn't do any planning for overlay ads, CloudWatch doesn't show any `Avail.X` metrics.  | 
| SkippedReason.\$1 |  Because MediaTailor doesn't do any planning for overlay ads, CloudWatch doesn't show any `SkippedReason.X` metrics.  | 

# Billing for overlay ads in MediaTailor
<a name="overlay-ads-billing"></a>

MediaTailor bills customers based on the number of non-linear ads in the ADS response. This number includes non-linear ads that extend past the break duration. After MediaTailor fills the avail, it bills for the ads it filled.

For prefetch workflows, MediaTailor does not bill for ads when retrieving the prefetch, but rather, when it sees a compatible ad avail in the consumption window for that session.

For additional billing information, see [https://aws.amazon.com/mediatailor/pricing/](https://aws.amazon.com/mediatailor/pricing/).