如何修復 iOS Universal Links (通用連結) 的 Bundle ID 與 AASA App ID 不符問題

為什麼 Bundle ID 不符會導致 iOS Universal Links 失效？ 當應用程式已簽署的應用程式識別碼 (Application Identifier) 與對應網域的 AASA appID/appIDs 項目不匹配時，Universal Links 就會失效，進而導致關聯網域 (Associated Domains) 驗證失敗。

Bundle ID (CFBundleIdentifier) 是一組獨一無二的字串，用於在 Apple 生態系統中識別特定的 iOS 應用程式。在 Universal Link 架構中，Bundle ID 會與應用程式識別碼前綴 (Application Identifier Prefix) 結合成應用程式識別碼 (Application Identifier)，作業系統會將其與代管的 apple-app-site-association 檔案進行驗證，以授權原生 URL 處理機制。

標準診斷鏈

下圖說明在 App 安裝與網域驗證期間執行的多層驗證序列：

Layer 1: Signed App Binary
       │
       ├── application-identifier (<Prefix>.<BundleID>)
       ├── com.apple.developer.team-identifier
       └── com.apple.developer.associated-domains (applinks:example.com)
                    │
                    ▼
Layer 2: AASA Delivery & CDN Ingestion
       │ (Apple-managed infrastructure retrieves origin AASA)
                    ▼
Layer 3: AASA Schema & Pattern Matching
       │ (Validates appIDs array and components/paths routing rules)
                    ▼
Layer 4: Device Association State
       │ (Operating system registers verified domains in local database)
                    ▼
Layer 5: Application Routing Execution
       │ (System routes matching URLs to application lifecycle handlers)

快速修復檢查清單：30 秒診斷流程

當 Universal Links 意外退回網頁處理時，請依序檢查下列項目：

• 提取已簽署的識別碼：檢查編譯後二進位檔內嵌的權利憑證，以取得準確的 application-identifier (<Prefix>.<BundleID>)。
• 驗證權利憑證格式：確認 com.apple.developer.associated-domains 包含確切的主機名稱（例如 applinks:subdomain.domain.com），且沒有不需要的路徑、查詢字串或結尾斜線。
• 稽核原始 AASA：取得 https://subdomain.domain.com/.well-known/apple-app-site-association，並確保已簽署的應用程式識別碼完整列在 appIDs 中。
• 驗證路徑匹配：確認目標 URL 符合 AASA 設定中定義的 components 或 paths 模式。
• 檢查網域範圍：確保關聯網域權利憑證涵蓋目標主機名稱，且該主機名稱備有對應的 AASA 設定。對於子網域，請視情況使用明確的主機名稱或支援的 *. 通配字元格式。
• 隔離開發模式：在開發簽署的建置版本上使用 ?mode=developer，以便在迭代期間略過 Apple CDN 快取。

為什麼 Bundle ID 與應用程式識別碼的準確性如此重要

應用程式識別碼的剖析

Universal Link 驗證不會評估 App 的顯示名稱、內部 URL scheme 或 bundle 名稱。根據 Apple 關於 applinks.Details 的說明文件，其安全模型嚴格依賴完整資格的應用程式識別碼，其結構如下：

其中：

• ApplicationIdentifierPrefix：在您的 Apple Developer 帳號設定中指派的 App ID 前綴（例如 9JA723G82S）。對許多現代開發者帳號而言，此數值與 10 字元的 Team ID 相同，但工程師應在 Apple Developer Portal 中驗證實際的前綴，而非假設兩者可互換。
• CFBundleIdentifier (Bundle ID)：在 Target 建置設定中定義的大小寫敏感、反向網域名稱字串（例如 com.example.mobileapp）。

在代管的 apple-app-site-association (AASA) JSON 檔案中，這個複合字串會出現在 appIDs 陣列或 appID 字典項目中（例如 9JA723G82S.com.example.mobileapp）。如果編譯後二進位檔內嵌的權利憑證與代管的 AASA 項目之間存在字元差異、大小寫不同或結尾空格，網域驗證就會失敗。

Bundle ID 不符是整合排查時優先級最高的原因之一，但它並不是 Universal Link 退回網頁的唯一原因。

關聯網域與 AASA 如何建立雙向關聯

不同於任何已安裝 App 都能宣告且無需網域驗證的自訂 URL scheme，Universal Links 建立了安全的雙向關聯：

• App 宣告網域：已編譯的 iOS App 透過在其程式碼簽章中納入 com.apple.developer.associated-domains 權利憑證，宣告其擁有特定網頁網域的所有權。
• 網域授權 App：網頁網域透過在 https://<domain>/.well-known/apple-app-site-association 或 https://<domain>/apple-app-site-association 代管 AASA JSON 檔案，確認其授予特定 App 路由授權。

在安裝或 App 更新期間，作業系統會將 App 已簽署的關聯網域權利憑證與針對該網域取得的 AASA 設定進行驗證。用於 App 關聯的應用程式識別碼必須與 AASA 設定中宣告的對應識別碼相符。識別碼相符後，要求的 URL 也必須符合設定好的 components 或 paths 規則。

失敗徵兆：為什麼不相符的識別碼會強制退回網頁

當發生應用程式識別碼不符的情況時，iOS 通常不會將其顯示為致命的執行時期例外狀況。相反地，此失敗會反映在關聯網域驗證狀態、裝置診斷或隨之而來的網頁退回行為中：

• 系統處理方式：當網域關聯失敗時，系統不會透過已驗證的 Universal Link 路徑叫用 App。根據 URL 的開啟方式與周遭的瀏覽器上下文，URL 會保留在網頁處理或退回至網頁處理，而不會傳遞至原生 App。
• 使用者體驗影響：當使用者在訊息 (Messages)、郵件 (Mail) 或 Safari 中點擊符合的網頁連結時，系統無法識別已授權的原生 App 對應，因而會在瀏覽器中開啟該網頁 URL。

參閱：Bundle ID ──> Universal Links 架構

Apple 的 CDN 如何擷取與快取 AASA 檔案

安裝交握與 Apple CDN 機制

當包含 com.apple.developer.associated-domains 權利憑證的應用程式安裝或更新時，系統會建立或重新整理關聯網域關係：

• CDN 仲介爬蟲：當系統建立或重新整理關聯網域關係時，會透過 Apple 的關聯網域基礎設施取得網域的 AASA 資料，並使用該資料來驗證關聯。
• 獨立的快取生命週期：由 Apple 管理的 CDN 控制自己的重新整理與快取生命週期，因此不應假設來源更新會立即透過 CDN 可見。測試變更時，請在適當情況下使用記錄的開發替代模式，並檢查裝置關聯狀態。
• 來源伺服器要求：來源網頁伺服器必須透過帶有有效、受信任 TLS 憑證的 HTTPS 提供 AASA 檔案（拒絕自簽憑證），並使用 application/json MIME 類型。AASA 代管不得依賴 HTTP 重新導向；AASA 端點應直接回傳帶有 HTTP 200 OK 的檔案。

AASA JSON 格式一致性

現代 iOS 版本支援細緻的 components 字典語法，同時維持與舊版 paths 陣列的相容性。

根據 Apple 開發者技術備忘錄 TN3155 關於偵錯 Universal Links 的說明，在特定的 details 項目中，開發者應使用現代的 appIDs + components 結構，或是舊版的 appID + paths 結構；請勿在同一個項目中混合使用這兩種結構，因為混合設定可能會產生非預期的驗證行為。

舊版的 AASA 範例通常包含 "apps": []。對於以現代 Apple OS 發行為目標的部署，不需要此金鑰；僅在支援明確預期它的舊版作業系統時才保留它。

診斷協定：逐步解決工作流程

步驟 1：使用 codesign 檢查已簽署的 App 權利憑證

若要判斷匯出的 IPA 或除錯建置版本是否包含確切預期的應用程式識別碼與關聯網域，請使用 macOS codesign 命令列公用程式直接檢查二進位檔的程式碼簽章。請一併檢查 application-identifier、com.apple.developer.team-identifier 與 com.apple.developer.associated-domains。

