AMP

Important: this documentation is not applicable to your currently selected format email!

amp-story-auto-ads

Description

Dynamically inserts ads into a Story.

 

Required Scripts

<script async custom-element="amp-story-auto-ads" src="https://cdn.ampproject.org/v0/amp-story-auto-ads-0.1.js"></script>

Dynamically inserts ads into a Story.

Getting Started

For information on how to include ads in your AMP Stories, refer to our guide.

Best practices for creating an AMP Story ad

If you are interested in creating an ad for the AMP Story platform, refer to our best practices guide.

Behavior

amp-story-auto-ads extension dynamically inserts ads (implemented as amp-ad) into the story while content is being consumed by the user. The current algorithm expects at least a story containing 7 pages.

Each amp-ad is inserted as a full screen story page. To prevent showing blank/unloaded ads, the ad is pre-rendered completely in the background before making it visible to the user. Based on user interactions, the extension decides when and where to insert ads.

Ad in story can be skipped the same way as normal story pages by tapping on the right part of the screen.

Configuration

There are two ways of configuring an ad: Inline and Remote

Inline Ad Config

In the <amp-story-auto-ads> element, you specify a JSON configuration object that contains the details for how ads should be fetched and displayed, which looks like the following:

<amp-story>
  <amp-story-auto-ads>
    <script type="application/json">
      {
        "ad-attributes": {
          "type": "doubleclick",
          "data-slot": "/30497360/a4a/amp_story_dfp_example"
        }
      }
    </script>
  </amp-story-auto-ads>
  ...
</amp-story>

ad-attributes is a map of key-value pairs, which are the attributes of the amp-ad element to be inserted.

The above example will insert the following amp-ad element, which represents a ad served by doubleclick:

<amp-ad type="doubleclick" data-slot="/30497360/a4a/amp_story_dfp_example">
</amp-ad>

Unlike normal amp-ad, no <fallback> or <placeholder> needs to be specified here, as ads in stories will only be displayed once fully rendered.

Remote Ad Config

Instead of adding in the JSON configuration file inside a script tag (as shown in the Inline Ad Config section), One may also host the remote URL using a

Remote JSON ad configuration file

{
  "ad-attributes": {
    "type": "doubleclick",
    "data-slot": "/30497360/a4a/amp_story_dfp_example"
  }
}

Once you have your JSON configuration file setup, simply use the

html ad config code to retrive the remote URL:

in the <amp-story-auto-ads> element as shown here:

<amp-story standalone supports-landscape>
    <!--
      This is an example of JSON retrieved from a source file.
    -->
    <amp-story-auto-ads src="/examples/amp-story/ads/remote.json" ></amp-story-auto-ads>
    <amp-story-page id="page-1">
    .
    .
    .
</amp-story>

Passing additional attributes (RTC, Targeting, etc.)

If you wish to pass any additional data (e.g. targeting information) as attributes to the created <amp-ad> tag, simply add the additional key value pairs to the ad-attributes JSON object.

A common use case is to pass targeting data or RTC configuration to the underlying amp-ad element. A more complex configuration may look something like this:

<amp-story-auto-ads>
  <script type="application/json">
    {
      "ad-attributes": {
        "type": "doubleclick",
        "data-slot": "/30497360/a4a/amp_story_dfp_example",
        "rtc-config": {
          "urls": ["https://rtcEndpoint.biz/"]
        },
        "json": {
          "targeting": {
            "loc": "usa",
            "animal": "cat"
          },
          "categoryExclusions": ["sports", "food", "fun"]
        }
      }
    }
  </script>
</amp-story-auto-ads>

This would result in creation of the following amp-ad element.

<amp-ad
  type="doubleclick"
  data-slot="/30497360/a4a/amp_story_dfp_example"
  rtc-config='{"urls": ["https://rtcEndpoint.biz/"}'
  json='{"targeting":{"loc": "usa", "animal": "cat"}, "categoryExclusions":["sports", "food", "fun"]}'
>
</amp-ad>

Validation

amp-story-auto-ads must be a direct child of amp-story element.

Insertion Control

If there is a specific position in a story that you wish to never show an ad, you can add the next-page-no-ad attribute an <amp-story-page>. The insertion algorithm will then skip the slot after this page when trying to insert an ad.

<amp-story-page next-page-no-ad id="page-7">
  ...
</amp-story-page>

<!-- No ad will ever be inserted here. -->

<amp-story-page next-page-no-ad id="page-8">
  ...
</amp-story-page>

Analytics

When using amp-story-auto-ads several new analytics triggers and [variables] will be available for your analytics configuration.

Triggers

Name Event
story-ad-request An ad is requested.
story-ad-load An ad is loaded.
story-ad-insert An ad is inserted.
story-ad-view An ad is viewed.
story-ad-click An ad's CTA button has been clicked.
story-ad-exit A user stops looking at an ad.
story-ad-discard An ad is discarded due to invalid configuration.

Variables

The following variables will be avaiable in roughly sequential order. The variables can then be used in any following pings. For instance, a request using the story-ad-load trigger will not have access to the viewTime variable as it has not happened yet (this will resolve to an empty string). Whereas a request sent using the story-ad-exit trigger would be able to get the value of all the previous events (requestTime, loadTime, insertTime etc.)

Name Definition
adIndex Index of the ad generating the trigger (available for all triggers)
adUniqueId Id that should be unique for every ad (available for all triggers)
requestTime Timestamp when ad is requested
loadTime Timestamp when ad emits INI_LOAD signal
insertTime Timestamp when ad is inserted into story
viewTime Timestamp when ad-page becomes active page
clickTime Timestamp when ad is clicked
exitTime Timestamp when ad page moves from active => inactive
discardTime Timestamp when ad is discared due to bad metadata etc.
position Position in the parent story. Number of page before ad + 1. Does not count previously inserted ad pages. (avaiable at insertion)
ctaType Given cta-type of inserted ad (avaiable at insertion)
도움이 더 필요하신가요?

이 문서를 수십 번 읽었음에도 여전히 궁금한 점이 남아 있나요? 다른 개발자들도 같은 심정일지 모릅니다. Stack Overflow에서 소통해 보세요.

Stack Overflow로 이동
버그나 누락된 기능을 발견하셨나요?

AMP 프로젝트는 여러분의 참여와 기여를 적극 환영합니다! 오픈 소스 커뮤니티를 통해 지속적으로 활동해 주셔도 좋지만 관심 있는 주제에 한 번만 기여하셔도 큰 도움이 됩니다.

GitHub로 이동하기