# App Association

How to access on Fynd Commerce 
Commerce Panel → Sales Channel (select application) → Content → App Association

## Introduction

App association lets you connect your storefront domain to your iOS and Android applications so that deep links open in the app instead of the browser.

When a customer opens a link to your storefront, such as from an email, an SMS, or a social post, the operating system checks two files served from your domain:

| Platform | Served at | File contents |
|  --- | --- | --- |
| iOS | `https://<your-domain>/.well-known/apple-app-site-association` | Apple App Site Association (AASA), which declares which iOS apps can open which URL paths. |
| Android | `https://<your-domain>/.well-known/assetlinks.json` | Digital Asset Links, which declares which Android apps and signing certificates are authorised for this domain. |


The App association page in the merchant panel is where you author and publish these two files. The platform serves them automatically after you save, so you do not need to host anything yourself.

## Who should use this

Use App association if all of the following are true:

* You have a custom iOS app, a custom Android app, or both.
* You want links to your storefront, such as `https://<your-domain>/product/…` or `https://<your-domain>/collection/…`, to open directly in the app on devices where the app is installed.
* You have access to your app’s Apple Team ID and bundle ID for iOS, or package name and SHA-256 signing certificate fingerprint for Android.


If you only sell through the Fynd default apps and do not have your own custom apps, you can skip this step. The platform handles those apps automatically.

## Before you begin

Have the following details ready before you open the page.

### For iOS

* **Apple Team ID**. This is the 10-character prefix, such as `ABCD1E2F3G`. You can find it in your Apple Developer account under **Membership**.
* **Bundle identifier** for each iOS app, such as `com.yourbrand.shop`.
* The **Associated Domains** capability enabled in your app’s Xcode project for the domain you want to configure.


### For Android

* **Package name** for each Android app, such as `com.yourbrand.shop`.
* **SHA-256 signing certificate fingerprint** for each app. Use colon-separated uppercase hex, with 32 pairs.
* You can get this with `keytool -list -v -keystore <your.keystore>` or from Google Play Console under **Setup > App integrity**.
* If you support multiple builds, keep a separate fingerprint for each environment, such as debug, release, and Play-signed.


## How to access the page

1. Open **App Association**.
2. The page opens with two tabs: **iOS AASA** and **Android Asset Links**.


You need the **Settings** permission on the application to view or edit this page.

## Page layout

The App association page contains the following components.

* **Header** — Displays the page title and the primary **Save** button in the top-right corner. The **Save** button is unavailable until you make changes.
* **Tabs** — Switch between **iOS AASA** and **Android Asset Links**. Each tab has its own editor and saves independently, so you do not need to fill both at the same time.
* **Action bar** — Appears to the right of the tabs and includes the following options:
  * **Preview** — Opens a read-only modal that shows the current editor contents as the final formatted file.
  * **Format JSON** — Auto-indents and tidies the JSON in the editor.
  * **Check Live** — Opens the file currently being served by the platform at `/.well-known/…` in a new tab. This option appears only when your storefront has a primary domain configured. Use it to verify that a save has propagated.
* **JSON editor** — A syntax-highlighting code editor. Validation errors appear in a red banner directly below the editor.
* **Character counter** — Appears in the bottom-left corner. The limit is 262,144 characters (approximately 256 KB). The counter turns orange at 80% and red at 95%.
* **External validator link** — Appears in the bottom-right corner. iOS opens the Branch.io AASA Validator, and Android opens Google’s Statement List Generator and Tester.
* **Help & Docs** — A collapsible panel with platform-specific reference links and a copyable example payload.


## Configure iOS app site association

The iOS file uses Apple App Site Association (AASA).

### Required JSON structure

The iOS file must be a JSON object. It must start with `{` and end with `}`.

Example:


```json
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCD1E2F3G.com.yourbrand.shop",
        "paths": [
          "/product*",
          "/collection*",
          "/c/*",
          "NOT /cart/*"
        ]
      }
    ]
  }
}
```

### What each field means

