Referencia de API de SDK para JavaScript javascript-sdk-api-reference
Referencia de API api-reference
Estas funciones inician solicitudes de interacción con una MVPD. Todas las llamadas son asincrónicas; debe implementar callbacks para gestionar las respuestas:
setRequestor (inRequestorID, extremos, opciones) setrequestor(inRequestorID,endpoints,options)
Descripción: identifica el sitio desde el que se originan las solicitudes. Debe realizar esta llamada antes que cualquier otra llamada de API en una sesión de comunicación.
Parámetros:
-
inRequestorID: el identificador único que el Adobe asignó al sitio de origen durante el registro.
-
extremos: este parámetro es opcional. Puede tener uno de los siguientes valores:
- Matriz que permite especificar extremos para los servicios de autenticación y autorización proporcionados por el Adobe (se pueden utilizar distintas instancias para la depuración). En caso de que se proporcionen varias direcciones URL, la lista de MVPD estará compuesta por los extremos de todos los proveedores de servicios. Cada MVPD está asociado con el proveedor de servicios más rápido; es decir, el proveedor que respondió primero y que admite ese MVPD. De forma predeterminada (si no se especifica ningún valor), se utiliza el proveedor de servicios de Adobe (http://sp.auth.adobe.com/).
Ejemplo:
setRequestor("IFC", ["http://sp.auth-dev.adobe.com/adobe-services"])
-
options: un objeto JSON que contiene el valor ID de aplicación, el valor ID de visitante, la configuración sin actualización (cierre de sesión en segundo plano) y la configuración de MVPD (iFrame). Todos los valores son opcionales.
- Si se especifica, se informará del ID de visitante de Experience Cloud en todas las llamadas de red realizadas por la biblioteca. El valor se puede utilizar posteriormente en informes de análisis avanzados.
- Si se especifica el identificador único de la aplicación -
applicationId
- el valor se agregará a todas las llamadas subsiguientes realizadas por la aplicación como parte del encabezado HTTP X-Device-Info. Este valor se puede obtener posteriormente de ESM informes con la consulta adecuada.
Nota: Todas las claves JSON distinguen entre mayúsculas y minúsculas.
Ejemplo:
setRequestor("IFC", {
"visitorID": "THE_ECID_VALUE",
"applicationId": "APP_ID_VALUE"
})
- El programador puede anular la configuración de MVPD configurada en la autenticación de Adobe Pass, especificando si se requiere o no un iFrame para el inicio de sesión (clave iFrameRequired) y las dimensiones del iFrame (iFrameWidth y iFrameHeight claves). El objeto JSON tiene la siguiente plantilla:
{
"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>
}
}
}
Todas las claves de nivel superior de la plantilla anterior son opcionales y tienen valores predeterminados (backgroundLogin, backgroundLogut son false de forma predeterminada y mvpdConfig es null, lo que significa que no se anula ninguna configuración de MVPD).
- Nota: si se especifican valores o tipos no válidos para los parámetros anteriores, se producirá un comportamiento no definido.
Esta es una configuración de ejemplo para el siguiente escenario: activación del inicio de sesión y cierre de sesión sin actualización, cambio de MVPD1 al inicio de sesión de redirección de página completo (no iFrame) y MVPD2 al inicio de sesión de iFrame con anchura=500 y altura=300:
{
"backgroundLogin": true,
"backgroundLogout": true,
"mvpdConfig":{
"MVPD1":{
"iFrameRequired": false
},
"MVPD2":{
"iFrameRequired": true,
"iFrameWidth": 500,
"iFrameHeight": 300
}
}
}
Llamadas de retorno activadas: setConfig()
getAuthorization(inResourceID, redirect_url) getauthorization(inresourceid,redirect_url)
Descripción: solicita autorización para el recurso especificado. Cada vez que un cliente intente acceder a un recurso autorizable, llame a esta función para obtener un token de autorización de corta duración del Habilitador de acceso. Los ID de recurso se acuerdan con la autorización de la MVPD.
Utiliza el token de autenticación en caché para el cliente actual. Si no se encuentra ese token, inicia primero el proceso de autenticación y, a continuación, continúa con la autorización.
Parámetros:
inResourceID
: ID del recurso para el cual el usuario solicita autorización.redirect_url
: proporcione opcionalmente una URL de redireccionamiento, de modo que el proceso de autorización de MVPD devuelva al usuario a esa página en lugar de a la página desde la cual se inició la autorización.
Se activaron devoluciones de llamadas: setToken() con éxito, tokenRequestFailed con error
getAuthentication(redirect_url) getauthentication(redirect_url
Descripción: solicita autenticación para el cliente actual. Normalmente se llama en respuesta a un clic en un botón de inicio de sesión. Busca un token de autenticación en caché para el cliente actual. Si no se encuentra ese token, inicia el proceso de autenticación. Esto invoca el cuadro de diálogo de selección de proveedor predeterminado o personalizado y, a continuación, utiliza el proveedor seleccionado para redirigir a la interfaz de inicio de sesión de la MVPD.
Si se realiza correctamente, crea y almacena un token de autenticación para el usuario. Si la autenticación falla, el proveedor devuelve un mensaje de error apropiado a la llamada de retorno setAuthenticationStatus().
Parámetros:
- redirect_url: Opcionalmente, proporcione una URL de redireccionamiento para que el proceso de autenticación de MVPD devuelva al usuario a esa página en lugar de a la página desde la que se inició la autenticación.
Se desencadenaron devoluciones de llamadas: setAuthenticationStatus(), displayProviderDialog(), sendTrackingData()
checkAuthN checkauthn
Descripción: comprueba el estado de autenticación actual del cliente actual. No asociado a ninguna interfaz de usuario.
Llamadas de retorno activadas: setAuthenticationStatus()
checkAuthorization(inResourceID) checkauthorization(inresourceid)
Descripción: La aplicación utiliza este método para comprobar el estado de autorización del cliente actual y del recurso dado. Se inicia comprobando primero el estado de autenticación. Si no se autentica, se activa la llamada de retorno tokenRequestFailed() y se cierra el método. Si el usuario está autenticado, también almacena en déclencheur el flujo de autorización. Ver detalles del método [getAuthorization()] (#getAuthZ.
Parámetros:
inResourceID
: ID del recurso para el cual el usuario solicita autorización.
Llamadas de retorno activadas:
setToken(), tokenRequestFailed(), sendTrackingData(), setAuthenticationStatus()
checkPreauthorizedResources(resources) checkPreauthorizedResources(resources)
Descripción: solicita el estado de autorización de "comprobación preliminar" para una lista de
recursos.
Parámetros:
- resources: el parámetro resources es una matriz de recursos cuya autorización se debe comprobar. Cada elemento de la lista debe ser una cadena que represente el ID de recurso. El id. de recurso está sujeto a las mismas limitaciones que el id. de recurso de la llamada
getAuthorization()
; es decir, se trata de un valor acordado entre el programador y la MVPD o un fragmento de RSS multimedia.
checkPreauthorizedResources(resources-cache=true) checkPreauthorizedResources(resources-cache=true)
Esta variante de API está disponible a partir de la versión 4.0 del SDK de JS
Parámetros:
-
resources: el parámetro resources es una matriz de recursos cuya autorización se debe comprobar. Cada elemento de la lista debe ser una cadena que represente el ID de recurso. El id. de recurso está sujeto a las mismas limitaciones que el id. de recurso de la llamada
getAuthorization()
; es decir, se trata de un valor acordado entre el programador y la MVPD o un fragmento de RSS multimedia. -
cache: Indica si se debe usar la caché interna cuando se comprueban recursos preautorizados. Este es un parámetro opcional, con el valor predeterminado true. Si es true, el comportamiento es idéntico al de la API anterior, lo que significa que las llamadas posteriores a esta función utilizarán una caché interna para resolver el recurso autorizado previamente. Si se pasa false para este parámetro, se deshabilitará la caché interna, lo que dará como resultado una llamada al servidor cada vez que se llame a la API checkPreauthorizedResources.
Llamadas de retorno activadas: preauthorizedResources()
getMetadata(Key) getMetadata
Descripción: recupera información expuesta como metadatos por la biblioteca del Habilitador de acceso.
Existen dos tipos de metadatos:
- Estático (TTL de token de autenticación, TTL de token de autorización e ID de dispositivo)
- Metadatos de usuario (Esto incluye información específica del usuario que se pasa desde la MVPD al dispositivo del usuario durante los flujos de autenticación o autorización)
Más información: Metadatos de usuario
Parámetros:
-
key: ID que especifica los metadatos solicitados:
-
Si la clave es
"TTL_AUTHN",
, se realiza la consulta para obtener el tiempo de caducidad del token de autenticación. -
Si la clave es
"TTL_AUTHZ"
y params es una matriz que contiene el ID de recurso como una cadena, se realiza la consulta para obtener la hora de caducidad del token de autorización asociado al recurso especificado. -
Si la clave es
"DEVICEID"
, se realiza la consulta para obtener el ID del dispositivo actual. Tenga en cuenta que esta función está desactivada de forma predeterminada y los programadores deben ponerse en contacto con el Adobe para obtener información sobre la habilitación y las tarifas. -
Si la clave procede de la siguiente lista de tipos de metadatos de usuario, se envía a la función de devolución de llamada
setMetadataStatus()
un objeto JSON que contiene los metadatos de usuario correspondientes: -
"zip"
- Código postal -
"encryptedZip"
- Código postal cifrado -
"householdID"
- Identificador del hogar. En caso de que una MVPD no admita subcuentas, será idéntico a userID. -
"maxRating"
- Clasificación parental máxima para el usuario -
"userID"
: el identificador de usuario. En el caso de que una MVPD admita subcuentas y el usuario no sea la cuenta principal, userID será diferente a householdID. -
"channelID"
: lista de canales que el usuario puede ver -
"is_hoh"
- Indicador que identifica si un usuario es cabeza de familia -
"encryptedZip"
- Código postal cifrado -
"typeID"
: indicador que identifica si la cuenta de usuario es la cuenta principal/secundaria -
"primaryOID"
- Identificador del hogar -
"postalCode"
- Similar al código postal -
"acctID"
- ID de cuenta -
"acctParentID"
- Identificador principal de la cuenta
Nota: Los metadatos de usuario reales disponibles para un programador dependen de lo que una MVPD ponga a disposición. Consulte Metadatos de usuario para ver la lista actual de metadatos de usuario disponibles.
-
Por ejemplo:
// 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 {
...
}
}
Llamadas de retorno activadas: setMetadataStatus()
setSelectedProvider(providerid) setSelectedProvider
Descripción: Llame a esta función cuando el usuario haya seleccionado una MVPD en la interfaz de usuario de selección de proveedores para enviar la selección de proveedores al Habilitador de acceso o llame a esta función con un parámetro nulo en caso de que el usuario descarte la interfaz de usuario de selección de proveedores sin seleccionar un proveedor.
Llamadas de retorno
desencadenó: setAuthenticationStatus(), sendTrackingData()
getSelectedProvider() getSelectedProvider
Descripción: Recupera los resultados de la selección del cliente en el cuadro de diálogo de selección de proveedor. Esto se puede utilizar en cualquier momento después de la comprobación de autenticación inicial.
Esta función es asincrónica y devuelve su resultado a la función de devolución de llamada selectedProvider()
.
- MVPD El MVPD seleccionado actualmente, o nulo si no se seleccionó ningún MVPD.
- AE_State: el resultado de la autenticación para el cliente actual es "Nuevo usuario", "Usuario no autenticado" o "Usuario autenticado"
Llamadas de retorno activadas: selectedProvider()
cierre de sesión logout
Descripción: cierra la sesión del cliente actual y borra toda la información de autenticación y autorización de ese usuario. Elimina todos los tokens authN y authZ del sistema del cliente.
Llamadas de retorno activadas: setAuthenticationStatus()
Definición de llamada calllback-definitions
Debe implementar estas llamadas de retorno para gestionar las respuestas a sus llamadas de solicitud asincrónicas:
rightLoaded() entitlementLoaded
Descripción: se activó cuando el Habilitador de acceso ha completado la inicialización y está listo para recibir solicitudes. Implemente esta llamada de retorno para saber cuándo puede iniciar la comunicación con la API del Habilitador de acceso.
setConfig(configXML) setconfig(configXML)
Descripción: Implemente esta devolución de llamada para recibir la información de configuración y la lista de MVPD.
Parámetros:
- configXML: objeto xml que contiene la configuración del REQUESTOR actual, incluida la lista de MVPD.
Activado por: setRequestor()
displayProviderDialog(providers) displayproviderdialog(providers)
Descripción: Implemente esta devolución de llamada para invocar su propia interfaz de usuario de selección de proveedor personalizada. El cuadro de diálogo debe utilizar el nombre para mostrar (y el logotipo opcional) para proporcionar las opciones del cliente. Cuando el cliente haya elegido y haya cerrado el cuadro de diálogo, envíe el ID asociado del proveedor elegido en la llamada a setSelectedProvider().
Parámetros:
- proveedores: una matriz de objetos que representan las MVPD solicitadas:
var mvpd = {
ID: "someprov",
displayName: "Some Provider",
logoURL: "http://www.someprov.com/images/logo.jpg"
}
Activado por: getAuthentication(), getAuthorization()
createIFrame(inWidth, inHeight) createIFrame(inWidth,inHeight)
Descripción: Implemente esta llamada de retorno si el usuario seleccionó una MVPD que requiera un iFrame en el que mostrar su interfaz de usuario de la página de inicio de sesión de autenticación.
Activado por: setSelectedProvider()
setAuthenticationStatus(isAuthenticated, errorCode) set-authn-status-isauthn-error
Descripción: Implemente esta devolución de llamada para recibir el estado de autenticación (1=autenticado o 0=no autenticado) y un mensaje de error descriptivo si se produce algún error al intentar determinar el estado de autenticación (cadena vacía al finalizar correctamente la comprobación).
Parámetros:
- isAuthenticated - Proporciona el estado de autenticación: 1 (autenticado) o 0 (no autenticado).
- errorCode: cualquier error que se produjo al determinar el estado de autenticación. Una cadena vacía si no hay ninguna.
Activado por: checkAuthentication(), getAuthentication(), checkAuthorization()
sendTrackingData(trackingEventType, trackingData) sendTrackingData(trackingEventType,trackingData)
Descripción: Implemente esta devolución de llamada para recibir datos de seguimiento cuando se produzcan eventos específicos. Puede utilizar esto, por ejemplo, para realizar un seguimiento de cuántos usuarios han iniciado sesión con las mismas credenciales. El seguimiento no se puede configurar actualmente. Con la autenticación de Adobe Pass 1.6, sendTrackingData()
también genera informes sobre el dispositivo, el cliente del habilitador de acceso y el tipo de sistema operativo. La llamada de retorno sendTrackingData()
sigue siendo compatible con versiones anteriores.
-
Valores posibles para el tipo de dispositivo:
- ordenador
- tableta
- mobile
- consola de juegos
- desconocido
-
Valores posibles para el tipo de cliente del Habilitador de acceso:
- html5
- ios
- androide
Pasa el tipo de evento y una matriz de información asociada. Los tipos de eventos son:
Activado por: checkAuthentication(), getAuthentication(), checkAuthorization(), getAuthorization()
setToken(inRequestedResourceID, inToken) setToken(inRequestedResourceID,inToken)
Descripción: Implemente esta llamada de retorno para recibir el token de medios de corta duración (inToken) y el identificador del recurso (inRequestedResourceID) para el que se realizó una solicitud de autorización o una solicitud de autorización de comprobación y que se completó correctamente.
Activado por: checkAuthorization(), getAuthorization()
tokenRequestFailed(inRequestedResourceID, inRequestErrorCode, inRequestDetailedErrorMessage) token-request-failed-error-msg
Descripción: Implemente esta llamada de retorno para que se señale cuando haya fallado una autorización o una solicitud de autorización de comprobación. Opcionalmente, un MVPD puede utilizarlo para proporcionar un mensaje personalizado que mostrará el programador.
Parámetros:
- inRequestedResourceID: cadena que proporciona el identificador de recurso que se utilizó en la solicitud de autorización.
- inRequestErrorCode: cadena que muestra el código de error de autenticación de Adobe Pass, indicando el motivo del error; los valores posibles son "Error de usuario no autenticado" y "Error de usuario no autorizado"; para obtener más detalles, vea "Códigos de error de devolución de llamada" a continuación.
- inRequestDetailedErrorMessage: una cadena descriptiva adicional adecuada para mostrar. Si esta cadena descriptiva no está disponible por algún motivo, la autenticación de Adobe Pass enviará una cadena vacía (""). Un MVPD puede utilizarla para transmitir mensajes de error personalizados o mensajes relacionados con las ventas. Por ejemplo, si a un suscriptor se le niega la autorización para un recurso, la MVPD podría responder con un
*inRequestDetailedErrorMessage*
como: "Actualmente no tiene acceso a este canal en su paquete. Si desea actualizar el paquete, haga clic *aquí*." Autenticación de Adobe Pass pasa el mensaje a través de esta devolución de llamada al sitio del programador. A continuación, el programador tiene la opción de mostrarlo u omitirlo. La autenticación de Adobe Pass también puede utilizar*inRequestDetailedErrorMessage*
para notificar al programador la condición que podría haber provocado un error. Por ejemplo, "Se produjo un error de red al comunicarse con el servicio de autorización del proveedor".
Activado por: checkAuthorization(), getAuthorization()
preauthorizedResources(authorizedResources) preauthorizedResources(authorizedResources)
Descripción: La llamada de retorno desencadenada por el Habilitador de acceso que entrega la lista de recursos autorizados devuelta después de una llamada a checkPreauthorizedResources()
.
Parámetros:
- authorizedResources: La lista de recursos autorizados.
Activado por: checkPreauthorizedResources()
setMetadataStatus(key, encryption, data) setMetadataStatus(key,encrypted,data)
Descripción: La llamada de retorno desencadenada por el Habilitador de acceso que entrega los metadatos solicitados mediante una llamada de getMetadata()
.
Más información: Metadatos de usuario
Parámetros:
- key (String): Clave de los metadatos para los que se realizó la solicitud.
- cifrado (booleano): Un indicador que indica si el "valor" está cifrado o no. Si es "true", "value" será en realidad una representación cifrada con web JSON del valor real.
- data (objeto JSON): un objeto JSON con la representación de los metadatos. Para las solicitudes simples ('
TTL_AUTHN
', 'TTL_AUTHZ
', 'DEVICEID
'), el resultado es una cadena (que representa el TTL de autenticación, el TTL de autorización o el ID de dispositivo). En el caso de una solicitud de metadatos de usuario, el resultado puede ser un objeto primitivo o JSON que represente la carga útil de metadatos. La estructura real de los objetos de metadatos de usuario de JSON es similar a la siguiente:
{
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"]
}
Por ejemplo:
// 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);
}
Activado por: getMetadata()
Volver al principio
selectedProvider(resultado) selectedProvider(result)
Descripción: Implemente esta devolución de llamada para recibir la MVPD seleccionada actualmente y el resultado de la autenticación del usuario actual envuelto en el parámetro result
. El parámetro result
es un objeto con las siguientes propiedades:
- MVPD El MVPD seleccionado actualmente, o nulo si no se seleccionó ningún MVPD.
- AE_State Resultado de la autenticación para el usuario actual, uno de "Nuevo usuario", "Usuario no autenticado" o "Usuario autenticado"
Activado por: getSelectedProvider()