iOS Universal Links
iOS Universal Links 的 AASA 部署與除錯指南
網站的 AASA 檔案指定哪些 App 可以處理連結。請分別設定網站與簽署後的 App,再到裝置上測試一條允許及一條排除的路徑。
內容更新: · 維護者:Hung Chi-Hsueh · 修正回報
從簽署後的 App 確認識別資料
在 Mac 對簽署完成的 App 執行 codesign --display --entitlements - --xml YourApp.app,找出輸出中的 application-identifier。前 10 個字元是 Application Identifier Prefix,接著是一個句點與 Bundle ID。前綴可能與 Team ID 不同。只需將這兩項識別資料填入工具。
本工具使用 iOS 13 引入的 appIDs 與 components 格式,為單一 App 產生路徑規則。舊版 paths、查詢或片段比對、App Clips 與共用網站憑證須另外設定。
把範圍較小的例外規則放在前面
Apple 採用第一條命中的 components 規則。以下範例中,/shop/help/contact 命中排除規則,因此留在網頁。/shop/order/42 命中第二條,完成關聯驗證後可開啟 App。若對調順序,範圍更大的 /shop/* 會先命中。排除只影響連結的開啟方式,存取權限應由 App 與伺服器控管。
本工具會將 * 與 ? 視為路徑萬用字元。請只填路徑,省略網址的查詢與片段,並將 $() 替換變數改為明確模式。非 ASCII 路徑請依實際網址填寫百分號編碼,例如 /caf%C3%A9/*,再用裝置確認目標網址是否命中。
合併並發布檔案,再設定 App entitlement
第一次設定時,將檔案存成無副檔名的 apple-app-site-association。若既有 AASA 使用 appIDs 與 components,請先檢查 applinks.details,再更新這個 App 專用的項目,或新增一個。若多個 App 共用同一項目,請先分出這個 App 的 ID,再修改它的規則。保留其他 ID 原有的 components,並重測合併後的優先順序。也要保留 webcredentials、appclips 等服務。
若檔案使用舊版 appID 與 paths,請先遷移規則、確認行為後再合併。Apple 建議分開使用兩種格式。
將已檢查的 JSON 放在 https://example.com/.well-known/apple-app-site-association,並換成自己的主機名稱。請使用有效憑證的 HTTPS,直接回傳 HTTP 200 和 application/json,避免重新導向。若 entitlement 明列 example.com 和 www.example.com,兩個主機各需提供檔案。在 Xcode 加入 Associated Domains 與對應的 applinks:example.com,主機名稱前後不要加協定、路徑或斜線。
用安裝簽署版 App 的裝置驗證
安裝簽署版 App 後,從「備忘錄」分別開啟兩種路徑。也可依 Apple 文件使用裝置「開發者」設定中的 Universal Links 診斷。在瀏覽器網址列直接輸入網址,只會測到瀏覽器的導覽。Apple CDN 與裝置取得更新需要時間,重改規則前請先檢查正式回應與 App 的 entitlement。
產生器檢查輸入格式並保留規則順序。實際關聯由 Apple 依簽署後的 App 與已部署的網站驗證,產生器不會連線檢查兩者。
{
"applinks": {
"details": [{
"appIDs": ["ABCDE12345.com.example.shop"],
"components": [
{"/": "/shop/help/*", "exclude": true},
{"/": "/shop/*"}
]
}]
}
}資料可信度
資料來源
- Apple Developer · Supporting associated domains
- Apple Developer · URL components and precedence
- Apple Developer · Application Identifier Prefix and Universal Links
- Apple Developer · Inspect a signed app’s entitlements
- Apple Developer · Substitution variables
- Apple Developer · TN3155: Debugging universal links