Universal Links and App Links setup in Brevily

Add your iOS and Android app to Brevily, pick the domains that open it, and set up Universal Links and App Links with a publishable key that counts opens.

On this page
  1. How Universal Links and App Links work in Brevily
  2. What you need
  3. Add your app in Link setup › Mobile apps
  4. Choose the domains that open the app
  5. Universal Links and App Links setup in your app
  6. Make a publishable app key
  7. Troubleshooting Universal Links and App Links
  8. Common questions
  9. Next steps

Universal Links and App Links setup takes three things: your app's IDs in Brevily, the domains whose links should open it, and a few lines in the app itself. Brevily then serves apple-app-site-association and assetlinks.json on each domain you pick, so a tap on a short link opens the installed app directly, with no page in between. This guide covers the app record in Link setup › Mobile apps, the files, the iOS and Android side, and the publishable key the app uses to report each open.

Before you start: this guide builds on deep links to app screens. Your app's own calls use its app key, with nothing to sign; keep API errors to hand.

Without them, a deep-linked short link goes through Brevily first: Android gets an intent:// redirect into the app, and iPhone gets a one-tap page with Open in the app. That works on any domain and needs nothing in the app beyond its URL scheme.

With them, the phone checks your domain's association file and opens the app before the short link loads:

  • iPhone (Universal Links): the file lists only the links on that domain whose deep link opens this app, each by its exact path. Every other link, and a link added since the file was last built, opens in the browser as before.
  • Android (App Links): the file names the app and its signing certificates, never paths. Which paths the app opens is up to its own manifest.
  • The click: the visit never reaches Brevily, so the app reports it with POST /events/open and its publishable key. Brevily decides the visit as for any tap, counts the click and answers the screen to show. That call is in deferred deep links.

When the app isn't installed, the phone simply opens the link in the browser, and the deep link's usual fallback applies.

