iOS/tvOS SDK逐步指南 iostvos-sdk-cookbook

建立回呼函式：

• setRequestorComplete()

• 由setRequestor()觸發，傳回成功或失敗。

• 成功表示您可以繼續權益呼叫。

• displayProviderDialog(mvpds)

  • 僅當使用者尚未選取提供者(MVPD)且尚未驗證時，才由getAuthentication()觸發。
  • mvpds引數是使用者可用的提供者陣列。

• setAuthenticationStatus(status, errorcode)

  • 每次都由checkAuthentication()觸發。
  • 只有在使用者已經驗證且已選取提供者時，才會由getAuthentication()觸發。
  • 傳回的狀態是成功或失敗，錯誤碼會說明失敗的型別。

• navigateToUrl(url)

  • 在使用者選取MVPD後由getAuthentication()觸發。 url引數提供MVPD登入頁面的位置。

• sendTrackingData(event, data)

  • 由checkAuthentication()、getAuthentication()、checkAuthorization()、getAuthorization()、setSelectedProvider()觸發。
  • event引數指出已發生的權利事件；data引數是與事件相關的值清單。

• setToken(token, resource)

  • 在成功授權檢視資源之後，由checkAuthorization()和getAuthorization()觸發。
  • token引數是短期的媒體權杖；resource引數是使用者有權檢視的內容。

• tokenRequestFailed(resource, code, description)

  • 授權失敗後由checkAuthorization()和getAuthorization()觸發。
  • resource引數是使用者嘗試檢視的內容；code引數是錯誤碼，指出發生的失敗型別；description引數描述與錯誤碼相關的錯誤。

• selectedProvider(mvpd)

  • 由getSelectedProvider()觸發。
  • mvpd引數提供使用者所選取之提供者的相關資訊。

• setMetadataStatus(metadata, key, arguments)

  • 由getMetadata().觸發
  • metadata引數提供您要求的特定資料；key引數是getMetadata()要求中使用的索引鍵；arguments引數是傳遞給getMetadata()的相同字典。

• 'preauthorizedResources(authorizedResources)'

  • 由checkPreauthorizedResources()觸發。

  • authorizedResources引數顯示使用者擁有的資源
    已獲得檢視的授權。

• 'presentTvProviderDialog(viewController)'

  • 當目前的要求者至少支援支援SSO的MVPD時，由getAuthentication()觸發。
  • viewController引數是Apple SSO對話方塊，必須顯示在主檢視控制器上。

• 'dissistTvProviderDialog(viewController)'

  • 由使用者動作觸發(從Apple SSO對話方塊選取「取消」或「其他電視提供者」)。
  • viewController引數是Apple SSO對話方塊，需要從主檢視控制器中解除。

啟動上層應用程式。

起始Adobe Pass驗證

a.呼叫init以建立Adobe Pass Authentication AccessEnabler的單一執行個體。

• 相依性： Adobe Pass驗證原生iOS/tvOS資料庫(AccessEnabler)

b.呼叫setRequestor()以建立程式設計師的身分；傳入程式設計師的requestorID以及（選擇性）Adobe Pass驗證端點的陣列。 若是tvOS，您還需要提供公開金鑰和密碼。 如需詳細資訊，請參閱無使用者端檔案。

• 相依性： ​有效的Adobe Pass驗證請求者ID (使用您的Adobe Pass驗證帳戶)
  管理員來安排此工作)。

• 觸發器：

  setRequestorComplete()回呼。

您有兩個實作選項：將要求者識別資訊傳送至後端伺服器後，UI應用程式層可以選擇下列兩種方法之一：

1. 等候觸發setRequestorComplete()回呼（AccessEnabler委派的一部分）。 此選項最能確定setRequestor()已完成，因此建議用於大部分實作。

2. 繼續而不等候setRequestorComplete()回呼的觸發，並開始發出權益要求。 這些呼叫(checkAuthentication、checkAuthorization、getAuthorization、getAuthorization、checkPreauthorizedResource、getMetadata、logout)已由AccessEnabler程式庫排入佇列，將在setRequestor()之後進行實際的網路呼叫。 例如，如果網路連線不穩定，此選項偶爾會中斷。

