AMP
EN
Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

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

amp-app-banner

Description

A wrapper and minimal UI for a cross-platform, fixed-position banner showing a call-to-action to install an app.

 

Required Scripts

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

Supported Layouts

Usage

A wrapper and minimal UI for a cross-platform, fixed-position banner that shows a call-to-action to install an app.

The amp-app-banner component includes conditional logic to direct users to the right app on the right platform. If the user dismisses the banner, the banner is hidden permanently.

<head>
  <meta
    name="apple-itunes-app"
    content="app-id=123456789, app-argument=app-name://link/to/app-content"
  />
  <link rel="manifest" href="https://link/to/manifest.json" />
</head>

. . .

<body>
  <amp-app-banner layout="nodisplay" id="demo-app-banner-2134">
    <amp-img src="https://example.com/icon.png" width="60" height="51">
    </amp-img>
    <h3>App Name</h3>
    <p>Experience a richer experience on our mobile app!</p>
    <div class="actions">
      <button open-button>Get the app</button>
    </div>
  </amp-app-banner>
</body>

For a full-page example, see article.amp.html.

Use of amp-app-banner must meet the following requirements:

Specify data sources

To extend and promote the usage of the natively supported app banners on iOS and Android, amp-app-banner uses the exact data sources that the native app banners use on their respective platforms. iOS uses a <meta name="apple-itunes-app"> tag in the head of the document, while Android uses a <link rel="manifest"> tag.

  • On iOS, the AMP runtime parses the <meta> tag content attribute to extract the App ID and app-argument. These are usually used for deep link URIs, such as app-protocols like whatsapp:// or medium://.

    • The <meta> tag must have the name and content attributes.

    • The value of the content attribute must contain app-id=.

  • On Android, the AMP runtime makes an XHR request to fetch the manifest.json file. The runtime parses the content to extract app_id from related_applications and calculates the app store URL as well as open-in-app URL, which has the following form: android-app://${appId}/${protocol}/${host}${pathname}

The protocol, host, and pathname are calculated from the canonical URL of the AMP document. Your native app needs to register the links in their manifest. For more information, read up on mobile deep linking.

Example app manifest 

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/view_article">
        <!-- This is important in order to allow browsers to launch your app. -->
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "https://CANONICAL_HOST/gizmos" -->
        <data android:scheme="https"
              android:host="CANONICAL_HOST"
              android:pathPrefix="/" />
    </intent-filter>
</activity>

Example manifest.json

{
  "prefer_related_applications": true, // This is not necessary for <amp-app-banner>, but signals a preference on non-AMP pages using the same manifest.json file for the native app over a web app if available
  "related_applications": [
    {
      "platform": "play",
      "id": "com.app.path",
      "url": "android-app://com.app.path/https/host.com/path/to/app-content"
    }
  ]
}

UI behavior

amp-app-banner provides no default UI. Instead, the developer can build any kind of UI inside the banner and style it accordingly.

Currently, the banner is always displayed until it's dismissed. After it's dismissed, the banner never displays on that domain unless the user visits on a different browser or clears their local storage.

Required attribute in the UI

The button[open-button] button is required in the banner. This is the click target that either installs the app or, if it's already installed, opens the deep link.

The button[open-button] element can't have the value disabled.

Dismissal button restrictions

The "X" button used to dismiss the banner has limits on how you can customize it. You can style this button with the .amp-app-banner-dismiss-button class. Keep the dismissal button visible and easily accessible on mobile devices so that the banner doesn't block content.

OS, browser, and viewer dependencies

The native app banners aren't shown in the viewer context. As such, amp-app-banner is shown inside of the viewer when the appropriate markup is present.

However, system-level app banners are shown when viewed with a browser on a compatible OS, such as Android and Chrome, or iOS and Safari. In those cases, the amp-app-banner is hidden to avoid redundancy. The following table shows these dependencies:

Context Android + Chrome iOS + Safari Other OS + browser
In AMP viewer Show amp-app-banner Show amp-app-banner Show amp-app-banner
Outside of AMP viewer Show system banner Show system banner Show amp-app-banner

Attributes

id

Defines a unique identifier for an amp-app-banner component. The id value is used for persistence logic.

layout

Specifies the layout of the banner. The value must be nodisplay.

Validation

See amp-app-banner rules in the AMP validator specification.

Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub