如何設定 Safari 智慧型應用程式橫幅 (Smart App Banners) 以引導 iOS 跳轉

我該如何為網站新增智慧型應用程式橫幅？ 新增智慧型應用程式橫幅需要將 apple-itunes-app meta 標籤插入網站的 HTML head 中，定義您唯一的 app-id，並透過 app-argument 傳遞路由參數，以啟用 Safari 原生應用程式喚醒功能及 App Store 下載備援。

Apple 智慧型應用程式橫幅是一種原生 Safari 推廣組件，透過 HTML meta 標籤宣告，可在 iOS 和 iPadOS 的網頁頂端顯示一個簡潔的下載或開啟提示。它由 WebKit 直接呈現，能自動偵測應用程式的安裝狀態：已安裝時顯示「開啟」按鈕並傳遞情境參數，未安裝時則顯示「檢視」按鈕將使用者導向 App Store。

為什麼 Safari 智慧型應用程式橫幅對於 iOS 使用者獲取依然不可或缺

Safari 原生整合：零 JavaScript 開銷與一致的 OS 層級渲染

Apple 的原生智慧型應用程式橫幅代表了網頁內容與 iOS 應用程式之間的整合橋樑。與需要客戶端 DOM 操作、第三方樣式庫及持續重新計算佈局的自訂 JavaScript 橫幅不同，原生智慧型應用程式橫幅直接由 WebKit 在作業系統層級進行渲染。

由於 WebKit 原生管理佈局，該橫幅不會產生 JavaScript 執行開銷，也不會在頁面載入期間阻礙瀏覽器的主執行緒。橫幅在 iOS 和 iPadOS 螢幕尺寸上保持一致的顯示效果，並能平滑適應視窗旋轉、現代 iPhone 硬體的安全區域 (Safe Area) 以及動態字級等系統協助工具設定。

消除商店搜尋阻力：自動擷取應用程式圖示、標題、評分與價格

設定一般的網頁推廣提示通常需要行銷團隊手動查詢 App Store API，以顯示最新的應用程式圖示、開發者標題、在地化價格及總星級評分。當應用程式中繼資料變更時（例如季節性活動更新圖示或推出限時價格促銷），靜態的自訂橫幅很快就會過期。

原生智慧型應用程式橫幅消除了此維護負擔。當 WebKit 讀取到有效的 app-id 時，會直接與本地 App Store 服務溝通，自動獲取應用程式的生產中繼資料。Safari 會顯示官方的 App Store 圖示、標題、當前評分及在地化價格（例如「免費」或當地貨幣），網頁開發者無需撰寫硬編碼的行銷素材或管理在地化字串表。

系統層級狀態偵測：WebKit 如何區分已安裝與未安裝的使用者

網頁轉應用程式路由的一項持續挑戰是識別訪客裝置是否已安裝原生應用程式。基於隱私與安全性考量，瀏覽器沙盒嚴格禁止網頁 JavaScript 查詢本地應用程式註冊表或檢視已安裝軟體列表。

原生智慧型應用程式橫幅在平台層級解決了此挑戰。Safari 使用網頁 JavaScript 無法存取的系統層級機制來判斷應用程式是否已在裝置上提供。若對應 app-id 的應用程式已安裝，Safari 會顯示「開啟 (OPEN)」行動呼籲 (CTA)；若未安裝，則顯示「檢視 (VIEW)」CTA。此偵測完全在作業系統邊界內發生，既防止了客戶端指紋辨識，又協助訪客獲得準確且可操作的提示。

如何正確建構 Apple iTunes App Meta 標籤語法

剖析核心標籤屬性：app-id 與 app-argument

原生智慧型應用程式橫幅透過放置在文件 <head> 中的單一 HTML <meta> 元素設定。name 屬性必須精確設為 apple-itunes-app，而 content 屬性則接受由逗號分隔的鍵值對字串：

<meta name="apple-itunes-app" content="app-id=123456789, app-argument=myapp://product/detail/1024?campaign=spring_sale">

