Summary
The `mobilePlatformApplicationCreate` and `mobilePlatformApplicationUpdate` mutations currently have no way to control which storefront paths are routed into the native iOS app via Universal Links. We’d like optional path configuration fields on the Apple input so apps can deep-link specific URL patterns (e.g. `/products/*`, `/cart`) into the app while leaving other paths (`/blogs/*`, `/policies/*`, `/help/*`) opening in Safari like normal web pages.
Problem
When a Shopify storefront has an iOS app registered with `universalLinksEnabled: true`, Shopify auto-generates the `/.well-known/apple-app-site-association` file with a wildcard that captures every storefront URL:
NOT /admin/\*
NOT /\*/amazon_payments/callback
NOT /\*/checkouts/\*/express/callback
/\*
The trailing `/*` routes every URL on the storefront into the native app. There is no way to narrow it without disabling Universal Links entirely.
Apple’s AASA specification supports exactly this kind of path-level control — either through the modern `components` array (with per-path `exclude`, `caseSensitive`, and `percentEncoded` flags) or the legacy `paths` array with `NOT` exclusions. The constraint is on the Shopify side.
I’ve checked the full GraphQL schema and none of these types expose a `paths`, `components`, or `excludedPaths` field:
- `MobilePlatformApplication` (interface)
- `AppleApplication` (object)
- `MobilePlatformApplicationCreateInput` / `MobilePlatformApplicationCreateAppleInput`
- `MobilePlatformApplicationUpdateInput` / `MobilePlatformApplicationUpdateAppleInput`
The five fields available on the Apple input are `appId`, `universalLinksEnabled`, `sharedWebCredentialsEnabled`, `appClipsEnabled`, and `appClipApplicationId`. None of them control path matching in the generated AASA file. The Admin UI under Online Store, Domains, and Apps / Mobile does not expose this either.
Use Case (Concrete Example)
Consider a merchant with a native iOS shopping app that handles product browsing and cart, but whose storefront also hosts marketing content, blog posts, help articles, and policy pages that are built for the web.
With the current AASA wildcard, every storefront URL force-opens the app, which causes:
- Customers without the app installed experience an interstitial or fall-through delay on every storefront link.
- Marketing, blog, and help content built for the web renders poorly inside the app’s webview.
- Support and policy pages can’t stay browsable without app context.
- SEO landing pages and paid-ad destinations need to stay in Safari so the page loads predictably and analytics or conversion tracking work as expected.
The current options are to disable Universal Links entirely (which defeats the purpose of registering the app for product and cart deep links) or to accept all the above issues. Migrating to a headless or Hydrogen setup purely to control one JSON file isn’t a proportionate response to what is, in Apple’s spec, a single config change.
Proposed Change
Add optional path configuration fields to the Apple create/update inputs, and surface them on the `AppleApplication` object. Two possible shapes, in order of preference:
Option 1 — Mirror Apple’s modern `components` spec:
input MobilePlatformApplicationCreateAppleInput {
appId: String!
universalLinksEnabled: Boolean
sharedWebCredentialsEnabled: Boolean
appClipsEnabled: Boolean
appClipApplicationId: String
components: \[AppleAasaComponentInput!\] # <- new
}
input AppleAasaComponentInput {
path: String!
exclude: Boolean
caseSensitive: Boolean
percentEncoded: Boolean
comment: String
}
type AppleApplication implements MobilePlatformApplication {
\# ...existing fields
components: \[AppleAasaComponent!\] # <- new
}
Option 2 — Simpler legacy `paths` mapping:
input MobilePlatformApplicationCreateAppleInput {
\# ...existing fields
paths: \[String!\] # <- new
excludedPaths: \[String!\] # <- new
}
Either shape can be fully backwards-compatible: if no path configuration is provided, Shopify keeps generating the current default AASA file. The equivalent fields should be added to `MobilePlatformApplicationCreateAndroidInput` for `assetlinks.json`, though Android’s spec is more constrained.
Prior Art
- Apple’s AASA spec — supports `components` (modern) and `paths` (legacy) for exactly this purpose. Shopify’s auto-generated file already uses the legacy `paths` array with `NOT` exclusions, so the underlying generator can already express path-level rules.
Previous Posts
Impact
This is a non-breaking addition that benefits any merchant running a native iOS app alongside a storefront that also serves web-first content (marketing, blogs, help, policies, SEO landing pages, paid-ad destinations). It removes the all-or-nothing tradeoff between Universal Links and a normal web browsing experience, without requiring a headless or Hydrogen migration.
