Naming third-party components

May 17, 2021 · View on GitHub

AMP differentiates between "first-party" and "third-party" components:

  • First-party components are those that work independently, regardless of a specific external service. These are generic. These are first-party components:

    • <amp-sidebar>
    • <amp-list>
    • <amp-iframe>[1]
    • etc.

  • Third-party components are those that embed functionality provided by a service separate from the AMP runtime, usually through an embedded <iframe>. These always depend on the same specific service. These are third-party components:

    • <amp-facebook>
    • <amp-gfycat>
    • <amp-subscriptions-google>
    • etc.

The goal of these guidelines is to disambiguate between first and third-party components through their names, so that a component provided by a third-party service is not confused with a generic one.

Guideline 1: Third party components must contain a brand name

Since third-party services are usually bundled as a product, the component must contain its associated brand name:

  • ✅ This is OK: <amp-facebook-comments>
  • ❌ This is not OK: <amp-comments>

Exception: Brand name may be confused with a component that's generic

Let's imagine a service named Toast.io. Regardless of what the service provides, naming a component for this service "<amp-toast>" would be bad, since it can be confused for the generic term for a "toast" component. In this case, the name must communicate that it's a third-party embed:

  • ❌ This is not OK: <amp-toast>
  • ✅ This is OK: <amp-embed-toast>
  • ✅ This is OK: <amp-toast-io>

Guideline 2: Media players must be named as such

Names for third-party products may fail to communicate their purpose, so all media player names (like a video or audio player) must end with -player. This provides an affordance by convention: third-party media player components are always annotated as such.[2]

Let's imagine a video provider named UltraVideo:

  • ❌ This is not OK: <amp-ultra-video>
  • ✅ This is OK: <amp-ultra-video-player>
  • ✅ This is even better: <amp-ultra-video-embed-player>

1 Why are <amp-iframe> or <amp-video-iframe> considered first-party?

The URL that these components embed is interchangeable, since their src attribute is configurable by the page's author to point to any third-party endpoint, or the author's own endpoint.

2 Why is <amp-youtube> not suffixed like <amp-youtube-player>?

Several media player components names lack the -player prefix, like <amp-youtube> and all those the apply in the video player list. These were historically created before this guideline.