佈建設定檔 (Provisioning profile) 顯示設定檔允許哪些功能與網域；已簽署的可執行檔 (codesign) 則顯示出貨的二進位檔實際包含的內容。

步驟 2：稽核代管的 AASA JSON Schema

驗證來源伺服器是否代管了無需驗證或重新導向即可公開存取的有效 AASA 檔案。請注意，舊版的 AASA 範例通常包含 "apps": []，而以當代 iOS 發行為目標的現代設定則會省略此金鑰。

底下的標準 AASA JSON Schema 說明瞭使用現代 appIDs 與 components 結構的正確路徑路由：

```json
{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "9JA723G82S.com.example.mobileapp",
          "9JA723G82S.com.example.mobileapp.staging"
        ],
        "components": [
          {
            "/": "/product/*",
            "comment": "Matches product detail routes"
          },
          {
            "/": "/invite/*",
            "?": { "ref": "?*" },
            "comment": "Matches referral links with custom query parameters"
          },
          {
            "/": "/help/*",
            "exclude": true,
            "comment": "Excludes customer support URLs from native routing"
          }
        ]
      }
    ]
  }
}

步驟 3：執行診斷 CLI 工具 (codesign、swcutil、curl)

在提供 swcutil 診斷功能的 macOS 版本上，使用該工具來檢查或驗證關聯網域資料。由於指令選項可能會隨作業系統與工具鏈版本而異，請在執行下列診斷工作流程之前，先透過 swcutil --help 確認可用的選項：

# 0. Confirm available options (syntax may vary by OS and toolchain release)
swcutil --help

# 1. Unpack the exported IPA archive
unzip -q YourApp.ipa -d UnpackedApp

# 2. Extract and inspect signed entitlements directly from the executable binary
codesign -d --entitlements :- "UnpackedApp/Payload/YourApp.app" > signed-entitlements.plist 2>/dev/null
/usr/libexec/PlistBuddy -c "Print" signed-entitlements.plist

# 3. Check whether the AASA data can be downloaded for the domain using swcutil (macOS diagnostic tool)
sudo swcutil dl -d custom.opwakeup.com

# 4. Validate AASA pattern matching against a specific URL using swcutil
sudo swcutil verify -d custom.opwakeup.com -j ./apple-app-site-association -u https://custom.opwakeup.com/product/123

# 5. Query the Apple-managed Associated Domains CDN diagnostic endpoint directly
curl -i https://app-site-association.cdn-apple.com/a/v1/custom.opwakeup.com

在進行邊緣交付 (edge-delivered) AASA 資料疑難排解時，請檢查 Apple 管理的 Associated Domains CDN 端點。請將此端點視為診斷基礎設施，而非公開的 API 合約。

步驟 4：使用關聯網域開發人員模式進行 AASA 測試

根據 Apple 關於設定關聯網域的說明文件，Apple 為開發提供了替代模式。developer 模式 (?mode=developer) 允許符合資格的開發裝置略過 Apple 管理的 CDN，並透過 HTTPS 直接從關聯網域擷取 AASA 檔案。

下方的設定示範如何在不同的 Xcode 權利憑證設定中宣告開發人員模式：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>applinks:custom.opwakeup.com</string>
    </array>
</dict>
</plist>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>applinks:custom.opwakeup.com?mode=developer</string>
    </array>
</dict>
</plist>

一旦作業系統建立網域關聯，應用程式層級的路由就會使用標準的 UIKit 或 SwiftUI 生命週期委派來處理傳入的 URL 酬載：

import UIKit

// ----------------------------------------------------------------------------
// 1. UIKit AppDelegate Implementation
// ----------------------------------------------------------------------------
@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        return true
    }

    // Standard Apple Universal Link Continuation Callback
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
              let incomingURL = userActivity.webpageURL else {
            return false
        }
        
        print("Handling verified Universal Link: \(incomingURL.absoluteString)")
        
        // Dispatch incomingURL to internal router or SDK layer for parameter extraction
        return handleIncomingRoute(incomingURL)
    }

    private func handleIncomingRoute(_ url: URL) -> Bool {
        // Application-level destination routing logic
        // Note: Returning true indicates the app handled the activity, not that URL parsing succeeded.
        return true
    }
}

// ----------------------------------------------------------------------------
// 2. SceneDelegate Lifecycle Implementation (iOS 13+)
// ----------------------------------------------------------------------------
class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        if let userActivity = connectionOptions.userActivities.first(where: { $0.activityType == NSUserActivityTypeBrowsingWeb }),
           let incomingURL = userActivity.webpageURL {
            print("Cold-launch Universal Link: \(incomingURL.absoluteString)")
        }
    }

    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
           let incomingURL = userActivity.webpageURL {
            print("Foreground Universal Link: \(incomingURL.absoluteString)")
        }
    }
}

若要在實體硬體上啟用用戶端開發人員模式：

1. 在 iOS 16+ 上，前往設定 > 隱私權與安全性 > 開發人員模式並將其切換為開啟 (需要重新開機)。
2. 前往設定 > 開發人員 > 關聯網域開發 (Associated Domains Development) 並切換開關。
3. 安裝使用包含 ?mode=developer 權利憑證的開發佈建設定檔所簽署的開發建置版本。
4. 發行注意事項：請將 ?mode=developer 限制在開發與內部測試設定中，除非您的部署明確要求並支援該設定，否則請勿將其納入正式環境的關聯網域權利憑證中。

根本原因決策樹

Universal Link falls back to web handling
        │
        ├── Does signed application-identifier match AASA appIDs?
        │       ├── NO ──> Correct App ID Prefix or Bundle ID in AASA
        │       └── YES
        │
        ├── Does associated-domains entitlement list the exact domain?
        │       ├── NO ──> Add applinks:<domain> to target entitlements
        │       └── YES
        │
        ├── Does sudo swcutil dl -d <domain> succeed?
        │       ├── NO ──> Fix origin HTTPS, TLS certificates, or 301/302 redirects
        │       └── YES
        │
        ├── Does sudo swcutil verify match the target URL path?
        │       ├── NO ──> Correct components or paths syntax in AASA
        │       └── YES
        │
        └── Check device association state and internal application routing handlers

診斷矩陣：Universal Link 失效的根本原因

在 Xcode 中實作雙環境設定

管理多個建置設定 (Debug、Staging、Production)

企業開發管線經常在不同的建置環境中管理各自的 Bundle ID（例如 com.example.app.debug、com.example.app.staging、com.example.app）。

為了在所有建置設定中維持正常運作的 Universal Links：

• 明確的 AASA 宣告：代管的 AASA 檔案必須在其 appIDs 陣列中明確列出每個環境完整資格的應用程式識別碼：

  "appIDs": [
    "9JA723G82S.com.example.app",
    "9JA723G82S.com.example.app.staging",
    "9JA723G82S.com.example.app.debug"
  ]
  
  

• Target 專屬權利憑證：使用 Xcode 建置設定來為每個建置設定連結不同的 .entitlements 檔案，確保內部除錯建置版本不會查詢正式環境網域。

管理 Target 識別碼

進行 Universal Links 疑難排解時，請使用已簽署建置版本的正確 Bundle ID 與應用程式識別碼前綴，而不是依賴萬用字元識別碼。明確處理每個主機名稱：如果 App 宣告 example.com 與 www.example.com，請設定對應的關聯網域項目，並確保每個主機名稱都提供適當的 AASA 資料。確保權利憑證已在實際處理 Universal Links 的 Target 上設定好，並在適用的情況下分別驗證任何 App 擴充功能或 watchOS Target。

在 CI/CD 中驗證內嵌佈建設定檔與已簽署的二進位檔

在將二進位檔上傳至 TestFlight 之前，請在持續整合 (CI) 建置指令碼中自動化驗證權利憑證與應用程式識別碼：

# Automated CI validation script
security cms -D -i /path/to/embedded.mobileprovision > provision.plist

# 1. Inspect profile entitlements for allowed Associated Domains
/usr/libexec/PlistBuddy -c "Print :Entitlements:com.apple.developer.associated-domains" provision.plist

# 2. Extract actual signed entitlements from the compiled executable binary
codesign -d --entitlements :- "UnpackedApp/Payload/YourApp.app" > signed-entitlements.plist 2>/dev/null
SIGNED_APP_ID=$(/usr/libexec/PlistBuddy -c "Print :application-identifier" signed-entitlements.plist)
echo "Extracted Signed Application Identifier: $SIGNED_APP_ID"

# 3. Validate that signed Associated Domains match the target domain
/usr/libexec/PlistBuddy -c "Print :com.apple.developer.associated-domains" signed-entitlements.plist

# 4. Verify that the signed App ID exists in the hosted AASA file via Python
python3 -c "
import json, sys
signed_id = sys.argv[1]
data = json.load(open('apple-app-site-association'))
app_ids = [app for detail in data.get('applinks', {}).get('details', []) for app in detail.get('appIDs', [])]
if signed_id not in app_ids:
    print(f'AASA mismatch: {signed_id} not found in AASA appIDs: {app_ids}')
    sys.exit(1)
print(f'AASA consistency check passed: {signed_id} registered')
" "$SIGNED_APP_ID"

如果驗證指令碼以錯誤代碼結束，請中止建置管線，以防止將無法正常運作的深度連結 (deep linking) 二進位檔出貨至正式環境。

Universal Link 匹配條件

為確保路由可靠，必須同時滿足下列條件：

Signed App Configuration:
application-identifier = <ApplicationIdentifierPrefix>.<CFBundleIdentifier>
com.apple.developer.associated-domains = applinks:<hostname>

AASA Configuration:
appIDs = [..., "<ApplicationIdentifierPrefix>.<CFBundleIdentifier>", ...]
components / paths = Matching target URL paths and query parameters

System Eligibility:
1. Associated Domains entitlement explicitly contains the target hostname.
2. The signed Application Identifier matches an authorized entry in the domain's AASA appIDs.
3. The incoming URL satisfies the AASA routing patterns.
4. Device association state and user/browser context permit native application delegation.

即使權利憑證、AASA 關聯與 URL 模式全都匹配，觀察到的路由仍可能取決於裝置狀態以及使用者或瀏覽器上下文。例如，當使用者在 Safari 中瀏覽同一個網域時點擊通用連結，作業系統可能會尊重使用者留在 Safari 的意圖。

總結與決策框架

Universal Link 路由的可靠性取決於三個節點之間精確、字元級別的一致性：Apple Developer Portal App ID 設定、Xcode com.apple.developer.associated-domains 權利憑證，以及代管的 apple-app-site-association JSON 檔案。第三方 SDK 或路由框架無法修復失敗的作業系統網域關聯；它只能在 iOS 成功將 Universal Link 交付給應用程式之後處理 URL。如果 Universal Links 在作業系統層級正確關聯，但參數提取失敗，請將應用程式層級的路由層與網域關聯層分開檢查。

如果您的應用程式在 Universal Link 關聯成功後，也需要動態連結參數還原與引導路由，OpoInstall 為該應用程式層級的工作流程提供了一個選擇性的 SDK 層。

若要深入了解網域設定模式與深度連結整合，請參閱 OpoInstall 深度連結說明文件。

相關資料

• 概念：應用程式識別碼驗證、AASA Schema 驗證、Apple CDN 快取、權利憑證提取

• 技術：iOS Universal Links、Xcode 權利憑證、Apple Developer Portal、Shared Web Credentials

• 標準：IETF RFC 8259 (JSON 资料交换)、TLS 1.3 規格

• 診斷工具：Apple codesign CLI 工具、macOS swcutil 工具、Apple 管理的 CDN 快取查詢

官方說明文件

• Apple Developer 關於支援關聯網域的說明文件

• Apple Developer 關於設定關聯網域權利憑證的說明文件

• Apple Developer 技術備忘錄 TN3155：偵錯 Universal Links

• Apple Developer 關於在 App 中支援 Universal Links 的說明文件