Apple 目前的智慧型應用程式橫幅文件定義了兩個主要支援參數：

• app-id (必要)：指派給 App Store Connect 中應用程式的唯一數字識別碼。此 ID 讓 WebKit 能夠解析正確的商店列表並查詢本地應用程式的安裝狀態。
• app-argument (選填)：當使用者點擊「開啟」時，Safari 傳遞給原生應用程式的有效 URI 字串（如自訂 URL Scheme 或 HTTPS 通用連結 Universal Link）。

較舊的智慧型應用程式橫幅參考文件記載了另一個用於合作夥伴追蹤的參數 affiliate-data。由於現行的 Apple 文件不再將其列為標準參數，除非另有依照目前的 Apple 服務合作夥伴指南驗證，否則請將其視為舊版行為。

嚴格的格式規範：驗證逗號分隔符與屬性引號

WebKit 的中繼資料解析器執行嚴格的結構規則，常見的語法錯誤會導致 Safari 忽略標籤：

• content 字串內的屬性必須以逗號分隔，不可使用分號或管道符號 (|)。
• 屬性值不得包含未編碼的空白字元或原始逗號字元。
• 屬性值不得在主要的 content 屬性字串內以嵌套引號包裹。

正確的標籤格式應遵循以下規範：

<meta name="apple-itunes-app" content="app-id=987654321, app-argument=https://app.example.com/promo/summer?source=safari_banner">

伺服器端渲染要求：確保在文件初始化 Head 中可靠地呈現中繼資料

前端架構經常嘗試在評估單頁應用程式 (SPA) 路由參數後，使用客戶端 JavaScript 框架（如 React、Vue 或 Angular）動態注入或更新 <meta name="apple-itunes-app"> 標籤。

為獲得確定性的橫幅行為，請在初始文件 <head> 中渲染 apple-itunes-app meta 標籤。Apple 建議採用伺服器端生成 app-argument 的方式；切勿依賴 document.head.appendChild() 或屬性修改等後載客戶端 DOM 變更，因為 WebKit 在初始文件串流評估期間就會解析文件元數據，且後續的 DOM 變更可能不會觸發橫幅設定的重新評估。

根據 W3C 文件中繼資料標準驗證 WebKit 中繼資料一致性

apple-itunes-app 元素符合 W3C HTML5 文件中繼資料規範，該規範允許在標準 <meta> 元素中使用廠商特定的擴充功能。WebKit 在評估嵌套的 app-argument 負載時，遵守 RFC 3986 URI 解析標準。

透過 App Argument 傳遞參數的技術機制

將深度連結負載編碼為 app-argument 字串：Scheme 與 HTTPS URL 的比較

app-argument 屬性建立了進入原生應用程式的情境化路由。網頁團隊可提供自訂 URI Scheme 或 HTTPS 通用連結 (Universal Link)：

