文档Adobe PassAdobe Pass 身份验证

JavaScript SDK API参考 javascript-sdk-api-reference

Last update: Sat Jul 20 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
NOTE
此页面上的内容仅供参考。 使用此API需要来自Adobe的当前许可证。 不允许未经授权使用。

API参考 api-reference

这些函数启动与MVPD交互的请求。 所有调用都是异步调用；您必须实施回调来处理响应：

setRequestor (inRequestorID， endpoints， options) setrequestor(inRequestorID,endpoints,options)

描述： ​标识请求源自的站点。 在通信会话中，必须在任何其他API调用之前进行此调用。

参数：

  • inRequestorID -Adobe在注册期间分配给原始站点的唯一标识符。

  • 端点 — 此参数是可选的。 它可以是以下值之一：

    • 一个数组，允许您为Adobe提供的身份验证和授权服务指定端点（其他实例可用于调试目的）。 如果提供了多个URL，则MVPD列表由来自所有服务提供商的端点组成。 每个MVPD都与最快的服务提供程序相关联；即首先响应并支持该MVPD的服务提供程序。 默认情况下（如果未指定值），将使用Adobe服务提供程序(http://sp.auth.adobe.com/)。

    示例：

    • setRequestor("IFC", ["http://sp.auth-dev.adobe.com/adobe-services"])

  • 选项 — 包含应用程序ID值、访客ID值无刷新设置（后台登录注销）和MVPD设置(iFrame)的JSON对象。 所有值都是可选的。

    1. 如果指定，将在库执行的所有网络调用中报告Experience CloudvisitorID。 该值以后可用于高级分析报表。
    2. 如果指定了应用程序的唯一标识符 — applicationId — 则该值将作为X-Device-Info HTTP标头的一部分添加到应用程序发出的所有后续调用中。 稍后可以使用正确的查询从ESM报表中获取此值。

    注意： ​所有JSON密钥都区分大小写。

    示例：

   setRequestor("IFC", {
      "visitorID": "THE_ECID_VALUE",
      "applicationId": "APP_ID_VALUE"
  })
  • 通过指定登录（iFrameRequired ​键）和iFrame维度（iFrameWidth ​和​ iFrameHeight ​键）是否需要iFrame，程序员可以覆盖在Adobe Pass身份验证中配置的MVPD设置。 JSON对象具有以下模板：
    {
       "visitorID": <string>,
       "backgroundLogin": <boolean>,
       "backgroundLogout": <boolean>,
       "mvpdConfig":{
          "MVPD_ID_1":{
             "iFrameRequired": <boolean>,
             "iFrameWidth": <integer>,
             "iFrameHeight": <integer>
          },
          ...
          "MVPD_ID_N":{
             "iFrameRequired": <boolean>,
             "iFrameWidth": <integer>,
             "iFrameHeight": <integer>
          }
       }
    }

上述模板中的所有顶级键都是可选的，且具有默认值（backgroundLogin、backgroundLogut ​默认为false，而mvpdConfig为null — 表示不覆盖任何MVPD设置）。

  • 注意：为上述参数指定无效值/类型将导致未定义的行为。

以下是以下方案的示例配置：激活无刷新登录和注销，将MVPD1更改为全页重定向登录（非iFrame），并将MVPD2更改为iFrame登录(width=500 and height=300)：

    {
       "backgroundLogin": true,
       "backgroundLogout": true,
       "mvpdConfig":{
          "MVPD1":{
             "iFrameRequired": false
          },
          "MVPD2":{
             "iFrameRequired": true,
             "iFrameWidth": 500,
             "iFrameHeight": 300
          }
       }
    }

已触发​ 回调： setConfig()

返回页首

getAuthorization(inResourceID， redirect_url) getauthorization(inresourceid,redirect_url)

描述： ​请求对指定资源的授权。 每次客户尝试访问可授权资源时，均调用此函数以从Access Enabler获取短期授权令牌。 资源ID与提供授权的MVPD协商一致。

使用当前客户的缓存身份验证令牌。 如果未找到此类令牌，则先启动身份验证过程，然后继续授权。

参数：

  • inResourceID — 用户请求授权的资源的ID。
  • redirect_url — 可以选择提供重定向URL，以便MVPD的授权进程将用户返回到该页面，而不是返回启动授权的页面。

已触发​ 回调： setToken()成功，tokenRequestFailed失败

CAUTION
请尽量使用checkAuthorization()而不是getAuthorization()。 getAuthorization()方法将启动一个完整的身份验证流程（如果用户未经过身份验证），这可能会导致程序员端的复杂实施。

返回页首

getAuthentication(redirect_url) getauthentication(redirect_url

描述： ​请求对当前客户的身份验证。 通常为响应单击登录按钮而调用。 检查当前客户的缓存身份验证令牌。 如果未找到此类令牌，则启动身份验证过程。 这将调用默认或自定义提供程序选择对话框，然后使用选定的提供程序重定向到MVPD的登录界面。

成功后，为用户创建并存储身份验证令牌。 如果身份验证失败，提供程序会向您的setAuthenticationStatus()回调返回相应的错误消息。

参数：

  • redirect_url — 可以选择提供重定向URL，以便MVPD的身份验证进程将用户返回到该页面，而不是启动身份验证的页面。

已触发​ 回调： setAuthenticationStatus()，displayProviderDialog()，sendTrackingData()

返回页首

checkAuthN checkauthn

描述： ​检查当前客户的当前身份验证状态。 未与任何UI关联。

已触发​ 回调： setAuthenticationStatus()

返回页首

checkAuthorization(inResourceID) checkauthorization(inresourceid)

描述： ​应用程序使用此方法来检查当前客户和给定资源的授权状态。 首先检查身份验证状态。 如果未经过身份验证，则触发tokenRequestFailed()回调，此方法将退出。 如果用户通过了身份验证，它还会触发授权流。 查看有关[getAuthorization()] (#getAuthZ方法的详细信息。

TIP
使用检查状态功能 ​在请求授权之前，您不需要检查身份验证或授权状态。 例如，您可以调用这些函数来更新您自己的状态显示。 在需要任何用户交互时不要使用它们。

参数：

  • inResourceID — 用户请求授权的资源的ID。

已触发​ 回调：
setToken()，tokenRequestFailed()，sendTrackingData()，setAuthenticationStatus()

checkPreauthorizedResources(resources) checkPreauthorizedResources(resources)

描述： ​请求列表的“预检”授权状态
资源。

参数：

  • 资源：资源参数是应检查其授权的资源数组。 列表中的每个元素都应该是一个表示资源ID的字符串。 资源ID的限制与getAuthorization()调用中的资源ID的限制相同，即它是程序员与MVPD之间建立的商定值，或媒体RSS片段。

checkPreauthorizedResources(resources-cache=true) checkPreauthorizedResources(resources-cache=true)

从JS SDK版本4.0开始，提供此API变体

参数：

  • 资源：资源参数是应检查其授权的资源数组。 列表中的每个元素都应该是一个表示资源ID的字符串。 资源ID的限制与getAuthorization()调用中的资源ID的限制相同，即它是程序员与MVPD之间建立的商定值，或媒体RSS片段。

  • 缓存：检查预授权资源时是否使用内部缓存。 这是可选参数，默认为​ true。 如果为true，则其行为与上述API相同，这意味着对此函数的后续调用将使用内部缓存来解析预授权的资源。 为此参数传递​ false ​将禁用内部缓存，导致每次调用​ checkPreauthorizedResources API时都会调用服务器。

已触发​ 回调： preauthorizedResources()

返回页首

getMetadata(Key) getMetadata

描述： ​检索Access Enabler库公开为元数据的信息。

有两种类型的元数据：

  • 静态（身份验证令牌TTL、授权令牌TTL和设备ID）
  • 用户元数据 （这包括在身份验证和/或授权流期间从MVPD传递到用户设备的用户特定信息）

更多信息： 用户元数据

参数：

  • key：指定所请求元数据的ID：

    • 如果密钥为"TTL_AUTHN",，则进行查询以获取身份验证令牌过期时间。

    • 如果键为"TTL_AUTHZ"，而params是包含资源ID作为字符串的数组，则进行查询以获取与指定资源关联的授权令牌的过期时间。

    • 如果键为"DEVICEID"，则进行查询以获取当前设备ID。 请注意，此功能默认处于禁用状态，程序员应联系Adobe以获取有关启用和费用的信息。

    • 如果键来自以下用户元数据类型列表，则会将包含相应用户元数据的JSON对象发送到setMetadataStatus()回调函数：

    • "zip" — 邮政编码

    • "encryptedZip" — 加密的邮政编码

    • "householdID" — 家庭标识符。 在MVPD不支持子帐户的情况下，它将与用户ID相同。

    • "maxRating" — 用户的最大家长评级

    • "userID" — 用户标识符。 如果MVPD支持子帐户，并且用户不是主帐户，则userID将不同于householdID。

    • "channelID" — 用户有权查看的渠道列表

    • "is_hoh" — 标识用户是否为户主的标记

    • "encryptedZip" — 加密的邮政编码

    • "typeID" — 标识用户帐户是否为主/辅助帐户的标志

    • "primaryOID" — 家庭标识符

    • "postalCode" — 类似于邮政编码

    • "acctID" — 帐户ID

    • "acctParentID" — 帐户父级ID

    注意：程序员可用的实际用户元数据取决于MVPD提供的内容。 有关可用用户元数据的当前列表，请参阅用户元数据。

例如：

    // Assume that a reference to the AccessEnabler has been previously
    // obtained and stored in the "ae" variable

    ae.setRequestor("SITE");
    ae.checkAuthentication();

    function setAuthenticationStatus(status, reason) {
        if (status ==  1) {
            //user is authenticated, request metadata
            ae.getMetadata("zip");
            ae.getMetadata("maxRating");
        } else {
            ...
      }
    }

已触发​ 回调： setMetadataStatus()

返回页首

setSelectedProvider(providerid) setSelectedProvider

描述： ​当用户从提供程序选择UI中选择MVPD以便向访问启用程序发送提供程序选择时，调用此函数，或者使用null参数调用此函数，以防用户在不选择提供程序的情况下取消您的提供程序选择UI。

回调
已触发： setAuthenticationStatus()，sendTrackingData()

返回页首

getSelectedProvider() getSelectedProvider

描述： ​在“提供程序选择”对话框中检索客户选择的结果。 这可以在初次身份验证检查后的任何时间使用。

此函数是异步函数，并将其结果返回给selectedProvider()回调函数。

  • MVPD ​当前选定的MVPD，如果未选择MVPD，则返回null。
  • AE_State ​当前客户的身份验证结果为“新用户”、“用户未身份验证”或“用户已身份验证”之一

已触发​ 回调： selectedProvider()

返回页首

注销 logout

描述： ​注销当前客户，清除该用户的所有身份验证和授权信息。 从客户系统中删除所有authN和authZ令牌。

已触发​ 回调： setAuthenticationStatus()

返回页首

回调定义 calllback-definitions

您必须实施这些回调以处理对异步请求调用的响应：

entitlementLoaded() entitlementLoaded

描述： ​在Access Enabler已完成初始化并准备好接收请求时触发。 实施此回调以了解何时可以使用Access Enabler API开始通信。

返回页首

setConfig(configXML) setconfig(configXML)

描述： ​实施此回调以接收配置信息和MVPD列表。

参数：

  • configXML：保存当前REQUESTOR的配置（包括MVPD列表）的xml对象。

触发者： setRequestor()

返回页首

displayProviderDialog(providers) displayproviderdialog(providers)

描述： ​实现此回调以调用您自己的自定义提供程序选择UI。 您的对话框应使用显示名称（和可选徽标）提供客户的选择。 当客户作出选择并取消对话框时，在对​ setSelectedProvider() ​的调用中发送所选提供程序的关联ID。

参数：

  • 提供程序 — 表示所请求MVPD的对象数组：
    var mvpd = {
        ID: "someprov",
        displayName: "Some Provider",
        logoURL: "http://www.someprov.com/images/logo.jpg"
    }

触发者： getAuthentication()，getAuthorization()

返回页首

createIFrame(inWidth， inHeight) createIFrame(inWidth,inHeight)

描述： ​如果用户选择的MVPD需要iFrame才能显示其身份验证登录页UI，则实施此回调。

触发者： ​ setSelectedProvider()

返回页首

setAuthenticationStatus(isAuthenticated， errorCode) set-authn-status-isauthn-error

描述： ​实施此回调以接收身份验证状态（1=已通过身份验证或0=未通过身份验证）和描述性错误消息（如果在尝试确定身份验证状态时发生了任何错误）（检查成功完成时为空字符串）。

NOTE
如果您使用的是当前的高级错误报告系统，则可以忽略发送到此函数的errorCode参数。 但是， isAuthenticated标记仍用于跟踪权利流中用户的身份验证状态

参数：

  • isAuthenticated — 提供身份验证状态： 1 （已验证）或0 （未验证）。
  • 错误代码 — 确定身份验证状态时发生的任何错误。 空字符串（如果无）。

触发者： checkAuthentication()，getAuthentication()，checkAuthorization()

返回页首

sendTrackingData(trackingEventType， trackingData) sendTrackingData(trackingEventType,trackingData)

CAUTION
通过使用公共Java库(http://java.net/projects/user-agent-utils)和用户代理字符串派生设备类型和操作系统。 请注意，此信息仅以粗略的方式提供，用于按设备类别细分操作量度，但该Adobe对错误结果不承担任何责任。 请相应地使用新功能。

描述： ​实施此回调以在发生特定事件时接收跟踪数据。 例如，您可以使用它来跟踪有多少用户使用相同的凭据登录。 跟踪当前不可配置。 使用Adobe Pass Authentication 1.6时，sendTrackingData()还报告有关设备、 Access Enabler客户端和操作系统类型的信息。 sendTrackingData()回调保持向后兼容。

  • 设备类型的可能值：

    • 计算机
    • 平板电脑
    • 移动设备
    • gameconsole
    • 未知

  • Access Enabler客户端类型的可能值：

    • html5
    • ios
    • android

传递事件类型和关联信息的数组。 事件类型包括：

mvpdSelection
用户在提供程序选择对话框中选择了MVPD。
authenticationDetection
身份验证检查已完成。
authorizationDetection
授权请求已完成。
事件类型（字符串）
数据（数组）
mvpdSelection
0：选定的MVPD
1：设备类型
2：Access Enabler客户端类型
3：操作系统
authenticationDetection
0：令牌请求是否成功(true/false)
1： MVPD ID
2： GUID
3：令牌已在缓存中(true/false)
4：设备类型
5：Access Enabler客户端类型
6：操作系统
authorizationDetection
0：令牌请求是否成功(true/false)
1： MVPD ID
2： GUID
3：令牌已在缓存中(true/false)
4：错误
5：详细信息
6：设备类型
7：Access Enabler客户端类型
8：操作系统

触发者： checkAuthentication()，getAuthentication()，checkAuthorization()，getAuthorization()

返回页首

setToken(inRequestedResourceID， inToken) setToken(inRequestedResourceID,inToken)

描述： ​实施此回调以接收短期媒体令牌(inToken)以及发出授权请求或检查授权请求且已成功完成的资源(inRequestedResourceID)的ID。

触发者： checkAuthorization()，getAuthorization()

返回页首

tokenRequestFailed(inRequestedResourceID， inRequestErrorCode， inRequestDetailedErrorMessage) token-request-failed-error-msg

描述： ​实施此回调以在授权或检查授权请求失败时发出信号。 可以选择由MVPD用来提供要由程序员显示的自定义消息。

IMPORTANT
此回调函数是旧版原始Adobe Pass身份验证错误报告系统的一部分。 为了向后兼容，该函数会保留；但是，如果您已经使用当前的高级错误报告系统实施了自己的回调，则根本不需要使用此函数。 较新的错误报告系统提供了有关授权（或其他操作）失败原因的更多详细信息，以及针对每种错误或警告类型的建议操作过程。

参数：

  • inRequestedResourceID — 提供授权请求中使用的资源ID的字符串。
  • inRequestErrorCode — 显示Adobe Pass身份验证错误代码的字符串，用于指示失败的原因；可能的值是“用户未验证错误”和“用户未授权错误”；有关更多详细信息，请参阅下面的“回调错误代码”。
  • inRequestDetailedErrorMessage — 适用于显示的附加描述性字符串。 如果此描述性字符串由于任何原因不可用，则Adobe Pass身份验证发送空字符串​ (")。 MVPD可使用此命令来传递自定义错误消息或与销售相关的消息。 例如，如果订阅者被拒绝对资源的授权，则MVPD可以使用*inRequestDetailedErrorMessage*进行回复，例如： "您当前在包中无法访问此渠道。 如果要升级包，请单击*此处*。” ​消息由Adobe Pass身份验证通过此回调传递到程序员网站。 然后，程序员可以选择显示或忽略它。 Adobe Pass身份验证还可以使用*inRequestDetailedErrorMessage*将可能导致错误的情况通知程序员。 例如，“与提供商的授权服务通信时出现网络错误”。

触发者： checkAuthorization()，getAuthorization()

返回页首

preauthorizedResources(authorizedResources) preauthorizedResources(authorizedResources)

描述： ​回调由Access Enabler触发，该回调提供在调用checkPreauthorizedResources()后返回的授权资源列表。

参数：

  • authorizedResources：授权资源的列表。

触发者： checkPreauthorizedResources()

返回页首

setMetadataStatus(key， encrypted， data) setMetadataStatus(key,encrypted,data)

描述： ​由Access启用程序触发的回调，该启用程序提供通过getMetadata()调用请求的元数据。

更多信息： 用户元数据

参数：

  • 键（字符串）：发出请求的元数据的键。
  • encrypted (Boolean)：表示“值”是否已加密的标志。 如果为“true”，则“value”实际上将是实际值的JSON Web加密表示形式。
  • 数据（JSON对象）：表示元数据的JSON对象。对于简单请求(“TTL_AUTHN”、“TTL_AUTHZ”、“DEVICEID”)，结果是一个字符串（表示身份验证TTL、授权TTL或设备ID）。 在用户元数据请求的情况下，结果可以是表示元数据有效负载的原始或JSON对象。 JSON用户元数据对象的实际结构类似于以下内容：
    {
        updated: 1334243471,
        encrypted: ["encryptedProp"],
        data: {
            zip: ["12345", "34567"],
            maxrating: {
                "MPAA": "PG-13",
                "VCHIP": "TV-Y",
                "URL": "http://exam.pl/e/manage/ratings"
            },
            householdid: "3456",
            uid: "BgSdasfsdk23/dsaf3+saASesadgfsShggssd=",
            channelID: ["channel-1", "channel-2"]
    }

例如：

    // Implement the setMetadataStatus() callback
    function setMetadataStatus(key, encrypted, data) {
        if (encrypted) {
            //the metadata value is encrypted
            //needs to be decrypted by the programmer
            data = decrypt(data);
        }
        alert(key + "=" + data);
    }

触发者： getMetadata()


返回页首

selectedProvider(result) selectedProvider(result)

描述： ​实施此回调以接收当前选定的MVPD以及封装在result参数中的当前用户的身份验证结果。 result参数是一个具有以下属性的对象：

  • MVPD ​当前选定的MVPD，如果未选择MVPD，则返回null。
  • AE_State ​当前用户、“新用户”、“用户未验证”或“用户已验证”之一验证的结果

触发者： getSelectedProvider()

返回页首

回调错误代码 callback-error-codes

一般错误
内部错误
尝试处理请求时发生系统错误。
未选择提供程序错误
当客户在提供商选择对话框中取消时发生
提供程序不可用错误
当没有可用的提供程序时发生。
身份验证错误
一般身份验证错误
当原因未知或无法发布时返回。
内部身份验证错误
尝试进行身份验证时出现系统错误。
用户未验证错误
用户未经过身份验证。
多个身份验证请求错误
在完成第一个身份验证请求之前，已收到其他身份验证请求。
授权错误
一般授权错误
当原因未知或无法发布时返回。
内部授权错误
尝试授权时出现系统错误。
用户未授权错误
客户无权查看请求的内容。

返回页首

recommendation-more-help
3f5e655c-af63-48cc-9769-2b6803cc5f4b