smartbanner.js

Customisable and lightweight smart app banner for iOS and Android.

  

Features

• Populating smartbanner is as easy as adding meta tags, no JavaScript knowledge required
• Default Smart App Banner like design
• Customisable info with i18n support and design by using
  • automatically generated smartbanner--<platform> class on wrapper
  • custom design modifier for externally defined styles or same design on all platforms
• Close button that closes the banner and sets cookie to keep banner closed
  • for current session or for defined time
  • site-wide or at a designated path
• Platform-specific app icon and View button
• User Agent specific targeting
• Pure JavaScript coming in at 6.6KB minified!
• Events emitted for API implementations
• ECMAScript 6 (es2015) source

Basic Usage

smartbanner.js works automagically given following meta tags:

<!-- Start SmartBanner configuration -->
<meta name="smartbanner:title" content="Smart Application">
<meta name="smartbanner:author" content="SmartBanner Contributors">
<meta name="smartbanner:price" content="FREE">
<meta name="smartbanner:price-suffix-apple" content=" - On the App Store">
<meta name="smartbanner:price-suffix-google" content=" - In Google Play">
<meta name="smartbanner:icon-apple" content="https://url/to/apple-store-icon.png">
<meta name="smartbanner:icon-google" content="https://url/to/google-play-icon.png">
<meta name="smartbanner:button" content="VIEW">
<meta name="smartbanner:button-url-apple" content="https://ios/application-url">
<meta name="smartbanner:button-url-google" content="https://android/application-url">
<meta name="smartbanner:enabled-platforms" content="android,ios">
<meta name="smartbanner:close-label" content="Close">
<!-- End SmartBanner configuration -->

Additionally, JavaScript and CSS have to be included:

<link rel="stylesheet" href="/dist/smartbanner.min.css">
<script src="/dist/smartbanner.min.js"></script>

Advanced Usage

Hide the smartbanner for certain User Agents

There are cases where you do not want to show the smart app banner on all Android and/or all iOS devices. For example:

• your app is available only for some Android/iOS versions
• your app is only available on iPhone, but not iPad
• your app is a web app which also shows this website, but of course should not show the smart app banner.

In this case you can define a regular expression, which matches all user agent strings that should be excluded. Just add another meta tag like the following:

<meta name="smartbanner:exclude-user-agent-regex" content="^.*My Example Webapp$">

This regular expression would match any user agent string, that ends with My Example Webapp.

Show the smartbanner for certain User Agents

In addition to blacklisting certain user agents using the regex explained in the previous section, you can also show smartbanner to user agents that enabled-platforms would leave out:

<meta name="smartbanner:include-user-agent-regex" content="iPhone 7">

Note that include-user-agent-regex only adds to what enabled-platforms allows, it never narrows it down. To show smartbanner to matching user agents only, disable all platforms alongside it:

<meta name="smartbanner:enabled-platforms" content="none">
<meta name="smartbanner:include-user-agent-regex" content="iPhone 7">

Note: You can define enabled-platforms, exclude-user-agent-regex and include-user-agent-regex at the same time. Smartbanner is shown when either enabled-platforms or include-user-agent-regex matches, unless exclude-user-agent-regex matches, which always takes precedence.

Disable Positioning

If you want to position smart app banner yourself (e.g. in CSS), you can disable built-in positioning with following option:

<meta name="smartbanner:disable-positioning" content="true">

Hide the smartbanner completely

If you want to prevent smartbanner rendering in some html pages, you can add optional meta tag:

<meta name="smartbanner:enabled-platforms" content="none">

Time-limited close

By default smartbanner would not reappear for the remainder of the browser session, as closing it sets a session cookie. The hide-ttl option replaces that with a fixed duration. Following example would keep smartbanner closed for 10 seconds (10000 ms):

<meta name="smartbanner:hide-ttl" content="10000">

Path-designated close

Once closed smartbanner would stay closed site-wide. It is default behaviour, equivalent to hide-path being set to /.

Following example would keep smartbanner closed under /shop only (but only when user has actually closed it), meaning it would reappear elsewhere on the site:

<meta name="smartbanner:hide-path" content="/shop">

Custom design modifier

smartbanner uses built-in platform-specific styles (e.g. smartbanner--ios or smartbanner--android), but this behaviour can be altered by adding custom design modifier that allows use of:

• externally defined styles, e.g.:

  <meta name="smartbanner:custom-design-modifier" content="mysite.com">

  which would add smartbanner--mysite.com class on wrapper.

• forced platform-specific styles on all platforms, e.g.:

  <meta name="smartbanner:custom-design-modifier" content="ios">

  which would add smartbanner--ios class on wrapper regardless of actual platform.

Platform-specific button labels

If you want to have a different button label for each platform, you can use the following meta tags:

<meta name="smartbanner:button-apple" content="Download on the App Store">
<meta name="smartbanner:button-google" content="Get it on Google Play">

smartbanner API use

By default smartbanner is added to DOM automatically. You can disable it with

<meta name="smartbanner:api" content="yes">

which also accepts true as value, and add smartbanner to DOM manually:

window.addEventListener('load', function() {
  smartbanner.publish();
});

Note: smartbanner is exposed on window only once the page has loaded, hence the load handler above.

Events

Following events are being dispatched:

Event	Description
smartbanner.init	Dispatched when smartbanner has been initialised
smartbanner.view	Dispatched when smartbanner is added to display
smartbanner.clickout	Dispatched when smartbanner is clicked to navigate to app store
smartbanner.exit	Dispatched when smartbanner is closed

Example handler (closes smartbanner when user clicks to navigate to app store):

document.addEventListener('smartbanner.clickout', () => smartbanner.exit());

Node.js Support

Node.js is only required for installing and building smartbanner.js, the distributed bundle itself runs in browsers.

Supported Node.js versions follow the Node.js release schedule: Current, Active LTS and Maintenance LTS lines are supported, end-of-life ones are not.

Note: dropping support for an end-of-life Node.js version is released as a minor version and is not considered a breaking change.

Contributing

See CONTRIBUTING.md.

Sponsors

Cross-browser testing across all mobile platforms is powered by

Licence

Copyright © 2016-2026 Ain Tohvri, contributors. Licenced under GPL-3.