amp-story-shopping

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

Use amp-story-shopping to create configurable, templated shopping experiences within amp-story.

amp-story-shopping is defined in the document using its two custom elements, amp-story-shopping-attachment and amp-story-shopping-tag.

Specify a shopping experience by defining one amp-story-shopping-attachment and one or more amp-story-shopping-tag elements for each product on the amp-story-page.

amp-story-shopping-tag

Use amp-story-shopping-tag elements to indicate shop-able elements within amp-story-page.

Tapping them opens a product details page (PDP) within the amp-story-shopping-attachment.

They must be a child of amp-story-grid-layer.

They are positioned absolute. Use custom CSS to place them on the page using top and left with percentage based units for a responsive layout.

...
<style amp-custom>
  [data-product-id="product1"] {
    top: 30%;
    left: 30%;
  }
</style>
...
<amp-story-grid-layer template="vertical">
  <amp-story-shopping-tag data-product-id="product1"></amp-story-shopping-tag>
</amp-story-grid-layer>

Example of positioning an amp-story-shopping-tag and testing responsiveness:

amp-story-shopping-tag attributes

data-product-id {string} required

Associates the amp-story-shopping-tag with product data. Must be equal to the productId value of the associated product's JSON data.

Customization

Custom icon

A shopping tag icon renders by default. You may replace the default shopping tag icon with a custom icon by specifying a url to a jpg or png as the productIcon value in the associated product's JSON data. Recommended image size is 48 x 48px;

Custom text

The item's price renders by default. You may replace the default text with custom text by defining productTagText in the associated product's JSON data. A maximum of two lines will display. Ellipses will display if the text is too long.

Diagram demonstrating how product JSON renders within amp-story-shopping-tag:

amp-story-shopping-attachment

The amp-story-shopping-attachment renders a tappable CTA button with the text "Shop now" that opens an inline shopping experience. Product JSON data must be configured and at least one amp-story-shopping-tag must be on the same page.

Product JSON configuration

Product JSON is configured inline as a child script tag. An optional src attribute will fetch data from an endpoint at render time. If src is defined it overrides the inline configuration.

Using src with inline JSON as a fallback is recommended. Inline data may be served from cache which may take time to propogate. src JSON is fetched at time of render which ensurs it is up-to-date.

{
   items: [
      {
         productUrl: "...", // Required. String. Links to the products website.
         productId: "..." // Required. Keys to amp-story-shopping-tag nodes.
         productBrand: "...", // Optional. String.
         productIcon: "...", // Optional. Links to an image. Defaults to a shopping bag icon.
         productTitle: "...", // Required. String.
         productPrice: 100, // Required. Number.
         productPriceCurrency: "..." // Required. String. ISO 4217 currency code used to display the correct currency symbol.
         productImages: [ // Required. Must have at least one entry. Array of objects.
            {
               url: "..." // Required. String.
               altText: "..." // Required. String.
            }
         ],
         productDetails: "...", // Required. String.
         aggregateRating: { // Optional. All sub fields are required if defined.
            "ratingValue": 4.4, // Required. Number.
            "reviewCount": 89, // Required. Number.
            "reviewUrl": // Required. String. Links to page where user can read reviews.
         }
      }
   ]
}

Product JSON schema

See the schema for product JSON validation in product.schema.json. If validation fails on one or more of the shopping tags, an error message will be displayed, and the tag and product details / listing associated with the product(s) that have errors will not be rendered. Validation is performed with ajv using the default ajv JSON schema draft.

amp-story-shopping-attachment attributes

src {string} optional

A url for remote product JSON configuration. When defined it overrides inline JSON configuration.

theme {string} optional

Sets the color of the CTA button and drawer. "light" (default) and "dark" values are accepted.

cta-text {string} optional

String that customizes the call to action button text. The default is "Shop now".

amp-story-shopping-attachment templates

Two types of templated pages render within the shopping attachment. They automatically populate with the product data from the configured JSON. the Product listing page (PLP) is a list of all products on the active story page. The Product details page (PDP) displays in-depth detail about the product such as images, text and a "Buy now" button.

Product listing page (PLP)

The PLP template renders a list of products on the active amp-story-page. Open it by tapping the "Shop now" CTA button that automatically displays on the bottom of the page when the shopping experience is configured. At least two associated amp-story-shopping-tag elements must be on the page for the PLP render.

Diagram demonstrating how product JSON renders within the PLP template:

Product details page (PDP)

The PDP template displays detailed information about a product. Tapping an amp-story-shopping-tag or the product's card within the PLP will open the product's PDP. If only one product is on the page the PDP will render by default when tapping the "Shop now" CTA button.

Diagram demonstrating how product JSON renders within the PDP template:

Validation

See validation rules in amp-story-shopping validator.