Apple Setup

Smart App Banner: the meta tag, the gotchas, and when it silently fails

The Smart App Banner meta tag is one line, but it silently does nothing in five common situations. The correct tag, the parameters, and why yours isn't showing.

By · · 6 min read

The Smart App Banner is the strip Safari shows at the top of a web page advertising your iOS app (“Open in the App”). It’s a single <meta> tag — and it silently does nothing in at least five common situations, with no error to tell you why. This is the correct tag, what each parameter does, and the reasons yours isn’t appearing.

For where this fits in your overall App Store web setup, see every URL and file Apple requires for an iOS App Store submission.

The meta tag

Place this in the <head> of the page you want the banner on:

<meta name="apple-itunes-app"
      content="app-id=1234567890, app-argument=https://yourdomain.com/path, affiliate-data=myAffiliateToken">

Parameters:

Parameter Required Purpose
app-id Yes Your numeric App Store ID (the digits in apps.apple.com/app/id1234567890). Not the bundle ID.
app-argument No A URL passed to your app when launched from the banner — use it to deep-link to the same content. Read it in application(_:open:options:) / userActivity.
affiliate-data No Apple Services affiliate token for attribution.

Apple’s reference: Promoting apps with Smart App Banners.

The five reasons it silently fails

1. You’re testing on desktop or in a non-Safari browser

Smart App Banners are Safari on iOS only. They do not appear in Chrome for iOS (uses a different mechanism), desktop Safari, or any Android browser. If you’re QA-ing on a Mac, you’ll never see it. Test on a physical iPhone in Safari.

2. The app isn’t on the App Store yet

The banner reads live App Store data for the app-id. If the app is still in review or TestFlight-only, the banner has nothing to render and silently omits itself. It only works once the app is publicly live.

3. You previously dismissed it

Once a user taps the × on the banner for a site, Safari suppresses it for that site for a while. During testing this looks like “it stopped working.” Test in a fresh Safari (or clear website data) to see the first-visit behavior.

4. The app-id is wrong (bundle ID instead of numeric ID)

app-id must be the numeric App Store ID, not com.yourcompany.app. Find it in App Store Connect (Apple ID field) or in the store URL. A bundle ID here = silent no-op.

5. Smart App Banner vs. a self-built banner conflict

If you also ship a hand-rolled “open in app” interstitial, or a third-party deferred-deep-link SDK that injects its own banner, they can suppress or conflict with the native one. Pick one. The native Smart App Banner is the only one Apple endorses and the only one that won’t get flagged under the App Store Review Guidelines interstitial rules if you also have an app.

They solve different halves of the same problem:

  • Universal Links make a tapped link to your domain open the app directly (no banner) — requires the AASA file.
  • Smart App Banner is for users who land on your web page in Safari and you want to nudge them to the app — it’s a promotion strip, not a redirect.

Use both: Universal Links for inbound links, Smart App Banner for organic web visitors. The app-argument URL should point at the same content so a banner tap deep-links correctly.

App Clip variant

The same meta tag promotes an App Clip instead of (or alongside) the full app:

<meta name="apple-itunes-app"
      content="app-id=1234567890, app-clip-bundle-id=com.yourcompany.app.Clip, app-clip-display=card">

app-clip-display=card shows the richer App Clip card. See App Clips invocation URLs and the AASA appclips key.

How OrbitKit handles it

OrbitKit injects the apple-itunes-app meta tag into every hosted page when you set your App Store ID (and optional affiliate data / app-argument) in the dashboard — so your privacy policy, support, and other hosted pages double as app-promotion surfaces without you editing HTML. App Clip banner variant supported too. Start free or see features.