* **applinks** — The required wrapper. It must contain a `details` array in the modern format, or an `apps` array in the legacy format.
* **apps** — The legacy field. Keep it as an empty array for backward compatibility.
* **details** — One entry for each iOS app you want to authorise.
  * **appID** — A `TEAMID.bundleID` value, such as `ABCD1E2F3G.com.yourbrand.shop`. Use `appIDs` if you want to authorise multiple bundle IDs with the same path rules.
  * **paths** — A list of URL path patterns that should open in the app.
    * Use `*` as a wildcard to match any string.
    * Use `?` to match a single character.
    * Prefix a rule with `NOT ` to exclude that pattern.
    * Order matters. Apple evaluates the rules from top to bottom, and the first matching rule wins.


### Recommended path rules for storefronts

Use path rules like these for storefronts:


```json
"paths": [
  "NOT /cart/order-status*",
  "NOT /cart/*",
  "/c",
  "/c/*",
  "/product*",
  "/products*",
  "/profile",
  "/profile/*"
]
```

Excluding `/cart/*` is a safety net. Keep the payment flow in the browser unless your app is specifically designed to take over that page.

### Configure multiple iOS apps

Add more entries to the `details` array. Each entry is independent.

Example:


```json
{
  "applinks": {
    "apps": [],
    "details": [
      { "appID": "ABCD1E2F3G.com.yourbrand.shop", "paths": ["/product*"] },
      { "appID": "ABCD1E2F3G.com.yourbrand.shop.staging", "paths": ["/staging/*"] }
    ]
  }
}
```

## Configure Android asset links

The Android file uses Digital Asset Links.

### Required JSON structure

The Android file must be a JSON array. It must start with `[` and end with `]`. Each entry is one statement.

Example:


```json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourbrand.shop",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]
```

### What each field means

* **relation** — Leave this as `['delegate_permission/common.handle_all_urls']`. This is the standard relation for opening every link in the app.
* **target.namespace** — Always `android_app` for app links.
* **target.package_name** — Your app’s package ID, such as `com.yourbrand.shop`.
* **target.sha256_cert_fingerprints** — An array of SHA-256 fingerprints. Add every signing certificate you want to trust, including debug builds, release builds, and the Play App Signing upload certificate if applicable.


### Multiple Android apps or signing keys

For multiple apps, add more statement objects to the array.

Example:


```json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourbrand.shop",
      "sha256_cert_fingerprints": ["AA:BB:CC:..."]
    }
  },
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourbrand.shop.kiosk",
      "sha256_cert_fingerprints": ["11:22:33:..."]
    }
  }
]
```

If you use multiple fingerprints for the same app, such as debug and release, add them to the same `sha256_cert_fingerprints` array. You do not need to duplicate the whole statement.

## Save and validate configuration

1. Paste or type your JSON into the editor.
2. The editor parses on every keystroke. If the JSON is invalid, a red banner appears with the error.
3. Select **Format JSON** to tidy the indentation, if needed.
4. Select **Save**.


When you save, you see a message that says changes go live in about 5 minutes. CDN caches can take up to 24 hours to refresh.

### What the save button checks

The Save button checks the following:

* **Syntax** — The JSON must parse correctly.
* **Shape** — iOS must use a JSON object, and Android must use a JSON array.
* **Size** — The total payload must be under 256 KB, or 262,144 characters.


The Save button stays unavailable while the editor has unsaved errors or when you have not made any changes.

## Verify the change is live

1. After you save, wait about 5 minutes for the platform edge to refresh.
2. Select **Check Live** in the action bar. The live file opens in a new tab. Confirm that the contents match what you saved.
3. For an authoritative check, use the official validation tools:
  * **iOS** — Branch.io AASA Validator.
  * **Android** — Google Statement List Generator and Tester.


If the CDN serves a stale value, use the validators above. They force-refresh the cache.

CDN caches outside the platform’s control, such as Apple’s CDN and Google’s CDN, can take up to 24 hours to pick up the new value. The validators bypass those caches.

## Remove your configuration