1. 自訂 URL Scheme (myapp://product/detail/1024?id=1024)：啟動應用程式並將負載傳遞給原生自訂 URL 代理。自訂 Scheme 可提供直接的應用程式喚醒，但若在 Safari 之外被複製，則無法提供獨立的網頁備援。
2. HTTPS 通用連結 (https://app.example.com/detail/1024?id=1024)：傳遞已驗證網域的 URL。這確保了在 Universal Link 代理間的一致性參數解析，同時在其他平台上維持完整的網頁存取能力。

管理查詢參數跳脫以防止 WebKit 中的 URL 截斷

在 app-argument 中傳遞追蹤代幣、推薦碼或嵌套負載時，開發者必須正確建構 URL。由於 WebKit 使用逗號來分隔 content 字串中的屬性，深度連結參數內若包含未編碼的逗號，將會導致 app-argument 過早截斷。

請保留標準 URL 語法 (scheme://host/path?query)，並將查詢參數值內的保留字元（如逗號、空格或嵌套分隔符）進行編碼。在 HTML 原始碼檔案中，連接多個查詢參數的任何與號 (&) 都必須正確跳脫為 &：

<!-- 錯誤範例：未編碼的逗號會截斷屬性解析 -->
<meta name="apple-itunes-app" content="app-id=123, app-argument=myapp://route?filter=red,blue">

<!-- 正確範例：標準 URL 結構，使用 HTML 跳脫與號及編碼參數值 -->
<meta name="apple-itunes-app" content="app-id=123, app-argument=myapp://product/detail/1024?filter=red%2Cblue&amp;campaign=spring_sale">

將傳入參數視為不受信任的輸入：執行 Schema 與路徑允許清單

根據 OWASP 行動應用程式安全性測試指南關於不安全深度連結的指導，應用程式必須將所有透過 app-argument 傳遞的資料視為不受信任的外部輸入。由於中繼資料公開於網頁上，攻擊者可能構建異常參數以鎖定內部應用程式路由。

原生 iOS 程式碼必須對傳入的 URL 進行消毒：

• 針對嚴格的允許清單驗證傳入的 URL Scheme 與主機 (Host)。
• 在載入內部視圖控制器 (View Controllers) 前執行路徑前綴驗證。
• 針對長度與字元集限制對查詢參數值進行消毒，並對未知鍵值採用失敗關閉 (Fail-closed) 的處理方式。
• 傳遞工作階段情境時，使用短效且無意義的恢復識別碼，而非可重複使用的使用者驗證憑證。

使用情境化標籤產生功能綁定動態行銷代幣

針對處理付費搜尋或網紅流量的網頁，伺服器端模板引擎應在提供網頁前，將傳入的 UTM 參數與推薦碼動態直接注入 app-argument 字串中。

OpoInstall 是一個行動歸因與深度連結平台，協助成長團隊將網頁端的推薦代幣與原生 SDK 參數同步。請查閱 SDK 整合文件，以獲取將網頁參數映射至原生歸因監聽器的相關指導。

Safari 如何處理應用程式已安裝狀態與使用者關閉行為

開啟與檢視狀態級聯：WebKit 如何根據本地套件註冊進行路由

當包含 meta 標籤的頁面載入時，WebKit 會啟動背景解析序列：

1. 應用程式可用性檢查：WebKit 檢查裝置上是否已安裝與宣告的 app-id 相符的應用程式。
2. 按鈕狀態設定：
   • 已安裝：橫幅顯示「開啟 (OPEN)」。點擊此按鈕會調用原生應用程式啟動代理，並傳遞 app-argument 字串。
   • 未安裝：橫幅顯示「檢視 (VIEW)」。點擊此按鈕會將 Safari 導向對應 app-id 的 App Store 產品頁面。
3. App Store 返回流程：若未安裝的使用者點擊「檢視」，從 App Store 下載應用程式並返回 Safari，WebKit 會將橫幅 CTA 從「檢視」更新為「開啟」。

持續性的使用者關閉：了解 Safari 的抑制行為

如果使用者點擊智慧型應用程式橫幅左側的「x」圖示，Safari 會將此操作視為明確的關閉請求。

Apple 記載，當使用者關閉智慧型應用程式橫幅後，該橫幅在使用者返回該網頁時將不會再次出現。Safari 未公開 JavaScript API 或 meta 屬性來以程式方式強制顯示該原生橫幅。

私密瀏覽與裝置相容性限制

智慧型應用程式橫幅在私密視窗或特定裝置設定檔下的行為，應根據目標 Safari 與 iOS 版本進行評估。WebKit 在私密視窗中限制了某些跨情境互動，且智慧型應用程式橫幅主要設計供 iOS 和 iPadOS Safari 使用，而非桌面版 macOS 環境。

偵錯開發硬體上的關閉狀態重置協定

在品質保證 (QA) 與工程驗證期間，開發者常在 UI 測試中關閉橫幅，隨後發現其在測試裝置上被抑制顯示。

針對 QA 環境，清除 Safari 網站資料可能會在某些 iOS 版本上重置本地觀察到的抑制狀態，儘管 Apple 未將其列為正式的智慧型應用程式橫幅 API 合約。在開發硬體上評估橫幅時：

1. 開啟 iOS 測試裝置上的設定。
2. 導覽至Safari -> 進階 -> 網站資料。
3. 搜尋測試網域並選擇刪除，或選擇移除所有網站資料。
4. 從 iOS 應用程式切換器中強制退出 Safari，並在標準頁籤中重新載入測試 URL。

[使用者在行動 Safari 中瀏覽網頁]
                 │
                 ▼
[WebKit 讀取 <meta name="apple-itunes-app">]
                 │
     ┌───────────┴───────────┐
     ▼                       ▼
[應用程式已安裝]      [應用程式未安裝]
     │                       │
     ▼                       ▼
[顯示 "OPEN"]      [顯示 "VIEW"]
     │                       │
     ▼                       ▼
[使用者點擊按鈕]    [使用者點擊按鈕]
     │                       │
     ▼                       ▼
[傳遞 app-argument] [開啟 App Store 產品頁面]
     │
     ▼
[App Delegate 解析情境]
     │
     ▼
[載入目標應用程式內場景]

處理橫幅參數的原生 iOS 生命週期實作

在 SceneDelegate 中攔截自訂 Scheme 與通用連結參數

在利用 UISceneDelegate (iOS 13 及之後版本標準) 的現代 iOS 架構中，由智慧型應用程式橫幅傳遞的 URL，會根據 app-argument 是自訂 Scheme 還是通用連結，透過場景生命週期回呼進行處理：

• 自訂 URL Scheme (myapp://)：當傳遞自訂 Scheme 時，WebKit 會調用 scene(_:openURLContexts:)。應用程式檢查 UIOpenURLContext 集以提取並消毒 URL。
• 通用連結路由 (https://)：如果您的智慧型應用程式橫幅路由策略透過已驗證的通用連結進入應用程式，請透過標準通用連結生命週期處理該 URL (使用 NSUserActivityTypeBrowsingWeb 的 scene(_:continue:))。請根據您目標部署矩陣中使用的 Safari 與 iOS 版本驗證此路由。

用於非 Scene 架構的舊版 AppDelegate 處理方式

對於維護舊版非 Scene 生命週期的應用程式（或支援 iOS 12 及更早版本），自訂 Scheme 通常透過 application(_:open:options:) 攔截，而通用連結則透過 application(_:continue:restorationHandler:) 處理。

Apple 目前已棄用 application(_:open:options:)，轉而支援 UIScene URL 處理。僅在您的架構明確支援非 Scene 應用程式結構時，才保留舊版 AppDelegate 方法。

下方的技術實作展示了如何安全地設定 HTML meta 標籤，並跨自訂 Scheme 與通用連結路徑處理傳入的橫幅參數。開發者可從 OpoInstall SDK 下載中心下載經認證的原生框架。

<!-- HTML：伺服器端渲染的文件 Head，包含智慧型應用程式橫幅中繼資料 -->
<!DOCTYPE html>
<html lang="zh-Hant">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>產品推廣登陸頁面</title>

    <!-- 為 iOS/iPadOS 上的 Safari 設定 Apple 智慧型應用程式橫幅 -->
    <!-- app-id：必要的 App Store Connect 數字識別碼 -->
    <!-- app-argument：選填的有效 URI 字串 (自訂 Scheme 或通用連結) -->
    <!-- 注意：查詢參數中的 HTML 與號必須寫為 &amp; -->
    <meta name="apple-itunes-app" 
          content="app-id=123456789, app-argument=myapp://product/detail/1024?utm_source=safari_banner&amp;campaign=spring_sale">
</head>
<body>
    <h1>季節性活動</h1>
    <p>直接在我們的行動應用程式中檢視此推廣商品。</p>
</body>
</html>

// iOS：為智慧型應用程式橫幅參數路由支援 SceneDelegate 與舊版 AppDelegate
// 此為整合參考範例；請針對部署的 iOS 架構驗證方法簽名。
import UIKit

// 1. 已驗證橫幅路由的資料結構
struct ValidatedBannerRoute {
    let targetPath: String
    let parameters: [String: String]
}

// 2. 傳入 app-argument URL 的安全性驗證器 (支援自訂 Scheme 與通用連結)
class BannerRouteValidator {
    private static let allowedSchemes = ["myapp", "https"]
    private static let allowedHosts = ["product", "promo", "event", "app.example.com"]
    private static let allowedPathPrefixes = ["/detail/", "/view/", "/promo/"]
    private static let allowedKeys = ["utm_source", "campaign", "id", "source"]

    static func validate(url: URL) -> ValidatedBannerRoute? {
        guard let scheme = url.scheme?.lowercased(), allowedSchemes.contains(scheme) else {
            return nil
        }
        guard let host = url.host?.lowercased(), allowedHosts.contains(host) else {
            return nil
        }

        let path = url.path
        if !path.isEmpty && !allowedPathPrefixes.contains(where: { path.hasPrefix($0) }) {
            return nil
        }

        var sanitizedParams: [String: String] = [:]
        if let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
           let queryItems = components.queryItems {
            let validChars = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-")
            for item in queryItems {
                // 失敗關閉驗證：若存在未知查詢鍵值則拒絕 URL
                guard allowedKeys.contains(item.name) else { return nil }
                let value = item.value ?? ""
                if value.count <= 128 && value.rangeOfCharacter(from: validChars.inverted) == nil {
                    sanitizedParams[item.name] = value
                } else {
                    return nil
                }
            }
        }

        return ValidatedBannerRoute(targetPath: "\(host)\(path)", parameters: sanitizedParams)
    }
}

// 3. 現代 Scene 架構處理 (iOS 13+)
class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(
        _ scene: UIScene,
        willConnectTo session: UISceneSession,
        options connectionOptions: UIScene.ConnectionOptions
    ) {
        guard let _ = (scene as? UIWindowScene) else { return }

        // 處理透過智慧型應用程式橫幅傳遞的自訂 URL Scheme 啟動
        if let urlContext = connectionOptions.urlContexts.first {
            handleIncomingURL(urlContext.url)
        }

        // 處理透過通用連結路由啟動
        if let userActivity = connectionOptions.userActivities.first(where: { $0.activityType == NSUserActivityTypeBrowsingWeb }),
           let webpageURL = userActivity.webpageURL {
            handleIncomingURL(webpageURL)
        }
    }

    // 處理透過自訂 URL Scheme 恢復應用程式
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        if let url = URLContexts.first?.url {
            handleIncomingURL(url)
        }
    }

    // 處理透過通用連結恢復應用程式
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let webpageURL = userActivity.webpageURL {
            handleIncomingURL(webpageURL)
        }
    }

    private func handleIncomingURL(_ url: URL) {
        // 針對開發/QA 建置，記錄診斷 URL 結構；生產環境請避免記錄敏感代幣
        NSLog("[SmartAppBanner] 正在處理傳入的 app-argument URL: %@", url.absoluteString)
        
        if let route = BannerRouteValidator.validate(url: url) {
            DispatchQueue.main.async {
                AppNavigator.shared.routeToScene(path: route.targetPath, params: route.parameters)
            }
        } else {
            NSLog("[SmartAppBanner] 已拒絕未經授權或格式錯誤的 app-argument: %@", url.absoluteString)
            DispatchQueue.main.async {
                AppNavigator.shared.routeToDefaultHome()
            }
        }
    }
}

// 4. 舊版 AppDelegate 處理 (用於非 Scene 架構 / iOS 12 及更早版本)
@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    // 已被 Apple 棄用，改用 UIScene 生命週期；僅保留以支援舊版
    func application(
        _ app: UIApplication,
        open url: URL,
        options: [UIApplication.OpenURLOptionsKey : Any] = [:]
    ) -> Bool {
        NSLog("[SmartAppBanner] 舊版 AppDelegate 攔截到自訂 Scheme: %@", url.absoluteString)

        if let route = BannerRouteValidator.validate(url: url) {
            DispatchQueue.main.async {
                AppNavigator.shared.routeToScene(path: route.targetPath, params: route.parameters)
            }
            return true
        }

        DispatchQueue.main.async {
            AppNavigator.shared.routeToDefaultHome()
        }
        return false
    }

    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let webpageURL = userActivity.webpageURL {
            if let route = BannerRouteValidator.validate(url: webpageURL) {
                DispatchQueue.main.async {
                    AppNavigator.shared.routeToScene(path: route.targetPath, params: route.parameters)
                }
                return true
            }
        }
        return false
    }
}

