Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ain/smartbanner.js
Customisable smart app banners for iOS and Android
https://github.com/ain/smartbanner.js
android bower ecmascript6 ios javascript mobile nodejs npm smart-app-banner smartbanner vanilla-js webdev
Last synced: about 2 months ago
JSON representation
Customisable smart app banners for iOS and Android
- Host: GitHub
- URL: https://github.com/ain/smartbanner.js
- Owner: ain
- License: gpl-3.0
- Created: 2016-05-29T09:40:13.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-05-20T06:04:19.000Z (4 months ago)
- Last Synced: 2024-05-20T07:25:23.619Z (4 months ago)
- Topics: android, bower, ecmascript6, ios, javascript, mobile, nodejs, npm, smart-app-banner, smartbanner, vanilla-js, webdev
- Language: JavaScript
- Homepage: https://npmjs.com/package/smartbanner.js
- Size: 5.02 MB
- Stars: 596
- Watchers: 12
- Forks: 178
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# smartbanner.js [](https://github.com/ain/smartbanner.js/actions?query=workflow%3A%22Node.js+CI%22) [](https://badge.fury.io/js/smartbanner.js) [](https://badge.fury.io/bo/smartbanner.js) [](https://coveralls.io/github/ain/smartbanner.js?branch=main)
Customisable smart app banner for iOS and Android.
 
## Features
- Populating smartbanner is as easy as [adding meta tags](#basic-usage), no JavaScript knowledge required
- Default [Smart App Banner](https://developer.apple.com/library/ios/documentation/AppleApplications/Reference/SafariWebContent/PromotingAppswithAppBanners/PromotingAppswithAppBanners.html) like design
- Customisable info with i18n support and design by using
- automatically generated `smartbanner--` class on wrapper
- [custom design modifier](#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](#time-limited-close)
- at current path or [site-wide](#path-designated-close)
- Platform-specific app icon and _View_ button
- User Agent specific targeting
- Pure JavaScript coming in at 17 KB minified, no jQuery required
- [Events](#events) emitted for [API](#smartbanner-api-use) implementations
- ECMAScript 6 source
## Basic Usage
`smartbanner.js` works automagically given following meta tags:
```html
```
Additionally, JavaScript and CSS has to be included:
```html
```
## 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:
```html
```
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:
```html
```
**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:
```html
```
### Hide the smartbanner completely
If you want to prevent smartbanner rendering in some html pages, you can add optional `meta` tag:
```html
```
### Time-limited close
By default smartbanner would not reappear if closed. This can be prevented with `hide-ttl` option. Following example would keep smartbanner closed for 10 seconds (10000 ms):
```html
```
### Path-designated close
Once closed smartbanner would reappear if site path changes. It is default behaviour.
Following example would keep smartbanner closed site-wide (but only when user has actually closed it):
```html
```
### 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.:
```html
```
which would add `smartbanner--mysite.com` class on wrapper.
- forced platform-specific styles on all platforms, e.g.:
```html
```
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:
```html
```
### smartbanner API use
By default smartbanner is added to DOM automatically. You can disable it with
```html
```
and add smartbanner to DOM manually:
```js
smartbanner.publish();
```
### 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):
```js
document.addEventListener('smartbanner.clickout', smartbanner.exit);
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## Sponsors
Cross-browser testing across all mobile platforms is powered by
## Licence
Copyright © 2016-2024 Ain Tohvri, contributors. Licenced under [GPL-3](https://raw.githubusercontent.com/ain/smartbanner.js/main/LICENSE).