To stop serving an App Association file completely so Apple and Google fall back to no app linkage:

1. Clear both the iOS and Android editors.
2. Select **Save**.
3. In the confirmation dialog, select **Continue**.


This is a destructive action. Once the verifiers see 404, deep links into your apps stop working until you save a new configuration.

After you remove the configuration, `/.well-known/apple-app-site-association` and `/.well-known/assetlinks.json` start returning 404.

## Troubleshooting

| Symptom | Likely cause | Fix |
|  --- | --- | --- |
| Save button stays unavailable | No changes detected, or there is a validation error | Edit the JSON, then check the red banner and fix any errors. |
| Invalid JSON banner appears | JSON syntax error, such as a missing comma, mismatched bracket, or trailing comma | Select **Format JSON** to spot the error, or paste the JSON into a linter. |
| iOS App Site Association must be a JSON object | The root value is an array, string, or number | Wrap the content in `{ … }` and place the `applinks` key inside it. |
| Android Asset Links must be a JSON array | The root value is an object | Wrap the statement in `[ … ]`. |
| Payload exceeds the 256 KB limit | Too many apps or paths | Consolidate the configuration. Contact platform support if you genuinely need more. |
| Apple validator shows 404 after save | Less than 5 minutes have passed since the save, or the storefront has no primary domain | Wait a few minutes, then verify your domain in **Settings > Domains**. |
| Apple validator shows “applinks key not found” | The JSON is valid but missing the `applinks` wrapper | The iOS file must start with `{ "applinks": { … } }`. |
| Google validator reports fingerprint mismatch | The SHA-256 fingerprint in the file does not match the certificate that signed the APK | Re-extract the fingerprint from the release keystore, not the debug keystore. |
| Universal Links open the browser, not the app | The app is not installed, the AASA file is cached, or the app’s Associated Domains capability is not enabled for this domain | Verify the app is installed, wait 24 hours or use Apple’s validator to force a refresh, and check the Xcode configuration. |
| Android App Links open the browser, not the app | The statement file was not found by Android, or the app’s `intent-filter` does not have `android:autoVerify="true"` | Verify the file is live with Google’s tester and check `AndroidManifest.xml`. |


## Reference

### Apple

* Supporting associated domains — `https://developer.apple.com/documentation/xcode/supporting-associated-domains`
* AASA file structure reference — `https://developer.apple.com/documentation/bundleresources/applinks`
* Branch.io AASA Validator — `https://branch.io/resources/aasa-validator/`


### Google

* Verify Android App Links — `https://developers.google.com/digital-asset-links/v1/getting-started`
* Statement List Generator and Tester — `https://developers.google.com/digital-asset-links/tools/generator`
* Digital Asset Links spec — `https://developers.google.com/digital-asset-links/v1/create-statement`


## Frequently asked questions

### Do I need to host the AASA or assetlinks.json file myself?

No. Save the JSON in the App Association page, and the platform serves it at `https://<your-domain>/.well-known/apple-app-site-association` and `https://<your-domain>/.well-known/assetlinks.json`. You do not need a server, a Cloudflare worker, or any other infrastructure.

### Does it have to be served over HTTPS?

Yes. Apple and Google both require HTTPS with a valid certificate. The platform handles the certificate; you only need to make sure the domain is configured in **Settings > Domains**.

### Can I have different rules per environment, such as staging and production?

Yes. Each application in the merchant panel has its own App Association page, so you can configure each app’s storefront independently.

### What happens if I change the JSON?

The platform updates the served file within about 5 minutes. Apple and Google operating-system caches can take up to 24 hours to refresh, so use the validator tools to force a refresh sooner.

### Can I authorise multiple apps in one file?

Yes. See the **Configure multiple iOS applications** and **Multiple Android apps or signing keys** sections above.

### What is the size limit?

The size limit is 256 KB, or 262,144 characters.

### Why does saving an empty configuration show a confirmation dialog?

Because it is destructive. Saving empty content deletes the configuration, and Apple and Google verifiers start getting 404