將參數消毒並路由至指定的視圖控制器，避免執行漏洞

一旦被原生生命週期代理攔截，原始的 app-argument 字串必須先通過內部驗證器，才能驅動 UI 轉換：

• 允許清單驗證：確認請求的路由符合預定義的導航目標 (例如 /detail/, /promo/)。
• 參數類型強制：將傳入的 ID 轉換為預期的格式 (如正整數或英數字串)，拒絕未預期的符號或未知鍵值。
• 安全備援：若驗證失敗或目標項目不可用，將使用者安全導向預設的應用程式首頁，而非導致崩潰或呈現空白介面。

Safari 原生橫幅與動態跨平台應用程式橫幅的比較

架構分析：原生 WebKit 橫幅與 JavaScript 橫幅

在規劃網頁轉應用程式的成長漏斗時，工程團隊必須評估原生的 Safari 智慧型應用程式橫幅是否滿足其營運需求，或是需要動態的跨平台橫幅架構。

原生 WebKit 橫幅提供零成本效能與道地的 OS 樣式，但僅在 iOS 的 Safari 中運行。對於在 Android、Chrome 及嵌入式社交網頁檢視中獲取使用者的多通路平台而言，僅依賴 Apple 的原生橫幅將導致非 Safari 流量無法得到服務。