呼叫checkAuthentication()以檢查現有的驗證，而不啟動完整的驗證流程。 如果此呼叫成功，您可以直接繼續進行授權流程。 如果沒有，請繼續驗證流程。

• 相依性： ​成功呼叫setRequestor() （此相依性也適用於所有後續呼叫）。

• 觸發器： setAuthenticationStatus()回呼。

呼叫getAuthentication()以啟動驗證流程，或取得使用者已在的確認
已驗證。

觸發器：

• setAuthenticationStatus()回呼（如果使用者已經驗證）。 在此情況下，請直接進入授權流程。

• displayProviderDialog()回呼（如果使用者尚未驗證）。

向使用者呈現傳送至的提供者清單
displayProviderDialog()。

使用者選取提供者後，從navigateToUrl:或navigateToUrl:useSVC:回呼取得使用者MVPD的URL，並開啟UIWebView/WKWebView或SFSafariViewController控制器，將該控制器導向至URL。

透過上一步中具現化的UIWebView/WKWebView或SFSafariViewController，使用者登陸MVPD的登入頁面並輸入登入認證。 控制器內發生數個重新導向作業。

使用者成功登入後，您的應用程式層就會偵測到特定自訂URL的載入。 請注意，這個特定自訂URL實際上無效，控制器並非打算實際載入此URL。 應用程式必須將其解譯為驗證流程已完成，且關閉UIWebView/WKWebView或SFSafariViewController控制器是安全的訊號。 若需使用SFSafariViewController控制器，則特定自訂URL是由​ application's custom scheme ​所定義（例如adbe.u-XFXJeTSDuJiIQs0HVRAg://adobe.com），否則此特定自訂URL是由​ ADOBEPASS_REDIRECT_URL ​常數（即adobepass://ios.app）所定義。

關閉UIWebView/WKWebView或SFSafariViewController控制器，並呼叫AccessEnabler的handleExternalURL:url API方法，該方法會指示AccessEnabler從後端伺服器擷取驗證權杖。

（選擇性）呼叫checkPreauthorizedResources(resources)以檢查使用者有權檢視哪些資源。 resources引數是與使用者的驗證Token關聯的受保護資源陣列。 從使用者的MVPD取得的授權資訊的一種用途是裝飾您的UI （例如，受保護內容旁邊的鎖定/解鎖符號）。

• 觸發器： preauthorizedResources()回呼
• 執行點： ​在完成驗證流程之後

如果驗證成功，請繼續前往授權流程。

呼叫getAuthentication()以啟動驗證流程，或取得使用者已驗證的確認。
觸發器：

• presentTvProviderDialog()回呼（若使用者未驗證，且目前要求者至少擁有支援SSO的MVPD）。 如果沒有任何MVPD支援SSO，則會使用傳統驗證流程。

使用者選取提供者後，AccessEnabler程式庫會取得驗證權杖，其中包含Apple VSA架構提供的資訊。

將觸發setAuthenticatiosStatus()回呼。 此時，使用者應該使用Apple SSO進行驗證。

[選擇性]呼叫checkPreauthorizedResources(resources)以檢查使用者有權檢視哪些資源。 resources引數是與使用者的驗證Token關聯的受保護資源陣列。 從使用者的MVPD取得的授權資訊的一種用途是裝飾您的UI （例如，受保護內容旁邊的鎖定/解鎖符號）。

• 觸發器： preauthorizedResources()回呼
• 執行點： ​在完成驗證流程之後

如果驗證成功，請繼續前往授權流程。

呼叫getAuthentication()以起始
驗證流程，或取得使用者已在的確認
已驗證。
觸發器：

• presentTvProviderDialog()回呼（若使用者未驗證，且目前要求者至少擁有支援SSO的MVPD）。 如果沒有任何MVPD支援SSO，則會使用傳統驗證流程。

使用者選取提供者後，將會呼叫status()回呼。 將會提供註冊碼，且AccessEnabler程式庫會開始輪詢伺服器，以順利進行第二個熒幕驗證。

