Smart Banners
A Smart Banner is a small piece of your app, shown on your website. A visitor reading a product page on the web sees a banner offering the app, taps it, and lands on that same product page inside the app — installing it first if they do not have it yet.
The tap goes through your normal Detour app link, so everything the platform already does keeps working: store routing, deferred deep linking, click recording, and analytics. A visitor who taps, installs, and opens the app minutes later still arrives at the page they were reading.
Plan availabilitySmart Banners are available on Starter and above. Writing your own banner markup instead of using the built-in designs additionally requires Scale or Enterprise. See Billing & Payments.
🛠️ Where to find it
- Log in to the Detour Dashboard.
- Open Smart banners in the sidebar, under your organization.
- Pick the app the banners belong to.
Each banner belongs to one app, and one app can have as many banners as you like.
1. Install the snippet
Add this once, anywhere in your pages' HTML:
<script async src="https://your-org.godetour.link/banner/v1.js" data-detour-app="YOUR_APP_HASH"></script>
Copy the exact snippet — with your organization's subdomain and app hash already filled in — from the Add this to your website card in the dashboard.
That is the whole installation. Every banner you create, edit, pause or schedule afterwards arrives through this one script, so you never have to touch your website again.
Single-page apps
If your site changes pages without a full reload — Next.js, Nuxt, most React and Vue apps — also call this after each navigation:
window.DetourBanner?.refresh();
Without it, the script keeps showing whatever matched the page the visitor first arrived at. With it, banners follow the visitor around your site.
Restricting which websites may use it
Your app hash is public — it sits in the HTML of every page the banner runs on. By default the snippet works anywhere it is pasted, including sites you did not paste it on.
Add your domains under Websites to narrow that down. An entry covers its subdomains, so listing example.com also covers www.example.com and shop.example.com. Leaving the list empty means "anywhere", which is fine while you are testing and worth revisiting before launch.
2. How Detour picks which banner to show
Banners are evaluated top to bottom in the list order, and the first one that matches wins. Only one banner is ever shown on a page. Drag the list to reorder it — put your most specific campaigns above your catch-all.
A banner matches when all of its conditions hold:
| Condition | What it checks |
|---|---|
| Status | It is live, and within its scheduled dates if it has any |
| Pages | The current page address matches your rules (or the banner is set to run on all pages) |
| Device | The visitor is on a phone, or on a desktop and the banner is configured to show there |
| Location | The visitor's country is in scope |
| Language | The visitor's browser language is in scope |
| History | They have not dismissed it recently, and have not already seen it too many times |
Page rules match against the path and query string of the current address, so a rule can depend on ?tab=summer. You can use * as a wildcard.
If nothing matches, no banner is shown — which is the correct outcome, not an error.
3. Where a tap goes
This is the part worth getting right, and the reason Smart Banners are more than a link.
Same page, in the app
Map your website's URL structure onto your app's screens using * as a wildcard. Each * on the web side captures a value, and the captures fill the * on the app side, in order:
| Web pattern | App screen | Visitor on… | Opens… |
|---|---|---|---|
/restaurant/* | /restaurant/* | /restaurant/BurgerKing | /restaurant/BurgerKing |
/blog/* | /articles/* | /blog/how-we-ship | /articles/how-we-ship |
/shop/*/detail | /product/* | /shop/48122/detail | /product/48122 |
Matching ignores case, but the captured text is passed through exactly as written, because it is a real route name in your app.
Set a fallback screen for visitors on pages the pattern does not cover — usually your app's home screen.
One fixed screen
If the banner is a campaign rather than a mirror of your site, point every tap at a single screen instead. This is the right choice for "get 20% off in the app" style banners, where the page the visitor happened to be on does not matter.
Attribution
Detour appends these to every banner link automatically:
utm_source=smart_bannerutm_campaign— your campaign name, or the banner's name if you left it blankdtb— the banner's internal id, used to attribute taps to the right banner
You can add your own parameters on top. Parameters using one of the three reserved names above are ignored, so they cannot collide with what Detour writes.
4. Desktop visitors
An app link is useless on a computer, so a banner shown on desktop has to do something else. Three options:
- Don't show it — the banner is phone-only. A reasonable default.
- Show a QR code — the visitor scans it with their phone and continues there. The code carries the app link, including the mapped screen and attribution, so scanning lands them exactly where a tap would have.
- Link somewhere else — send them to your app store listing, or to a URL of your choosing.
5. Frequency and dismissal
Two independent controls, both per visitor and per banner:
- After dismissing, show it again after… — their next visit, an hour, a day, a week, or never again.
- Show at most… — no limit, once, three times, or five times.
Both are stored in the visitor's own browser. They reset if the visitor clears their site data or switches browser or device, which is normal and not worth designing around.
6. Custom banner markup
Requires Scale or EnterpriseOther plans use the built-in designs, which cover the same layouts without writing any markup.
Instead of filling in the form, you can write the banner's HTML yourself. Two things make your markup work as a banner:
| Placeholder | What it does |
|---|---|
{{LINK}} | Replaced with the app link for the current page. Put it in an href="{{LINK}}". |
id="detour-banner-close" | Any element with this id becomes the dismiss control. |
The same constraints as Custom HTML Redirects apply:
- Size limit: 50 KB (51,200 characters).
- Scripts blocked:
<script>tags and inline JavaScript (onclick,onload, …) are stripped. - Media hosting: images, fonts and stylesheets must be hosted externally over HTTPS and referenced by absolute URL.
Your markup is rendered inside a shadow root, so your website's CSS cannot affect the banner and the banner's CSS cannot affect your website.
On a desktop visitor set to show a QR code, there is nothing a click could usefully open, so links in your markup are left inert. Use one of the other two desktop options if your custom banner needs to be clickable on a computer.
Downgrading below Scale does not delete your markup — banners fall back to the built-in design, and switching back restores what you wrote.
7. Measuring results
The banner list shows, per banner:
- Seen — how many times the banner was displayed.
- Tap rate — the share of those that turned into a tap.
Taps are ordinary Detour clicks, so they also appear in Analytics alongside the rest of your link traffic, tagged with utm_source=smart_banner and the campaign name. Installs that follow a tap are attributed the same way any deferred link install is.
⚠️ Things worth knowing
- Changes are not instant. The banner script is cached in visitors' browsers for up to 5 minutes, and your banner configuration for up to a minute at the edge. Pausing a banner takes effect within roughly that window, not immediately.
- Banner taps count as clicks against your plan's click allowance, the same as any other Detour link.
- Impressions do not. Only taps are clicks.
- One banner per page. The first match wins; the rest are not shown.
- Country detection is approximate, as all IP-based location is. Do not use it for anything that has to be exactly right.
Support
Need help or found a bug? We are here to assist you! Join our developer community on Discord for quick support, or reach out via the Contact Form on our main homepage.