Web banner

Before you start#

• Web banners are part of the Pro, Business and Enterprise plans. An account can have up to 20 banners.
• You need an Appy link for your app. The banner adds nothing to its routing: deep links, store targets, Galaxy Store, GetApps, country rules and the in-app browser page all work as they do for any other click.
• You need to be able to add a script tag to the pages of your website, directly or through a tag manager.

How it works#

1. 1

   The script checks the visitor

   On every page view, banner.js looks at the user agent. It stops right there on desktops, when the visitor closed this banner within the snooze period, and in Safari on iPhone or iPad when your page already has Apple's Smart App Banner tag.

2. 2

   It loads the banner settings

   One request to https://appy.to/_banner/<id> returns the text, colors, link and page rules. The script stops if the current path is not on the banner's list.

3. 3

   It shows the banner and counts an impression

   The banner appears at the top or bottom of the screen. One impression is sent per page view.

4. 4

   The button opens your link

   The button opens your Appy link with utm_source=web_banner, utm_medium=banner, the banner id as utm_campaign and the page path as utm_content. From there the link routes the visitor and records the click like any other.

Install#

Create the banner in the dashboard under Links > Web banner, save it and copy the snippet. Paste it just before the closing </body> tag on every page where the banner may show:

<script src="https://appy.to/banner.js" data-banner="YOUR_BANNER_ID" async></script>

• The file is about 6 KB compressed, has no dependencies and loads nothing from any other host.
• It runs inside a shadow root, so your CSS does not change the banner and the banner's CSS does not touch your page.
• Adding the snippet twice, or through both your template and a tag manager, still shows one banner.
• Changes you save, pausing included, reach visitors within about three minutes: Appy caches the settings for up to a minute and browsers for two.
• Single-page apps: the banner checks the path once, when the page loads. Use Show on and Never show on with the paths visitors land on.

Options#

Path patterns#

Patterns ignore the query string, the fragment, trailing slashes and letter case. * matches any characters, / included. :name matches one path segment.

Keep space at the top#

A banner that slides in above your header would push the page down after it has rendered. To keep the page still, add a slot at the start of <body> and load the script right after it, without async:

<style>
  [data-appy-banner-slot] { min-height: 64px; }
  [data-appy-banner-slot][data-appy-banner-state="hidden"],
  [data-appy-banner-slot][data-appy-banner-state="dismissed"] { min-height: 0; }
  @media (hover: hover) and (pointer: fine) { [data-appy-banner-slot] { display: none; } }
</style>
<div data-appy-banner-slot></div>
<script src="https://appy.to/banner.js" data-banner="YOUR_BANNER_ID"></script>

• The slot keeps 64 px free on phones and tablets and takes no space on computers with a mouse.
• The script sets data-appy-banner-state on the slot to shown, hidden or dismissed. Because it runs straight after the slot, visitors who closed the banner never see the empty space.
• Without a slot, a top banner with this layout falls back to Over the page.

While a banner is visible, <html> carries data-appy-banner="top" or data-appy-banner="bottom". Use it to move a sticky header or a chat button out of the way:

html[data-appy-banner="top"] .site-header {
  top: 64px;
}

Open the same page in your app#

When a visitor reads a product page on your site, the app can open on that product instead of its home screen. Choose one of the options under Open the same page in the app:

How the app receives it depends on your setup:

• Appy SDK: deep_link_path is one of the link parameters the SDK hands to your app, both when an installed app opens from the banner and on the first open after an install. See the iOS and Android guides.
• Parameter forwarding (Business and Enterprise): the parameter is also added to your deep link and to store URLs, for example myapp://open?deep_link_path=product%2F42.
• Without either, the app opens on the link's deep link and the path is only visible in your click data.

// iOS (Swift)
Appy.shared.onDeepLink { link in
  if let path = link.params["deep_link_path"] { router.open(path) }
}

// Android (Kotlin)
Appy.onDeepLink { link ->
  link.params["deep_link_path"]?.let { router.open(it) }
}

When the banner stays hidden#

Measurement#

The Web banner page shows these for the last 7, 30 or 90 days. Because clicks carry normal UTM values, the banner also shows up in the link's analytics, the report builder, exports and install attribution, with utm_content telling you which page the visitor came from.

Content-Security-Policy#

Sites with a strict Content-Security-Policy need to allow https://appy.to for the script, the settings and beacon requests, and the icon:

Content-Security-Policy:
  script-src  'self' https://appy.to;
  connect-src 'self' https://appy.to;
  img-src     'self' https://appy.to

• style-src needs nothing extra: the banner styles itself through a constructable stylesheet inside its shadow root, which a policy without unsafe-inline allows.
• Leave img-src out if the banner has no icon.
• Browsers older than Safari 16.4, Chrome 73 or Firefox 101 fall back to a <style> element. Under a strict style-src they show no banner at all.
• If you allow scripts by nonce or hash only, add the same nonce to the snippet's <script> tag.

Testing#

1. 1

   Open a page on a phone

   Or use the device toolbar in Chrome DevTools with a phone selected, then reload: the script reads the user agent when the page loads.

2. 2

   Check the settings

   Open https://appy.to/_banner/<id> in a browser. A 404 means the banner is paused, deleted or its link is inactive.

3. 3

   Show it again after closing

   Delete appy_banner_dismissed_<id> from local storage, or use a private window.

4. 4

   Follow the button

   Tap it on a phone with the app installed and on one without it, and check the click under the link's analytics with utm_source = web_banner.