1. 從一個真實場景說起為什么多個客戶端要共用一條拉起鏈接做過iOS端分享拉新或者跨端跳轉的同學大概率都遇到過這樣一個需求市場部給了一條推廣鏈接希望A應用、B應用、甚至H5頁面都能通過這一條鏈接把用戶拉起來而且拉起之后還要能區(qū)分是誰拉起來的、要跳到哪個具體頁面。聽起來簡單但真到配置Universal Link的時候坑就一個接一個冒出來了。Universal Link通用鏈接是蘋果在iOS 9之后推出的一種通過HTTPS鏈接直接喚起App的機制。它最大的好處是不需要像URL Scheme那樣彈一個是否打開某某App的確認框用戶點擊鏈接就能絲滑進入App體驗上幾乎和網(wǎng)頁跳轉一樣自然。但它的配置門檻也比URL Scheme高得多——需要在蘋果開發(fā)者后臺配置Associated Domains、需要在服務器上放置apple-app-site-association文件簡稱AASA文件、需要處理路徑匹配規(guī)則任何一環(huán)出問題鏈接就拉不起來。而多個客戶端共用同一條拉起鏈接這個需求把難度又往上抬了一檔。因為默認情況下一條Universal Link只能對應一個App的Team ID和Bundle ID組合。如果你有多個App比如主App、極速版、商家端、騎手端它們各自有不同的Bundle ID卻想共用同一個域名下的同一條鏈接就必須在AASA文件里做文章讓蘋果的匹配機制能同時識別多個App。這篇文章我會從原理講到實操把多客戶端共用Universal Link的完整配置流程、路徑匹配的坑、AASA文件的寫法、以及我實際踩過的幾個大坑都掰開揉碎講清楚。不管你是剛接觸Universal Link的新手還是已經(jīng)配過單App、現(xiàn)在要擴展到多App的老手都能從里面找到能直接抄作業(yè)的東西。2. Universal Link的工作機制與多客戶端共用的核心矛盾2.1 一條鏈接是怎么被系統(tǒng)認領的要理解多客戶端共用的難點得先搞清楚Universal Link的匹配流程。整個鏈路大致是這樣的用戶在任意位置短信、網(wǎng)頁、其他App點擊一條https://yourdomain.com/path的鏈接。iOS系統(tǒng)攔截這個點擊去本地緩存里查找這個域名對應的AASA文件記錄。系統(tǒng)拿當前設備上已安裝的所有App逐個比對AASA文件里聲明的appIDTeamID.BundleID和paths規(guī)則。如果某個App的appID匹配上且點擊的路徑也命中該App聲明的paths系統(tǒng)就直接喚起這個App并把完整URL傳給App的continueUserActivity回調(diào)。如果沒有任何App匹配鏈接就正常用Safari打開。關鍵點在于第3步系統(tǒng)是拿設備上已安裝的App去和AASA文件做匹配的。也就是說AASA文件里必須同時聲明所有希望被這條鏈接喚起的App的appID并且每個App的paths規(guī)則要寫清楚它負責響應哪些路徑。這里有個容易被忽略的細節(jié)AASA文件的緩存機制。iOS系統(tǒng)不會每次點擊都去服務器拉最新的AASA文件而是會在App安裝時拉一次之后由系統(tǒng)按自己的節(jié)奏通常是幾天或者App更新時刷新。蘋果的CDN也會緩存AASA文件。這就導致你改了AASA文件之后可能幾個小時甚至幾天都不生效。這是后面排查問題時必須記住的一條。2.2 多客戶端共用的三種典型訴求在實際項目里多個客戶端共用一條鏈接通常對應三種不同的業(yè)務訴求配置方式也不一樣訴求一同一App的不同變體。比如主App和極速版Bundle ID不同但功能高度重合希望同一條鏈接在裝了主App的設備上拉起主App裝了極速版的設備上拉起極速版。這種是最常見的。訴求二不同角色的App。比如用戶端和商家端同一條營銷鏈接用戶點了進用戶端商家點了進商家端。這種通常需要結合路徑或者參數(shù)來區(qū)分。訴求三App和H5兜底。裝了App就拉起App沒裝就用H5打開對應頁面。這是Universal Link的天然能力但多App場景下兜底邏輯會更復雜。這三種訴求的核心矛盾是一樣的一條鏈接、一個域名、一份AASA文件卻要服務多個appID。解決思路就是在AASA文件里用數(shù)組的方式聲明多個App并給每個App分配清晰的路徑規(guī)則避免路徑重疊導致的匹配歧義。2.3 為什么不能簡單粗暴地讓所有App聲明所有路徑有同學可能會想那我干脆讓每個App的paths都寫成[*]不就都能拉起來了嗎理論上可行但實際會出問題。當多個App都聲明了[*]系統(tǒng)在匹配時如果發(fā)現(xiàn)多個App都命中行為是不確定的——蘋果沒有明確文檔說明這種情況下會優(yōu)先拉起哪個。實測下來通常是按AASA文件里App聲明的順序或者按App安裝時間但這個順序并不可靠不同iOS版本表現(xiàn)還不一樣。所以正確做法是用路徑把不同App的職責區(qū)分開讓每條路徑只對應一個明確的App。3. AASA文件的正確寫法多App聲明的完整配置3.1 AASA文件的基本結構AASA文件是一個純JSON文件必須放在域名的根目錄下路徑固定為https://yourdomain.com/.well-known/apple-app-site-association。注意幾個硬性要求文件必須通過HTTPS訪問不能有重定向301/302都不行必須是200直接返回。Content-Type必須是application/json不能是text/plain。文件不能超過128KB未壓縮。不需要.json后綴文件名就是apple-app-site-association。一個支持多App的AASA文件結構大概長這樣{ applinks: { apps: [], details: [ { appID: TEAMID1.com.example.app.main, paths: [/share/*, /promo/*, /home/*] }, { appID: TEAMID2.com.example.app.lite, paths: [/share/*, /promo/*] }, { appID: TEAMID3.com.example.app.merchant, paths: [/merchant/*, /shop/*] } ] } }這里有幾個關鍵點要展開說。apps字段必須是一個空數(shù)組這是蘋果的歷史遺留字段現(xiàn)在填任何東西都會被忽略但必須存在且為空。details是一個數(shù)組每個元素代表一個App的聲明。appID的格式是TeamID.BundleIDTeamID是蘋果開發(fā)者賬號的團隊ID10位字符BundleID就是App的包名。這兩個必須完全匹配錯一個字符都匹配不上。paths是路徑規(guī)則數(shù)組支持通配符*和?。*匹配任意多個字符?匹配單個字符。注意路徑是區(qū)分大小寫的/Share/*和/share/*是兩條不同的規(guī)則。3.2 多App路徑分配的實戰(zhàn)策略路徑分配是整套配置里最需要動腦子的地方。我的經(jīng)驗是遵循先分域、再分路徑的原則。所謂分域是指如果不同App的業(yè)務差異大盡量用不同的路徑前綴把它們隔開。比如用戶端用/u/*商家端用/m/*這樣AASA文件里各App的paths完全不重疊匹配邏輯最清晰也最不容易出問題。如果業(yè)務上確實需要共用某些路徑比如/share/*這種營銷鏈接用戶端和極速版都要響應那就讓多個App聲明同一條路徑。這時候系統(tǒng)會優(yōu)先拉起哪個實測下來如果兩個App都裝了通常是AASA文件里排在前面的那個App被拉起。但這個行為不是蘋果官方保證的所以如果你的業(yè)務強依賴必須拉起某一個就不要讓路徑重疊而是通過URL參數(shù)在App內(nèi)部再做一次判斷。我一般會這樣設計路徑路徑前綴負責App用途/share/*主App、極速版分享拉新兩者都響應/promo/*主App、極速版活動推廣兩者都響應/merchant/*商家端商家專屬獨占/rider/*騎手端騎手專屬獨占/web/*無H5兜底不聲明走網(wǎng)頁這樣設計的好處是營銷類鏈接多端共用業(yè)務類鏈接各端獨占邏輯清晰后期擴展也方便。3.3 關于components字段的補充說明蘋果在iOS 13之后引入了新的components字段用來替代paths功能更強大支持查詢參數(shù)和片段匹配。寫法是這樣的{ applinks: { apps: [], details: [ { appID: TEAMID1.com.example.app.main, components: [ { /: /share/*, ?: { channel: ?* }, comment: 分享鏈接必須帶channel參數(shù) } ] } ] } }components里每個對象可以指定/路徑、?查詢參數(shù)、#片段的匹配規(guī)則還能用exclude字段排除某些情況。功能確實比paths強但兼容性上要注意iOS 13以下的設備不認components只認paths。所以如果你的App還要支持iOS 12及以下建議paths和components同時寫讓老系統(tǒng)走paths新系統(tǒng)走components。不過現(xiàn)在iOS 12以下的設備占比已經(jīng)極低了新項目基本可以只用components。但如果你的用戶群體里有大量老設備還是穩(wěn)妥點兩個都寫。4. 蘋果開發(fā)者后臺與Xcode的配置實操4.1 開發(fā)者后臺開啟Associated DomainsAASA文件配好了還得在蘋果開發(fā)者后臺給每個App開啟Associated Domains能力。步驟是登錄開發(fā)者后臺進入Certificates, Identifiers Profiles。找到對應的App ID注意是App ID不是Bundle ID雖然兩者通常一致。在Capabilities列表里勾選Associated Domains。保存后如果用的是手動簽名需要重新生成Provisioning Profile并下載。這一步每個App都要單獨做。多個App就重復多次。這里有個坑如果你用的是自動簽名Automatically manage signingXcode會自動幫你處理但前提是你在Xcode里配置了正確的Team。4.2 Xcode里的Associated Domains配置在Xcode里選中Target進入Signing Capabilities添加Associated Domains能力然后在Domains列表里添加applinks:yourdomain.com注意格式必須是applinks:前綴后面跟域名不要帶https://不要帶路徑不要帶末尾斜杠。正確的寫法是applinks:yourdomain.com錯誤的寫法包括applinks:https://yourdomain.com、applinks:yourdomain.com/、applinks:yourdomain.com/path。如果你有多個域名就加多行。如果同一個域名下有多個App每個App的Target里都要加這一行。這里有個細節(jié)如果你在開發(fā)階段想同時支持測試域名和生產(chǎn)域名可以兩個都加上applinks:yourdomain.com applinks:test.yourdomain.com但要注意測試域名的AASA文件也要配好否則測試鏈接拉不起來。4.3 多Target項目的配置要點如果你的項目是一個工程多個Target比如主App和極速版共用一個代碼庫那每個Target都要單獨配置Associated Domains。Xcode里切換Target分別添加。這時候容易出現(xiàn)的問題是某個Target忘了加導致那個App的鏈接拉不起來排查半天才發(fā)現(xiàn)是配置漏了。我的做法是做一個配置檢查清單每次新增App或者改域名時逐項核對[ ] 開發(fā)者后臺該App ID是否開啟Associated Domains[ ] Xcode該Target是否添加applinks:域名[ ] AASA文件是否聲明了該App的appID[ ] AASA文件該App的paths是否覆蓋了目標路徑[ ] Provisioning Profile是否包含Associated Domains權限這五步任何一步漏了鏈接都拉不起來。而且報錯信息往往很模糊不會直接告訴你哪一步錯了所以清單核對是最靠譜的辦法。5. 服務端AASA文件的部署與驗證5.1 部署位置與服務器配置AASA文件必須放在https://yourdomain.com/.well-known/apple-app-site-association。注意.well-known是個隱藏目錄很多服務器默認不允許訪問以點開頭的目錄需要單獨配置。以Nginx為例需要確保location /.well-known/apple-app-site-association { default_type application/json; add_header Content-Type application/json; root /var/www/html; }關鍵點是default_type application/json確保返回的Content-Type正確。有些服務器配置會把無后綴文件當成application/octet-stream返回蘋果的爬蟲就不認了。另外要確保這個路徑不被重定向。如果你的站點有全站HTTPS跳轉或者www跳轉要確保AASA文件的請求不會被跳轉。蘋果的爬蟲不跟隨重定向。5.2 驗證AASA文件是否可訪問部署完之后用curl驗證curl -I https://yourdomain.com/.well-known/apple-app-site-association期望看到的是HTTP/2 200和content-type: application/json。如果看到301/302說明有重定向要修。如果看到content-type: text/plain或application/octet-stream說明Content-Type不對也要修。再驗證內(nèi)容curl https://yourdomain.com/.well-known/apple-app-site-association確認返回的JSON格式正確沒有語法錯誤。可以用在線的JSON校驗工具過一遍或者本地用python -m json.tool驗證。5.3 蘋果CDN緩存與刷新AASA文件會被蘋果的CDN緩存。你更新文件后CDN不會立即刷新。蘋果官方?jīng)]有提供主動刷新CDN的接口只能等。通常幾小時內(nèi)會刷新但極端情況下可能要一兩天。在開發(fā)調(diào)試階段這個緩存很讓人頭疼。有幾個應對辦法用測試域名每次改配置換個新域名避開緩存。在設備上刪除App重裝會觸發(fā)重新拉取AASA文件。在設備設置里關閉再開啟開發(fā)者模式下的相關選項不同iOS版本路徑不同有時能觸發(fā)刷新。實測下來刪除App重裝是最可靠的方式。所以調(diào)試階段我一般會頻繁重裝App來驗證配置。6. App端的鏈接處理與多客戶端分發(fā)邏輯6.1 接收Universal Link的回調(diào)App端接收Universal Link的回調(diào)有兩個// iOS 13及以上SceneDelegate func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { guard userActivity.activityType NSUserActivityTypeBrowsingWeb, let url userActivity.webpageURL else { return } handleUniversalLink(url) } // iOS 13以下AppDelegate func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: escaping ([UIUserActivityRestoring]?) - Void) - Bool { guard userActivity.activityType NSUserActivityTypeBrowsingWeb, let url userActivity.webpageURL else { return false } handleUniversalLink(url) return true }如果你的App同時支持iOS 13以上和以下兩個都要實現(xiàn)。iOS 13以上走SceneDelegate以下走AppDelegate。如果只實現(xiàn)了AppDelegate在iOS 13以上的設備上可能收不到回調(diào)。6.2 多客戶端的分發(fā)邏輯設計當多個App共用一條鏈接時每個App收到的URL是一樣的。App需要自己解析URL判斷這個鏈接是不是給自己的以及要跳轉到哪個頁面。我的做法是在URL里帶足夠的參數(shù)讓App能自主判斷https://yourdomain.com/share/activity?channelwechattargetdetailid12345clientmainApp收到后解析client參數(shù)如果和自己的身份匹配就處理不匹配就忽略理論上不會發(fā)生因為系統(tǒng)已經(jīng)按AASA匹配過了但作為兜底邏輯保留。然后根據(jù)target和id參數(shù)路由到對應的頁面。這套邏輯建議封裝成一個統(tǒng)一的路由模塊所有App共用同一套解析代碼避免各端邏輯不一致。6.3 冷啟動和熱啟動的處理差異Universal Link在App冷啟動和熱啟動時的回調(diào)時機不一樣這是個大坑。冷啟動時App還沒起來系統(tǒng)會先啟動App然后在didFinishLaunchingWithOptions之后調(diào)用continueUserActivity。這時候如果你的首頁初始化邏輯比較重可能會在回調(diào)到達之前就渲染了首頁導致用戶看到首頁閃一下才跳到目標頁。熱啟動時App已經(jīng)在后臺系統(tǒng)直接調(diào)用continueUserActivity這時候處理起來相對簡單。我的處理方式是在App啟動時先判斷是不是通過Universal Link啟動的如果是就先不渲染首頁等回調(diào)到了再決定跳哪里。具體做法是在didFinishLaunchingWithOptions里檢查launchOptions[.userActivityDictionary]如果有值說明是Universal Link啟動設置一個標志位首頁初始化時根據(jù)標志位決定是否延遲渲染。這個細節(jié)不做的話用戶體驗會很差——點個鏈接App打開先閃一下首頁再跳到目標頁感覺像卡了一下。7. 常見問題排查與避坑經(jīng)驗實錄7.1 鏈接拉不起來的分層排查法Universal Link拉不起來是最常見的問題排查起來要有章法。我總結了一個從外到內(nèi)的排查順序排查層級檢查項常見問題第一層AASA文件能否HTTPS訪問、Content-Type、JSON格式重定向、Content-Type錯誤、JSON語法錯第二層appID匹配TeamID和BundleID是否正確TeamID寫錯、BundleID大小寫不一致第三層路徑匹配paths是否覆蓋目標路徑路徑大小寫、通配符位置錯誤第四層App配置Associated Domains是否開啟開發(fā)者后臺沒開、Xcode沒配第五層系統(tǒng)緩存AASA是否被緩存改了沒生效需重裝App按這個順序逐層排查基本能定位到問題。我遇到過最坑的一次是TeamID寫錯了一位排查了兩天才發(fā)現(xiàn)因為報錯信息完全不提示這個。7.2 路徑匹配的常見陷阱路徑匹配有幾個容易踩的坑大小寫敏感/Share/*和/share/*不匹配。URL路徑是區(qū)分大小寫的AASA里的paths也要嚴格對應。通配符位置/share/*能匹配/share/abc和/share/abc/def但/share*會匹配/shareabc語義不同。要明確你的意圖。末尾斜杠/share/*不匹配/share沒有斜杠如果需要匹配要單獨加一條/share。查詢參數(shù)paths不匹配查詢參數(shù)/share/*能匹配/share/abc?x1因為查詢參數(shù)不參與路徑匹配。但如果用components可以用?字段匹配查詢參數(shù)。7.3 多App場景下的優(yōu)先級問題前面提到過多個App聲明同一路徑時系統(tǒng)拉起哪個App是不確定的。我實測過幾次結論是如果只有一個App安裝了那毫無疑問拉起它。如果多個App都安裝了通常拉起AASA文件里排在前面的那個但這個順序在不同iOS版本上表現(xiàn)不一致。如果AASA文件里App順序變了拉起結果也可能變。所以如果你的業(yè)務強依賴必須拉起某個特定App就不要讓路徑重疊。正確做法是給不同App分配不同路徑或者用URL參數(shù)在App內(nèi)部做二次判斷。7.4 調(diào)試工具與日志技巧調(diào)試Universal Link時有幾個實用技巧用蘋果自帶的swcutil工具在設備上通過特定方式調(diào)用可以查看系統(tǒng)緩存的AASA文件內(nèi)容確認系統(tǒng)拉到的是不是你最新的配置。在App里打日志把收到的URL完整打印出來確認回調(diào)有沒有觸發(fā)、URL是什么。用Safari的開發(fā)者工具連接設備可以看網(wǎng)絡請求確認AASA文件有沒有被拉取。如果條件允許用真機調(diào)試模擬器對Universal Link的支持不完整很多問題在模擬器上復現(xiàn)不了。我個人最常用的是在continueUserActivity回調(diào)里打日志配合刪除App重裝基本能覆蓋大部分調(diào)試場景。8. 多客戶端共用的進階優(yōu)化與擴展思路8.1 用中間頁做統(tǒng)一入口如果你的App數(shù)量多、路徑規(guī)則復雜可以考慮加一個中間頁做統(tǒng)一入口。所有鏈接先指向一個H5中間頁中間頁根據(jù)User-Agent、URL參數(shù)等判斷該跳哪個App然后用Universal Link或者URL Scheme拉起。這樣做的好處是AASA文件只需要聲明中間頁的路徑各App的路徑規(guī)則可以簡化中間頁可以做更靈活的兜底邏輯比如沒裝App就引導下載。壞處是多了一次跳轉體驗上略慢而且中間頁本身要處理各種邊界情況。8.2 動態(tài)AASA文件的實現(xiàn)如果你的App列表經(jīng)常變或者需要按地區(qū)、按渠道返回不同的AASA文件可以做一個動態(tài)的AASA接口。服務器根據(jù)請求的來源比如User-Agent、IP地區(qū)動態(tài)生成AASA內(nèi)容返回。但要注意蘋果的爬蟲拉取AASA文件時請求頭里不一定帶足夠的信息讓你區(qū)分。而且CDN緩存會讓動態(tài)邏輯失效。所以動態(tài)AASA適合做灰度或者A/B測試不適合做核心的匹配邏輯。8.3 與URL Scheme的配合使用Universal Link雖然體驗好但有個限制只能通過用戶點擊觸發(fā)不能在App內(nèi)部用代碼直接打開另一個App。如果你的場景需要在App內(nèi)跳轉到另一個App還是得用URL Scheme。我的建議是兩者配合對外分享的鏈接用Universal Link保證點擊體驗App內(nèi)部跳轉用URL Scheme保證可控性。兩套機制共用同一套路由解析邏輯避免維護兩份代碼。9. 我踩過的幾個真實大坑第一個坑是AASA文件的Content-Type。我一開始用對象存儲托管AASA文件對象存儲默認給無后綴文件返回application/octet-stream蘋果爬蟲不認鏈接死活拉不起來。后來改成用Nginx托管顯式設置Content-Type才解決。這個坑排查了很久因為從瀏覽器訪問文件內(nèi)容是正常的只有Content-Type不對。第二個坑是TeamID和BundleID的匹配。我們有個App是從別的團隊遷移過來的TeamID變了但AASA文件里還寫著舊的TeamID導致這個App的鏈接一直拉不起來。后來把AASA文件里的appID全部核對了一遍才發(fā)現(xiàn)。第三個坑是路徑大小寫。我們的分享鏈接路徑是/Share/xxx首字母大寫但AASA文件里寫的是/share/*小寫結果就是拉不起來。URL路徑是區(qū)分大小寫的這個細節(jié)很容易忽略。第四個坑是冷啟動閃首頁。前面提到過冷啟動時App先渲染首頁再跳轉用戶看到閃一下。后來在啟動邏輯里加了判斷如果是Universal Link啟動就延遲渲染首頁才解決。這幾個坑的共同點是報錯信息都不明確只能靠經(jīng)驗和系統(tǒng)排查。所以我把排查清單和驗證步驟都固化下來每次配置新App或者改域名時逐項核對能省很多時間。10. 一套可直接復用的配置模板最后給一套我實際在用的配置模板多App共用一條鏈接的場景可以直接參考。AASA文件模板{ applinks: { apps: [], details: [ { appID: TEAMID1.com.example.app.main, paths: [/share/*, /promo/*, /home/*], components: [ { /: /share/* }, { /: /promo/* }, { /: /home/* } ] }, { appID: TEAMID1.com.example.app.lite, paths: [/share/*, /promo/*], components: [ { /: /share/* }, { /: /promo/* } ] }, { appID: TEAMID2.com.example.app.merchant, paths: [/merchant/*], components: [ { /: /merchant/* } ] } ] } }Xcode Associated Domains配置applinks:yourdomain.comApp端路由處理的核心邏輯func handleUniversalLink(_ url: URL) { guard let components URLComponents(url: url, resolvingAgainstBaseURL: false) else { return } let path components.path let queryItems components.queryItems ?? [] let params Dictionary(uniqueKeysWithValues: queryItems.map { ($0.name, $0.value ?? ) }) // 根據(jù)path分發(fā)到不同模塊 if path.hasPrefix(/share/) { routeToShare(params) } else if path.hasPrefix(/promo/) { routeToPromo(params) } else if path.hasPrefix(/merchant/) { routeToMerchant(params) } else { routeToHome() } }這套模板覆蓋了多App聲明、路徑分配、App端分發(fā)三個核心環(huán)節(jié)改改域名和BundleID就能用。實際項目里我還會加一層參數(shù)校驗和異常兜底確保任何異常URL都不會導致App崩潰。配置Universal Link這件事說到底就是細心加耐心。原理不復雜但細節(jié)多任何一個小地方出錯都會導致整個鏈路失效。把AASA文件、開發(fā)者后臺、Xcode、App端這四塊都配對了再配合分層排查法基本就沒有搞不定的場景。多客戶端共用一條鏈接的需求本質(zhì)上就是把這四塊配置乘以App的數(shù)量然后確保路徑規(guī)則不沖突。想清楚這一點剩下的就是按清單逐項落實了。