What you need

  • A plan with deep links, with Universal Links and App Links, and with website and app keys (for the app's own calls). See pricing.
  • A verified domain of your own, such as go.example.com, or an approved subdomain of a shared domain such as acme.brvl.app. Shared domains themselves serve no association files. See own domain for short links.
  • The Organisation permission with Edit to add the app and pick its domains, and API keys with Create to make its publishable key.
  • From Apple: your Team ID (Apple Developer account, under Membership) and the app's bundle ID (in Xcode).
  • From Google: the package name and the SHA-256 fingerprint of each signing certificate (Play Console › App integrity). With Play App Signing, that includes Google's app signing key, not only your upload key.
  1. Open Link setup › Mobile apps and choose Add an app.
  2. Enter the App name.
  3. On the iOS tab: Opens with (the URL scheme, exampleapp) and Without the app, send people to (an https address on apps.apple.com).
  4. Open Open straight from your links (optional) and fill in Team ID (10 letters and digits) and Bundle ID (com.example.app).
  5. On the Android tab: Opens with and Without the app, send people to (on play.google.com).
  6. Under Open straight from your links (optional): Package name (left blank, it's read from the Play Store address) and SHA-256 fingerprint, one per line in the form AB:CD:…, up to 10.
  7. Choose Add app.

Once a platform can open the app by its scheme, its tab shows Opens by scheme. It shows Ready once it also has what opening straight from a domain needs: on iOS the Team ID and bundle ID, on Android a fingerprint. Needs details means nothing opens the app yet.

The Android build needs Opens with even with App Links: without a scheme, Android visitors who reach the short link get the web destination instead of the intent:// redirect.

Choose the domains that open the app

  1. On Mobile apps, choose the app to open its page.
  2. Under Open from your domains, tick each domain whose links should open the app.
  3. Choose Save domains.

[screenshot: an app's page with the iOS and Android cards showing Ready, and Open from your domains with one domain ticked]

The files update within 7 minutes, and phones can take longer to notice: Apple fetches the file through its own cache. A domain is listed only once it's verified.

Check the files Brevily serves

Each file is served once at least one active link on the domain has a deep link that opens this app. Ask for it as the phone would:

bash
curl https://go.example.com/.well-known/apple-app-site-associationcurl https://go.example.com/.well-known/assetlinks.json

The Apple file lists your Team ID and bundle ID, and one exact path per link:

json
{  "applinks": {    "details": [      {        "appIDs": ["ABCDE12345.com.example.app"],        "components": [          { "/": "/autumn" },          { "/": "/offers/spring" }        ]      }    ]  }}

The Android file names the package and its fingerprints:

json
[  {    "relation": ["delegate_permission/common.handle_all_urls"],    "target": {      "namespace": "android_app",      "package_name": "com.example.app",      "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]    }  }]

Both are JSON, never a redirect, and the Apple file is also at /apple-app-site-association. Anything that can't be served is a plain-text 404.

iOS: Associated Domains

In Xcode, open the target's Signing & Capabilities, add Associated Domains, and add one entry per domain. The entitlements file then holds:

<key>com.apple.developer.associated-domains</key><array>  <string>applinks:go.example.com</string></array>

While developing, applinks:go.example.com?mode=developer makes a device in Developer Mode read the file from your domain rather than Apple's cache.

The app receives each link as an NSUserActivity of type NSUserActivityTypeBrowsingWeb, in your scene delegate. Pass its webpageURL to POST /events/open, as in deferred deep links.

Android: an App Links intent filter

The file can't list paths, so the manifest says which ones the app takes. A domain kept for app links, such as app.example.com, is simplest: claim the whole host.

<activity android:name=".LinkActivity" android:exported="true" android:launchMode="singleTask">  <intent-filter android:autoVerify="true">    <action android:name="android.intent.action.VIEW" />    <category android:name="android.intent.category.DEFAULT" />    <category android:name="android.intent.category.BROWSABLE" />    <data android:scheme="https" android:host="app.example.com" />  </intent-filter></activity>

Sharing a domain with ordinary links? Put the app's links behind a path, such as go.example.com/app/autumn (paths in links depend on your plan), and add android:pathPrefix="/app/" to the data element.

After installing a build, check that Android verified the domain:

bash
adb shell pm verify-app-links --re-verify com.example.appadb shell pm get-app-links com.example.app

The domain should show as verified.

Make a publishable app key

An app reports its opens with a publishable key: a key made for that app, safe to ship inside it. It can only send events and ask where a link should open. It's never a credential for the rest of the API.

  1. On the app's page, find Count taps that open the app and choose Make a key….
  2. Give it a Label, such as the app's name and version, so you can tell keys apart later.
  3. Choose Make key, then copy the key (brv_pk_…). It isn't a secret, so the app's page keeps it for you to copy again later.

[screenshot: the Count opens dialog with its Label field]

The app sends it in the x-brevily-key header. The panel shows the month's calls, so you can see a release start reporting.

Replace a key

An app can have two live keys, so a new one can take over gradually. Make the second key from Manage keys › Make another key…, ship it, and once every copy in use carries it, Retire the old one. Installed copies that still use a retired key stop counting opens and installs until they're updated.

  • The file is a 404: check that the domain is ticked under Open from your domains, that at least one active link on it opens this app, that the iOS build has a Team ID and bundle ID (or the Android build a fingerprint), that the app is enabled, that your plan includes Universal Links and App Links, and that the organisation is active. Shared domains never serve the files.
  • A new link opens in the browser on iPhone: the file lists it at the next update, and Apple's cache can take longer. The link still works through its one-tap page in the meantime.
  • "iPhone: in the browser" beside a domain: so many links open the app there that the file would pass Apple's 128 KB, so none is served for that domain. Give the app a domain of its own, such as app.example.com.
  • Android opens the app for links it shouldn't: the manifest claims more than the app's links. Narrow it with a path prefix or a domain of its own. For a link that doesn't open this app, POST /events/open answers 404; show that link in a Custom Tab.
  • "… isn't one of your verified domains": add and verify the domain under Link setup › Domains first.
  • Android doesn't verify: the fingerprint must be the certificate that signed the installed build. A Play-installed build is signed with Google's app signing key; a local build with your debug or upload key. Add each one you use.
  • The app can't be disabled or removed: active links still open it. Change their deep link, or disable them, first; the app's page links to them.

Common questions

Do I need Universal Links or App Links for a Brevily deep link to open my app?

No. A deep link opens the app on any domain with the app's URL scheme alone: straight away on Android, after one tap on iPhone. Universal Links and App Links remove that step, on your own domains.

Why doesn't Brevily's apple-app-site-association file use a wildcard path?

A wildcard would send every link on the domain into the app, including links meant for the web. Brevily lists each link that opens the app by its exact path, so every other link keeps opening in the browser.

Is a Brevily publishable app key a secret?

No. A publishable key can only report events (never a sale or an amount) and ask where a link opens, and only for links that open its own app on the domains picked for it. It never reports a sale or an amount. Keep your API keys on your server; the app never needs one.

Can I change my app's details in Brevily after adding it?

Yes. Choose Edit iOS or Edit Android on the app's page under Link setup › Mobile apps. Every link that opens the app follows within a few minutes, and the association files at their next update.

Next steps

All developer guides

Brevily is invite-only, for now

Say what you would use it for and a person replies. Already invited? Sign in.