Skip to main content

Mobile app links on custom domains

Use this guide when a customer domain is connected directly to StorifyMe, for example stories.example.com. StorifyMe serves the association files for that domain. You do not need to upload those files yourself.

The association files connect a website to an app. The app must also declare the domain in its signed iOS or Android configuration. Adding a domain in the StorifyMe dashboard does not change an app that has already been built or installed.

1. Configure mobile settings in StorifyMe​

Open Settings → Mobile, enable mobile deep links, and enter the app details for the platforms you support:

  • iOS: Apple Developer Team ID and app Bundle ID.
  • Android: application ID/package name and the SHA-256 fingerprint of the app signing certificate. If you use Play App Signing, use the app signing certificate fingerprint from Play Console, not the upload certificate. Multiple fingerprints can be configured when needed.

Save the settings. Android's file is empty ([]) until both the package name and at least one fingerprint are configured. iOS's details array is empty until both the Team ID and Bundle ID are configured.

2. Check the association files​

For a custom domain such as stories.example.com, the files are available at:

  • iOS: https://stories.example.com/.well-known/apple-app-site-association (no .json suffix)
  • Android: https://stories.example.com/.well-known/assetlinks.json

Check each URL directly:

curl -i https://stories.example.com/.well-known/apple-app-site-association
curl -i https://stories.example.com/.well-known/assetlinks.json

Each request should return 200, JSON, and no redirect. The iOS file identifies the app with appID (TeamID.BundleID) and currently associates custom-domain paths with /*. Custom-domain story links use root paths such as https://stories.example.com/my-story, so this includes those links. Android's file identifies the app with its package name and signing certificate fingerprint.

The files are generated from the account's saved settings and cached by the service for up to five minutes. Allow that time after changing settings before checking again.

3. Add the domain to the app​

The hostname must be included in the app binary. Use the exact hostname customers will open, with no scheme, path, or trailing slash. For https://stories.example.com/my-story, the hostname is stories.example.com.

iOS​

In Xcode, add the Associated Domains capability to the app target and add:

applinks:stories.example.com

Sign and distribute a new app build with this entitlement. iOS uses the AASA file to verify the app identifier and decide which paths can open the app. Apple requires the domain in the app entitlement as well as the AASA file. Apple's associated domains guide

Android​

Add a verified App Links intent filter to the activity that handles incoming links. For a custom-domain story URL at the root, use a path prefix that includes root paths:

<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="http" />
    <data android:scheme="https" />
    <data android:host="stories.example.com" />
    <data android:pathPrefix="/" />
</intent-filter>

Build and distribute an app version containing the host. The app must also read the incoming URL and route its story handle. Android verifies the manifest host against the assetlinks.json file. Android's App Links guide

If an app supports multiple independent customer domains, each domain needs to be covered by the app's manifest or entitlements. The server cannot add a new host to an already signed app. A wildcard is useful only when the customer domains share a parent domain that the app can declare.

4. Test on a device​

  • Open a shared story link from another app, such as Notes or Messages. Typing the URL into Safari's address bar is not a Universal Links test.
  • On Android, verify the installed package's App Links status with Android Studio's App Links Assistant or the device's App Links settings.
  • Confirm that the app's package/bundle identifier and signing certificate match the values saved in StorifyMe.

The operating systems cache domain verification results. A change to a file on the server may not take effect immediately on devices. iOS uses Apple's associated-domains CDN, and Android re-verification timing depends on Android version. Apple's Universal Links troubleshooting guide, Android's App Links verification guide

Proxy domains​

Automatic file generation in this guide applies to custom domains connected directly to StorifyMe. Proxy-based domains are outside this automatic flow. The proxy must serve the correct files at both root-level /.well-known/ URLs, or the proxy forwarding must be configured and validated separately with StorifyMe. Do not assume that forwarding to the direct custom-domain endpoint will select the proxy account automatically.

For app-side URL handling, see the platform guides for iOS, Android, Flutter, or React Native.