（舊版） Amazon FireOS整合逐步指南 amazon-fireos-integration-cookbook

建立回呼函式：

• 'setRequestorComplete()'

  • 由setRequestor()觸發，傳回成功或失敗。 成功表示您可以繼續權益呼叫。

• displayProviderDialog(mvpd)

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

• 'setAuthenticationStatus(status， reason)'

  • 每次都由checkAuthentication()觸發。 只有在使用者已經驗證且已選取提供者時，才會由getAuthentication()觸發。

  • 傳回的狀態已驗證或未驗證，原因說明驗證失敗或登出動作。

• navigateToUrl(url)

  • 在AmazonFireOS SDK中略過，方法用於Android平台，其中由getAuthentication()在使用者選取MVPD後觸發。 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(resources)'

  • 由checkPreauthorizedResources()觸發。
  • authorizedResources引數會顯示使用者有權檢視的資源。

啟動上層應用程式。

啟動Adobe Pass驗證。

1. 呼叫getInstance以建立Adobe Pass驗證AccessEnabler的單一執行個體。

   • 相依性： Adobe Pass Authentication Native Amazon FireOS程式庫(AccessEnabler)

2. 呼叫 setRequestor()以建立程式設計師的識別碼；傳入程式設計師的requestorID以及（選擇性）Adobe Pass驗證端點的陣列。

   • 相依性： ​有效的Adobe Pass驗證請求者ID (請與您的Adobe Pass驗證帳戶管理員合作安排此專案。)

   • 觸發器： setRequestorComplete()回呼

在完全建立請求者身分之前，無法完成任何權益請求。 這實際上意味著，當setRequestor()仍在執行時，所有後續的軟體權利檔案要求（例如，checkAuthentication()）都會遭到封鎖。

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

1. 等候觸發setRequestorComplete()回呼（AccessEnabler委派的一部分）。 此選項最能確定setRequestor()已完成，因此建議用於大部分實作。
2. 繼續而不等候setRequestorComplete()回呼的觸發，並開始發出權益要求。 這些呼叫(checkAuthentication、checkAuthorization、getAuthorization、getAuthorization、checkPreauthorizedResource、getMetadata、logout)已由AccessEnabler程式庫排入佇列，將在setRequestor()之後進行實際的網路呼叫。 例如，如果網路連線不穩定，此選項偶爾會中斷。

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

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

觸發器：

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

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

使用者選取提供者後，WebView會開啟提供者頁面，供使用者登入

使用者成功登入後，WebView將會關閉。

呼叫getAuthenticationToken(),以指示AccessEnabler從後端伺服器擷取驗證Token。

[選擇性]呼叫checkPreauthorizedResources(resources)以檢查使用者有權檢視哪些資源。 resources引數是與使用者的驗證Token關聯的受保護資源陣列。

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

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

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

相依性：與MVPD議定的有效ResourceID。

注意： ResourceID應該與任何其他裝置或平台上使用的相同，而且在MVPD上將會相同。

驗證驗證和授權。

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

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

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

驗證短媒體權杖。

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

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

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

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

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

• 如果選取的媒體受到保護，您的應用程式會啟動上述授權流程。
• 如果選取的媒體未受到保護，則播放該媒體的使用者。

呼叫logout()將使用者登出。 AccessEnabler會清除使用者在共用單一登入之所有要求者上，為目前的MVPD取得的所有快取值和權杖。 清除快取之後，AccessEnabler會進行伺服器呼叫以清除伺服器端工作階段。 請注意，由於伺服器呼叫可能會導致SAML重新導向至IdP （這允許IdP端的工作階段清理），此呼叫必須在所有重新導向之後。 因此，此呼叫將在WebView控制項中處理，使用者看不到該呼叫。

注意： ​登出流程與驗證流程不同，因為使用者不需要以任何方式與WebView互動。 因此，在登出過程中，可以（而且建議）讓WebView控制項隱形（亦即：隱藏）。