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实际上无效，控制器不会将其实际加载。 必须由应用程序将其解释为验证流程已完成，并且关闭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参数是与用户的身份验证令牌关联的受保护资源的数组。 从用户的MVPD获得的授权信息的一个用途是装饰您的UI（例如，受保护内容旁边的锁定/解锁符号）。

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

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

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

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

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

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

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

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

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

调用getAuthentication()以启动
身份验证流程，或获取用户已存在的确认
已通过身份验证。
触发器：

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

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

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

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

• 触发器： preauthorizedResources()回调

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

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

调用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:回调向UI应用程序层发出请求，以创建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）定义。