Apple SSO逐步指南(iOS/tvOS SDK) apple-sso-cookbook-iostvos-sdk
簡介 Introduction
Adobe Primetime Authentication AccessEnabler iOS/tvOS SDK可支援平台單一登入(SSO)驗證，適用於在iOS、iPadOS或tvOS上執行之使用者端應用程式的一般使用者，操作方式為所謂的Apple SSO工作流程。
請注意，此檔案可當作現有AccessEnabler iOS/tvOS SDK檔案的擴充功能，您可以在這裡找到。
逐步指南 Cookbook
為了從Apple SSO使用者體驗中獲益，一個應用程式需要整合AccessEnabler iOS/tvOS SDK，並遵循下面提供的提示順序。
必要條件 Prerequisites
許可權
Settings -> TV Provider或tvOS上的Settings -> Accounts -> TV Provider*移至區段來變更其決定。Settings -> TV Provider或tvOS上的Settings -> Accounts -> TV Provider*移至區段來變更其決定。 ...
let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();
videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
switch (accessStatus) {
// The user allows the application to access subscription information.
case VSAccountAccessStatus.granted:
// Do nothing.
// The user has not yet made a choice or does not allow the application to access subscription information.
default:
// Incentivize users who refuse to give permission to access subscription information by explaining the benefits of the Single Sign-On (SSO) user experience. Please bear in mind that the user can change its decision by going to the application settings (TV Provider permission access) or to the section from Settings -> TV Provider on iOS/iPadOS or Settings -> Accounts -> TV Provider on tvOS.
...
}
}
...
回呼
- presentTVProviderDialog — 當Apple MVPD選擇器即將開啟時觸發回呼。
- dissiseTVProviderDialog — 當Apple MVPD選擇器即將關閉時觸發回呼。
錯誤報告
- N003 — 使用者從Apple MVPD選擇器中選取[其他電視提供者]選項。
- N004 — 使用者從Apple MVPD選擇器選取電視提供者，但目前的要求者不支援該電視提供者（整合或停用單一登入）。
- N005 — 使用者決定取消一般MVPD選擇器或Apple MVPD選擇器。
- VSA403 — 應用程式拒絕使用者的TV提供者許可權。
- VSA404 — 應用程式未決定使用者的TV提供者許可權。
- VSA503 — 視訊訂閱者帳戶中繼資料要求失敗，訊息 欄位中有更多內容。
- AAPL / APPL_ERROR — 視訊訂閱者帳戶中繼資料要求失敗，詳細資料 欄位中有更多內容。
驗證 Authentication
-
應用程式必須初始化 AccessEnabler iOS/tvOS SDK。
-
應用程式必須設定目前的要求者識別碼。
重要： 第二個步驟可能會觸發Apple SSO工作流程專屬的進階錯誤碼，以防下列其中一項 為true：
- VSA403 — 應用程式拒絕使用者的TV提供者許可權。
- VSA404 — 應用程式未決定使用者的TV提供者許可權。
- APPL - AccessEnabler iOS/tvOS SDK與視訊訂閱者帳戶架構之間的通訊發生錯誤。
第二個步驟會嘗試以無訊息方式將Apple SSO設定檔交換為Adobe驗證Token，以防上述 全部為false 且 下列全部為true：
- 使用者的電視提供者許可權已授予應用程式。
- 使用者已在裝置系統層級登入其電視提供者帳戶。
- AccessEnabler iOS/tvOS SDK從視訊訂閱者帳戶架構收到使用者的電視提供者識別碼。
- 使用者的電視提供者與應用程式的整合可透過Adobe Primetime TVE Dashboard啟用。
- 使用者透過應用程式的電視提供者單一登入功能可透過Adobe Primetime TVE控制面板啟用。
- 使用者的電視提供者不會透過Adobe Primetime TVE Dashboard降級。
- AccessEnabler iOS/tvOS SDK從視訊訂閱者帳戶架構收到使用者的電視提供者SAML回應。
專業秘訣： 此第二個步驟不會觸發任何其他回呼（除了setRequestorComplete回呼），因為應用程式並未明確起始驗證。
-
應用程式必須檢查驗證狀態。
重要： 第三個步驟可能會觸發Apple SSO工作流程專屬的進階錯誤碼，以防下列其中一項 為true：
- *VSA403 — 使用者已登入其電視提供者帳戶，位於
裝置系統層級，但使用者的電視提供者許可權為
已拒絕應用程式。 - *VSA404 — 使用者已登入其電視提供者帳戶，位於
裝置系統層級，但使用者的電視提供者許可權
應用程式的未決定。 - *APPL_ERROR — 使用者已登入其電視提供者
裝置系統層級的帳戶，但與
AccessEnabler iOS/tvOS SDK和視訊訂閱者帳戶
框架發生錯誤。
重要： 此第三個步驟會觸發具有 狀態 等於0的 setAuthenticationStatus 回呼，如果 下列其中一個為true：
- 使用者並未在裝置系統層級登入其TV提供者帳戶，或是透過一般驗證流程登入。
- 使用者已在裝置系統層級或透過一般驗證流程登入其電視提供者帳戶，但使用者的電視提供者驗證權杖TTL已通過。
- 使用者已在裝置系統層級或透過一般驗證流程登入其電視提供者帳戶，但使用者與應用程式的電視提供者整合已透過Adobe Primetime TVE Dashboard停用。
- 使用者已在裝置系統層級登入其電視提供者帳戶，但使用者使用應用程式的電視提供者單一登入已透過Adobe Primetime TVE Dashboard停用。
- 使用者已在裝置系統層級登入其TV提供者帳戶，但使用者的TV提供者許可權已遭拒。
- 使用者已在裝置系統層級登入其TV提供者帳戶，但使用者的TV提供者許可權未決定於應用程式。
- 使用者已在裝置系統層級登入其電視提供者帳戶，但AccessEnabler iOS/tvOS SDK與視訊訂閱者帳戶架構之間的通訊發生錯誤。
重要： 此第三個步驟將會觸發 setAuthenticationStatus 回呼，其中 狀態 等於1，若上述 全部為false。
- *VSA403 — 使用者已登入其電視提供者帳戶，位於
-
若先前的驗證狀態檢查觸發了 setAuthenticationStatus 回呼，且 狀態 等於0，應用程式將必須初始化驗證。
專業秘訣： 實作下列其中一個AccessEnabler iOS/tvOS SDK API getAuthentication或getAuthentication：filter。
重要： 如果下列其中一項 為true，此第四個步驟可能會觸發Apple SSO工作流程專屬的進階錯誤碼：
- VSA403 — 應用程式拒絕使用者的TV提供者許可權。
- VSA404 — 應用程式未決定使用者的TV提供者許可權。
- VSA503 - AccessEnabler iOS/tvOS SDK與視訊訂閱者帳戶架構之間的通訊發生錯誤。
- N003 — 使用者從Apple MVPD選擇器中選取[其他電視提供者]選項。
- N004 — 使用者從Apple MVPD選擇器選取電視提供者，但目前的要求者不支援該電視提供者（整合或停用單一登入）。
- N005 — 使用者決定取消一般MVPD選擇器或Apple MVPD選擇器。
重要： 此第四個步驟將遞補為一般驗證流程，觸發上述進階錯誤碼的displayProviderDialog回呼 one，若上述其中一個為true 。
重要： 此第四個步驟將退回至一般驗證流程，方法是觸發navigateToUrl或navigateToUrl：useSVC回呼及上述進階錯誤碼中的 none，以防使用者選取不支援Apple SSO，但存在於Apple MVPD選擇器中的電視提供者。
專業秘訣： AccessEnabler iOS/tvOS SDK會無訊息地呼叫setSelectedPrrovder API，以防使用者選取的電視提供者不支援Apple SSO，但存在於Apple MVPD選擇器中。
重要： 此第四個步驟會嘗試以無訊息方式交換Apple SSO設定檔以取得Adobe驗證Token，前提是 以上皆為false 且 以下皆為true：
- 使用者的電視提供者許可權已授予應用程式。
- 使用者已登入/目前正在裝置系統層級登入其電視提供者帳戶。
- AccessEnabler iOS/tvOS SDK從視訊訂閱者帳戶架構收到使用者的電視提供者識別碼。
- 使用者的電視提供者與應用程式的整合可透過Adobe Primetime TVE Dashboard啟用。
- 使用者透過應用程式的電視提供者單一登入功能可透過Adobe Primetime TVE控制面板啟用。
- 使用者的電視提供者不會透過Adobe Primetime TVE Dashboard降級。
- AccessEnabler iOS/tvOS SDK從視訊訂閱者帳戶架構收到使用者的電視提供者SAML回應。
專業秘訣： 此第四個步驟將會觸發 setAuthenticationStatus 回呼，不論 狀態 結果為何，因為驗證是由應用程式明確啟動。
中繼資料 Metadata
應用程式可以選擇使用AccessEnabler iOS/tvOS SDK的"tokenSource" 使用者中繼資料 API，判斷是否因為透過平台SSO登入而發生驗證。
...
accessEnabler.getMetadata([METADATA_OPCODE_KEY:Int(METADATA_USER_META), METADATA_USER_META_KEY: "tokenSource"])
...
登出 Logout
視訊訂閱者帳戶架構未提供API以程式方式登出已在裝置系統層級登入其電視提供者帳戶的人員。 因此，若要讓登出完全生效，使用者必須從iOS/iPadOS上的 Settings -> TV Provider 或tvOS上的 Settings -> Accounts -> TV Provider 明確登出。 使用者可以使用的另一個選項，是從特定應用程式設定區段（TV提供者許可權存取）撤銷存取使用者訂閱資訊的許可權。
- 應用程式必須從AccessEnabler iOS/tvOS SDK 起始登出。 這不會促進MVPD端的工作階段清理。
- 只有在觸發VSA203 狀態碼時，應用程式才必須指示/提示使用者從tvOS上的
Settings -> Accounts -> TV Provider明確登出。
- 應用程式必須從AccessEnabler iOS/tvOS SDK 起始登出。 這有助於MVPD端的工作階段清理。
- 只有在觸發VSA203 狀態碼時，應用程式才能指示/提示使用者從iOS/iPadOS上的
Settings -> TV Provider明確登出。