smartbanner.js

Customisable smart app banner for iOS and Android.

Features

• Pure JavaScript, no jQuery (14 KB in size)
• ECMAScript 6 source
• Default Smart App Banner like design
• Customisable design using smartbanner--<platform> class on wrapper
• Fully customisable info
• Close button that
  • closes the banner
  • sets cookie to keep banner closed for current session
• Platform-specific app icon URL
• Platform-specific URL for View button
• Device-specific URL for VIEW button
• jQuery Mobile and AngularJS compliance
• User Agent specific targeting

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">
<!-- End SmartBanner configuration -->

Additionally, JavaScript and CSS has to be included:

<link rel="stylesheet" href="path/to/component/dist/smartbanner.min.css">
<script src="path/to/component/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 availabe only for some Android/iOS versions
• your app is only availabe 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 whitelist certain user agents:

<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. enabled-platforms has the lowest priority, exclude-user-agent-regex the highest priority.

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">

Add a separate links specific to some device/platform

There are cases when there are separate applications meant for phone and tablet of the same OS. For this purpose you can use the OS related metatag with platform-device suffix, e.g.

iOS - iPhone app link can be set with the following metatag:

  <meta name="smartbanner:button-url-apple-iphone" content="https://itunes.apple.com/iphonelink">

iOS - iPad app link can be set with the following metatag:

    <meta name="smartbanner:button-url-apple-ipad" content="https://itunes.apple.com/ipadlink">

Android - Phone app link can be set with the following metatag:

    <meta name="smartbanner:button-url-google-phone" content="https://android-phone/application-url">

Android - Tablet app link can be set with the following metatag:

    <meta name="smartbanner:button-url-google-tablet" content="https://android-tablet/application-url">

Note: It is important that 'global' link will work as fallback for related os device specific links in case if, for some reason, it will not be possible to identify your Android or iOS device userAgent.

Add a meta tag controlling when to load a component

It is useful in case if there is a specific requirement to show the smartbanner.js only for specific user group, e.g. for Registered users. In this case smartbanner.js can be initiated based on your own specific requirements by just running smartbanner.publish() from anywhere in your app. For this to work you also have to add a specific meta tag:

    <meta name="smartbanner:auto-load" content="false">

Note: If this meta tag gets omitted or its content attribute is set to true, smartbanner.js will be initiated in its usual way - on page load.

Contributing

See CONTRIBUTING.md.

Sponsors

Cross-browser testing across all mobile platforms is powered by

Licence

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