如果提供的註冊代碼已用於在第二個熒幕上成功驗證，則會觸發setAuthenticatiosStatus()回呼。 此時，使用者應該使用Apple SSO進行驗證。

[選擇性]呼叫checkPreauthorizedResources(resources)以檢查使用者有權檢視哪些資源。 resources引數是與使用者的驗證Token關聯的受保護資源陣列。 從使用者的MVPD取得的授權資訊的一種用途是裝飾您的UI （例如，受保護內容旁邊的鎖定/解鎖符號）。

• 觸發器： preauthorizedResources()回呼

• 執行點： ​在完成驗證流程之後

如果驗證成功，請繼續前往授權流程。

呼叫getAuthorization()以啟動授權流程。

• 相依性： ​與MVPD議定的有效ResourceID。
• 資源ID應與任何其他裝置或平台上使用的資源ID相同，且在所有MVPD上將會相同。 如需資源ID的相關資訊，請參閱識別受保護的資源

驗證驗證和授權。

• 如果getAuthorization()呼叫成功：使用者具有有效的AuthN和AuthZ權杖（使用者已經過驗證，並且獲得觀看請求媒體的授權）。

• 如果getAuthorization()失敗：請檢查擲回的例外狀況，以判斷其型別（AuthN、AuthZ或其他專案）：

  • 如果這是驗證(AuthN)錯誤，請重新啟動驗證流程。
  • 如果是授權(AuthZ)錯誤，則使用者無權觀看請求的媒體，並且應向使用者顯示某種錯誤訊息。
  • 如果有其他型別的錯誤（連線錯誤、網路錯誤等）， 然後向使用者顯示適當的錯誤訊息。

驗證短媒體權杖。
使用Adobe Pass驗證媒體權杖驗證器程式庫，驗證從上述getAuthorization()呼叫傳回的短期媒體權杖：

• 如果驗證成功：為使用者播放要求的媒體。
• 如果驗證失敗： AuthZ權杖無效，應拒絕媒體請求，並向使用者顯示錯誤訊息。

返回正常的應用程式流程。

使用者選取要檢視的媒體。

媒體是否受到保護？ 您的應用程式會檢查選取的媒體是否受到保護：

• 如果選取的媒體受到保護，您的應用程式會啟動上述授權流程。

• 如果選取的媒體未受保護，則播放該媒體
  使用者。

呼叫logout()將使用者登出。 AccessEnabler會清除所有快取值和Token。 清除快取之後，AccessEnabler會進行伺服器呼叫以清除伺服器端工作階段。 請注意，由於伺服器呼叫可能會導致SAML重新導向至IdP （這允許IdP端的工作階段清理），此呼叫必須在所有重新導向之後。 因此，必須在UIWebView/WKWebView或SFSafariViewController控制器內處理此呼叫。

a.遵循與驗證工作流程相同的模式，AccessEnabler網域會透過navigateToUrl:或navigateToUrl:useSVC:回呼，向UI應用程式層提出要求，以建立UIWebView/WKWebView或SFSafariViewController控制器，並指示載入回呼url引數中提供的URL。 這是後端伺服器上登出端點的URL。

b.您的應用程式必須監視UIWebView/WKWebView or SFSafariViewController控制器的活動，並偵測載入特定自訂URL的時間，因為它經過數個重新導向。 請注意，這個特定自訂URL實際上無效，控制器並非打算實際載入此URL。 應用程式必須將其解譯為登出流程已完成，且關閉UIWebView/WKWebView或SFSafariViewController控制器是安全的訊號。 當控制器載入這個特定自訂URL時，您的應用程式必須關閉UIWebView/WKWebView or SFSafariViewController控制器並呼叫AccessEnabler的handleExternalURL:urlAPI方法。 若需使用SFSafariViewController控制器，則特定自訂URL是由​ application's custom scheme ​所定義（例如adbe.u-XFXJeTSDuJiIQs0HVRAg://adobe.com），否則此特定自訂URL是由​ ADOBEPASS_REDIRECT_URL ​常數（即adobepass://ios.app）所定義。