評估作業系統與行銷漏斗的功能取捨

下表對比了 Apple 智慧型應用程式橫幅與動態 JavaScript 渲染橫幅的技術能力與限制：

總結與決策框架

設定 Safari 智慧型應用程式橫幅可在行動網站與原生 iOS 應用程式之間提供高效、無 JavaScript 開銷的原生橋樑。透過使用原生 <meta name="apple-itunes-app"> 規範，工程團隊能提供使用者熟悉且可信賴的安裝提示，該提示符合平台設計指南並能自動呈現 App Store 價格。

然而，由於原生橫幅僅限於 iOS 上的 Safari，且依賴伺服器端的中繼資料生成，全面的行動成長策略通常會結合原生橫幅與動態的跨平台框架。將原生 WebKit 中繼資料與客戶端歸因引擎相結合，有助於為所有行動裝置訪客提供適當的原生應用程式場景跳轉路徑。

若要進一步了解如何實作全面的行動深度連結與跨網頁及原生平台的參數路由，請參考 SDK 整合文件，從 OpoInstall SDK 下載中心下載客戶端函式庫，探索 行動歸因實作參考，或至 OpoInstall 開發者控制台註冊您的應用程式。

相關資源

• 概念：智慧型應用程式橫幅 (Smart App Banner)、網頁轉應用程式跳轉、自訂 URL Scheme、應用程式參數解析、應用程式商店優化 (ASO)

• 技術：Apple WebKit, iOS UIKit, UIWindowSceneDelegate, Safari Metadata Engine

• 標準：IETF RFC 3986 統一資源識別碼 (URI)、W3C HTML5 文件中繼資料規範、OWASP 行動應用程式安全性測試指南 (MASTG)

• API：Apple apple-itunes-app Meta 標籤, UIKit application(_:open:options:), WebKit decidePolicyForNavigationAction

• 官方文件與參考：

  • Apple Developer 文件：使用智慧型應用程式橫幅推廣 App

  • Apple Developer 指導：支援應用程式中的通用連結

  • Apple Developer 文件：UIApplicationDelegate openURL

  • W3C HTML5 文件中繼資料規範

  • OWASP 行動應用程式安全性測試指南：不安全深度連結