Smart app banner for mobile web
After this page, visitors on phones see an "Open in app" bar on your website, and a tap on it opens your app on the right screen.
On this page 9
- Time
- About 10 minutes
- You need
- A website you can add a script to, a Strait link for the banner (Dashboard → Links), your app set up with a Strait SDK
- Works on
- Android, iPhone, any mobile browser
The banner is part of the web SDK. It's a plain link to your Strait link, so a tap on it is handled like any other tap: the app opens if it's installed, otherwise the store opens and your app gets the destination on its first open (on iPhone, when install matching is switched on).
1. Create a link for the banner
In Dashboard → Links, create a link whose destination is the screen the banner should open, for example https://yourshop.example/app. A link used only by the banner keeps its taps separate in Analytics.
To open the page the visitor is on (a product, an article), create one link per page through the REST API and pass that page's link to the banner.
You should see: your link in the list, for example https://hilltop.strait.link/app.
2. Install the web SDK
Install it from npm. The banner arrived in version 0.6.0; install 0.8.7 or later for the @straitlink/web package name.
npm install @straitlink/web@0.8.7You should see: @straitlink/web in your package.json.
3. Add the banner
Call it once when the page loads. Copy, then change the link, title and icon:
import { Strait } from '@straitlink/web';
Strait.banner({
link: 'https://hilltop.strait.link/app', // your banner link from step 1
title: 'Hilltop Shoes', // usually your app's name
subtitle: 'Track your order in the app',
icon: '/icons/app-192.png', // shown at 40×40
theme: 'auto', // 'light' | 'dark' | 'auto'
});No build step? dist/banner.js in the package has no imports, so you can copy it next to your pages and load it directly:
<script type="module">
import { banner } from '/js/banner.js';
banner({ link: 'https://hilltop.strait.link/app', title: 'Hilltop Shoes', subtitle: 'Track your order in the app' });
</script>You should see: on a phone, a bar at the top of the page with your icon, title and an Open in app button. On a computer, nothing: the banner shows on phones and tablets only. To check the styling on a computer, add force: true for a moment.
4. Hide it inside your own app
If your app shows your website in a WebView, tell the banner, so people already in the app don't see it. Add a token to your WebView's user agent and pass it, or pass your own check:
Strait.banner({
link: 'https://hilltop.strait.link/app',
title: 'Hilltop Shoes',
appUserAgent: 'HilltopShoesApp/', // a token your WebView adds to its user agent
// or: inApp: () => document.cookie.includes('in_app=1'),
});The banner also hides on its own in WebViews that have a React Native WebView or flutter_inappwebview bridge. It still shows in in-app browsers such as Instagram's or WhatsApp's, which aren't your app.
You should see: the bar on your site in a phone browser, and no bar on the same page inside your app.
5. Tap it and close it
On a phone with your app installed, tap Open in app. Then open the site again and tap the close button.
You should see: your app opens on the link's screen, and the tap appears in Dashboard → Analytics. After you close the bar, it stays hidden on that browser for 30 days.
Options
| Option | Default | What it does |
|---|---|---|
link |
(required) | Your Strait link. Opened as is. |
title, subtitle |
(title required) | Text on the bar, shown as plain text. |
icon |
none | Icon URL, shown at 40×40. |
button |
Open in app |
Button text. |
theme |
auto |
light, dark, or auto to follow the visitor's setting. |
position |
top |
top pushes the page down; bottom floats over it. |
accent, accentText |
dark button | Button colour and its text colour, any CSS colour. |
dismissDays |
30 |
Days it stays hidden after the visitor closes it. |
inApp, appUserAgent |
none | Hide it inside your own app (step 4). |
force |
false |
Show it everywhere, even after a close. For previews only. |
banner() returns { element, dismiss, remove }, or null when it isn't shown.
What it sends
Nothing. The banner makes no requests and sets no cookies. It stores one value in the visitor's browser, strait.banner.dismissed, the time they closed it. The only thing recorded is the tap on your link, by Strait, the same as for any link. If the browser blocks storage, the banner still works and simply shows again on the next visit.
Common errors
- Nothing shows on your computer. That's by design. Use a phone, or add
force: truewhile you check the styling. - Nothing shows on a phone either. You closed it in the last 30 days on that browser. Clear the site's data, or use
force: trueonce. A link that isn'thttps://orhttp://also stops it. - The app opens on its home screen. The link's destination is your home page, or the app doesn't route links yet. Check the destination in Dashboard → Links and set up receiving links in the app.
Next steps
- Web SDK: count the visits your links send to your website and credit events to the tap.
- Analytics: how we count: where banner taps show up.