iOS/tvOS SDK指南 iostvos-sdk-cookbook

创建回调函数：

• setRequestorComplete()

• 触发者 setRequestor()，会返回成功或失败。

• 成功表示您可以继续权利调用。

• displayProviderDialog(mvpds)

  • 触发者 getAuthentication() 仅当用户尚未选择提供程序(MVPD)且尚未进行身份验证时。
  • 此 mvpds parameter是用户可用的提供程序数组。

• setAuthenticationStatus(status, errorcode)

  • 触发者 checkAuthentication() 每次。
  • 触发者 getAuthentication() 仅当用户已进行身份验证并已选择提供程序时。
  • 返回的状态是成功或失败，错误代码描述失败的类型。

• navigateToUrl(url)

  • 触发者 getAuthentication() 在用户选择MVPD之后。 此 url 参数提供MVPD登录页面的位置。

• sendTrackingData(event, data)

  • 触发者 checkAuthentication()， getAuthentication()， checkAuthorization()， getAuthorization()， setSelectedProvider().
  • 此 event 参数指示发生的权利事件； data parameter是与事件相关的值的列表。

• setToken(token, resource)

  • 触发者 checkAuthorization() 和 getAuthorization() 成功授权查看资源后。
  • 此 token 参数是短期媒体令牌； resource parameter是用户有权查看的内容。

• 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)'

  • 触发者 getAuthentication() 当前请求者至少支持具有SSO支持的MVPD时。
  • 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().

用户选择提供程序后，请从获取用户MVPD的URL navigateToUrl: 或 navigateToUrl:useSVC: 回调并打开 UIWebView/WKWebView 或 SFSafariViewController 控制器并将该控制器定向到URL。

通过 UIWebView/WKWebView 或 SFSafariViewController 在上一步中实例化后，用户登陆MVPD的登录页面并输入登录凭据。 在控制器内执行了若干重定向操作。

用户成功登录后，应用程序层即会检测特定自定义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 parameter是与用户的身份验证令牌关联的受保护资源数组。 从用户的MVPD获得的授权信息的一个用途是装饰您的UI（例如，受保护内容旁边的锁定/解锁符号）。

• 触发器： preauthorizedResources() callback
• 执行点： 完成身份验证流程后

如果身份验证成功，请转到授权流。

调用 getAuthentication() 启动身份验证流程，或获取用户已进行身份验证的确认。
触发器：

• 此 presentTvProviderDialog() 回调（如果用户未经身份验证，并且当前请求者至少具有支持SSO的MVPD）。 如果没有任何MVPD支持SSO，将使用经典身份验证流程。

用户选择提供商后，AccessEnabler库将获取包含Apple VSA框架所提供信息的身份验证令牌。

此 setAuthenticationStatus() 将触发回调。 此时，用户应通过Apple SSO进行身份验证。

[可选] 调用 checkPreauthorizedResources(resources) 以检查用户有权查看哪些资源。 此 resources parameter是与用户的身份验证令牌关联的受保护资源数组。 从用户的MVPD获得的授权信息的一个用途是装饰您的UI（例如，受保护内容旁边的锁定/解锁符号）。

• 触发器： preauthorizedResources() callback
• 执行点： 完成身份验证流程后

如果身份验证成功，请转到授权流。

调用 getAuthentication() 启动身份验证流程，或获取用户已进行身份验证的确认。
触发器：

• 此 presentTvProviderDialog() 回调（如果用户未经身份验证，并且当前请求者至少具有支持SSO的MVPD）。 如果没有任何MVPD支持SSO，将使用经典身份验证流程。

用户选择提供商后， status() 将调用callback。 将提供注册码，AccessEnabler库将开始轮询服务器以获得成功的第二屏身份验证。

如果提供的注册码用于在第二个屏幕上成功进行身份验证， setAuthenticatiosStatus() 将触发回调。 此时，用户应通过Apple SSO进行身份验证。

[可选] 调用 checkPreauthorizedResources(resources) 以检查用户有权查看哪些资源。 此 resources parameter是与用户的身份验证令牌关联的受保护资源数组。 从用户的MVPD获得的授权信息的一个用途是装饰您的UI（例如，受保护内容旁边的锁定/解锁符号）。

• 触发器： preauthorizedResources() callback

• 执行点： 完成身份验证流程后

如果身份验证成功，请转到授权流。

调用 getAuthorization() 以启动授权流。

• 依赖关系： 与MVPD约定的有效ResourceID。
• 资源ID应当与在任何其他设备或平台上使用的资源ID相同，并且在MVPD中也将相同。 有关资源ID的信息，请参阅 识别受保护的资源

验证身份验证和授权。

• 如果 getAuthorization() 调用成功：用户具有有效的AuthN和AuthZ令牌（用户经过身份验证并有权观看请求的媒体）。

• 如果 getAuthorization() 失败：检查引发的异常以确定其类型（AuthN、AuthZ或其他内容）：

  • 如果这是身份验证(AuthN)错误，则重新启动身份验证流程。
  • 如果是授权(AuthZ)错误，则用户无权观看请求的媒体，并且应向用户显示某种错误消息。
  • 是否存在其他类型的错误（连接错误、网络错误等） 然后向用户显示相应的错误消息。

验证短媒体令牌。
使用Adobe Pass身份验证媒体令牌验证器库验证从返回的短期媒体令牌 getAuthorization() 调用：

• 如果验证成功：为用户播放请求的媒体。
• 如果验证失败：AuthZ令牌无效，应拒绝媒体请求，并向用户显示错误消息。

返回到正常应用程序流程。

用户选择要查看的媒体。

媒体是否受保护？ 您的应用程序会检查所选媒体是否受保护：

• 如果所选媒体受保护，您的应用程序将启动 授权流程 以上。

• 如果所选媒体未受保护，则为用户播放该媒体。

调用 logout() 以注销用户。 AccessEnabler清除所有缓存的值和令牌。 清除缓存后，AccessEnabler会进行服务器调用以清除服务器端会话。 请注意，由于服务器调用可能会导致到IdP的SAML重定向（这允许IdP端的会话清理），因此此调用必须遵循所有重定向。 因此，必须在UIWebView/WKWebView或SFSafariViewController控制器中处理此调用。

a.遵循与身份验证工作流相同的模式，AccessEnabler域通过 navigateToUrl: 或 navigateToUrl:useSVC: 回调，用于创建UIWebView/WKWebView或SFSafariViewController控制器并指示其加载回调中提供的URL url 参数。 这是后端服务器上注销端点的URL。

b.您的应用程序必须监控 UIWebView/WKWebView or SFSafariViewController 并检测在加载特定自定义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)。