Référence de l’API du SDK JavaScript javascript-sdk-api-reference
Référence d’API api-reference
Ces fonctions déclenchent des demandes d’interaction avec un MVPD. Tous les appels sont asynchrones ; vous devez implémenter des rappels pour gérer les réponses :
setRequestor (inRequestorID, endpoints, options) setrequestor(inRequestorID,endpoints,options)
Description : Identifie le site d’où proviennent les demandes. Vous devez effectuer cet appel avant tout autre appel API dans une session de communication.
Paramètres :
-
inRequestorID - Identifiant unique qui a été attribué à l’Adobe sur le site d’origine lors de l’enregistrement.
-
endpoints - Ce paramètre est facultatif. Il peut s’agir de l’une des valeurs suivantes :
- Tableau qui vous permet de spécifier des points de terminaison pour les services d’authentification et d’autorisation fournis par Adobe (différentes instances peuvent être utilisées à des fins de débogage). Si plusieurs URL sont fournies, la liste MVPD est composée des points de terminaison de tous les fournisseurs de services. Chaque MVPD est associé au fournisseur de services le plus rapide, c’est-à-dire le fournisseur qui a répondu en premier et qui prend en charge ce MVPD. Par défaut (si aucune valeur n’est spécifiée), le fournisseur de services Adobe est utilisé (http://sp.auth.adobe.com/).
Exemple :
setRequestor("IFC", ["http://sp.auth-dev.adobe.com/adobe-services"])
-
options - Objet JSON contenant la valeur de l’ID d’application, les paramètres sans actualisation de la valeur de l’identifiant visiteur (déconnexion de l’arrière-plan) et les paramètres MVPD (iFrame). Toutes les valeurs sont facultatives.
- S’il est spécifié, le visitorID Experience Cloud est reporté sur tous les appels réseau effectués par la bibliothèque. La valeur peut être utilisée ultérieurement pour les rapports d’analyse avancés.
- Si l’identifiant unique de l’application est spécifié -
applicationId- la valeur sera ajoutée à tous les appels suivants effectués par l’application dans le cadre de l’en-tête HTTP X-Device-Info. Cette valeur peut être récupérée ultérieurement à partir des rapports ESM à l’aide de la requête appropriée.
Remarque : Toutes les clés JSON sont sensibles à la casse.
Exemple :
setRequestor("IFC", {
"visitorID": "THE_ECID_VALUE",
"applicationId": "APP_ID_VALUE"
})
- Le programmeur peut remplacer les paramètres MVPD configurés dans l’authentification Adobe Pass, en spécifiant si un iFrame est requis ou non pour la connexion (clé iFrameRequired) et les dimensions iFrame (iFrameWidth et clés iFrameHeight). L’objet JSON comporte le modèle suivant :
{
"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>
}
}
}
Toutes les clés de niveau supérieur du modèle ci-dessus sont facultatives et possèdent des valeurs par défaut (backgroundLogin, backgroundLogut sont false par défaut et mvpdConfig est null, ce qui signifie qu’aucun paramètre MVPD n’est remplacé).
- Remarque : La spécification de valeurs/types non valides pour les paramètres ci-dessus entraînera un comportement indéfini.
Voici un exemple de configuration pour le scénario suivant : activation de la connexion et de la déconnexion sans actualisation, changement de MVPD1 en connexion pleine page-redirection (non-iFrame) et MVPD2 en connexion iFrame avec width=500 et height=300 :
{
"backgroundLogin": true,
"backgroundLogout": true,
"mvpdConfig":{
"MVPD1":{
"iFrameRequired": false
},
"MVPD2":{
"iFrameRequired": true,
"iFrameWidth": 500,
"iFrameHeight": 300
}
}
}
Rappels déclenchés : setConfig()
getAuthorization(inResourceID, redirect_url) getauthorization(inresourceid,redirect_url)
Description : Demande l’autorisation pour la ressource spécifiée. Chaque fois qu’un client tente d’accéder à une ressource autorisable, appelez cette fonction pour obtenir un jeton d’autorisation de courte durée à partir de l’activateur d’accès. Les ID de ressource sont acceptés par le MVPD qui accorde l’autorisation.
Utilise le jeton d’authentification mis en cache pour le client actuel. Si aucun jeton de ce type n’est trouvé, lance d’abord le processus d’authentification, puis continue avec autorisation.
Paramètres :
inResourceID- Identifiant de la ressource pour laquelle l’utilisateur demande l’autorisation.redirect_url- Vous pouvez éventuellement fournir une URL de redirection, de sorte que le processus d’autorisation du MVPD renvoie l’utilisateur sur cette page plutôt que sur la page à partir de laquelle l’autorisation a été lancée.
Rappels déclenchés : setToken() en cas de succès, tokenRequestFailed en cas d’échec
getAuthentication(redirect_url) getauthentication(redirect_url
Description : Demande l’authentification pour le client actuel. Généralement appelé en réponse à un clic sur un bouton Connexion . Vérifie un jeton d’authentification mis en cache pour le client actuel. Si aucun jeton de ce type n’est trouvé, lance le processus d’authentification. Cela appelle la boîte de dialogue de sélection de fournisseur par défaut ou personnalisée, puis utilise le fournisseur sélectionné pour rediriger vers l’interface de connexion du MVPD.
En cas de succès, crée et stocke un jeton d’authentification pour l’utilisateur. Si l'authentification échoue, le fournisseur renvoie un message d'erreur approprié à votre rappel setAuthenticationStatus().
Paramètres :
- redirect_url : éventuellement fournir une URL de redirection, de sorte que le processus d’authentification du MVPD renvoie l’utilisateur vers cette page plutôt que la page à partir de laquelle l’authentification a été lancée.
Rappels déclenchés : setAuthenticationStatus(), displayProviderDialog(), sendTrackingData()
checkAuthN checkauthn
Description : Vérifie l’état d’authentification actuel du client actuel. Non associé à une interface utilisateur.
Rappels déclenchés : setAuthentcationStatus()
checkAuthorization(inResourceID) checkauthorization(inresourceid)
Description : Cette méthode est utilisée par l’application pour vérifier l’état d’autorisation du client actuel et de la ressource donnée. Il commence par vérifier l’état d’authentification. Si elle n’est pas authentifiée, le rappel tokenRequestFailed() est déclenché et la méthode se ferme. Si l’utilisateur est authentifié, il déclenche également le flux d’autorisation. Voir les détails sur la méthode getAuthorization().
Paramètres :
inResourceID- Identifiant de la ressource pour laquelle l’utilisateur demande l’autorisation.
Rappels déclenchés :
setToken(), tokenRequestFailed(), sendTrackingData(), setAuthenticationStatus()
checkPreauthorizedResources(resources) checkPreauthorizedResources(resources)
Description : Demande l’état d’autorisation "preflight" pour une liste
ressources.
Paramètres :
- resources : le paramètre resources est un tableau de ressources pour lequel l’autorisation doit être vérifiée. Chaque élément de la liste doit être une chaîne représentant l’ID de ressource. L’ID de ressource est soumis aux mêmes limites que l’ID de ressource dans l’appel
getAuthorization(), c’est-à-dire qu’il s’agit d’une valeur convenue établie entre le programmeur et le MVPD, ou un fragment RSS multimédia.
checkPreauthorizedResources(resources-cache=true) checkPreauthorizedResources(resources-cache=true)
Cette variante d’API est disponible à partir de la version 4.0 du SDK JS
Paramètres :
-
resources : le paramètre resources est un tableau de ressources pour lequel l’autorisation doit être vérifiée. Chaque élément de la liste doit être une chaîne représentant l’ID de ressource. L’ID de ressource est soumis aux mêmes limites que l’ID de ressource dans l’appel
getAuthorization(), c’est-à-dire qu’il s’agit d’une valeur convenue établie entre le programmeur et le MVPD, ou un fragment RSS multimédia. -
cache : si vous souhaitez utiliser le cache interne lors de la vérification des ressources préautorisées. Il s’agit d’un paramètre facultatif, défini par défaut sur true. Si la valeur est true, le comportement est identique à l’API ci-dessus, ce qui signifie que les appels suivants à cette fonction utiliseront un cache interne pour résoudre la ressource préautorisée. La transmission de false pour ce paramètre désactive le cache interne, ce qui entraîne un appel au serveur chaque fois que l’API checkPreauthorizedResources est appelée.
Rappels déclenchés : preauthorizedResources()
getMetadata(Key) getMetadata
Description : Récupère des informations exposées sous forme de métadonnées par la bibliothèque Access Enabler.
Il existe deux types de métadonnées :
- Static (jeton d’authentification TTL, jeton d’autorisation TTL et ID d’appareil)
- Métadonnées utilisateur (Cela inclut les informations spécifiques à l’utilisateur transmises du MVPD à l’appareil de l’utilisateur pendant les flux d’authentification et/ou d’autorisation)
Plus d’informations : Métadonnées utilisateur
Paramètres :
-
key : identifiant qui spécifie les métadonnées demandées :
-
Si la clé est
"TTL_AUTHN",, la requête est effectuée pour obtenir le délai d’expiration du jeton d’authentification. -
Si la clé est
"TTL_AUTHZ"et que params est un tableau contenant l’ID de ressource sous la forme d’une chaîne, la requête est effectuée pour obtenir le délai d’expiration du jeton d’autorisation associé à la ressource spécifiée. -
Si la clé est
"DEVICEID", la requête est effectuée pour obtenir l’identifiant de l’appareil actuel. Notez que cette fonctionnalité est désactivée par défaut et que les programmeurs doivent contacter Adobe pour plus d’informations sur l’activation et les frais. -
Si la clé figure dans la liste suivante des types de métadonnées utilisateur, un objet JSON contenant les métadonnées utilisateur correspondantes est envoyé à la fonction de rappel
setMetadataStatus(): -
"zip"- Code postal -
"encryptedZip"- Code postal chiffré -
"householdID"- Identifiant du foyer. Dans le cas où un MVPD ne prend pas en charge les sous-comptes, cela est identique à userID. -
"maxRating"- Note parentale maximale pour l’utilisateur -
"userID"- Identifiant de l’utilisateur. Dans le cas où un MVPD prend en charge des sous-comptes et que l’utilisateur n’est pas le compte principal, userID est différent de householdID. -
"channelID"- La liste des canaux que l’utilisateur est autorisé à afficher -
"is_hoh"- Indicateur qui identifie si un utilisateur est chef de famille -
"encryptedZip"- Code postal chiffré -
"typeID"- Indicateur qui identifie si le compte utilisateur est un compte principal/secondaire -
"primaryOID"- Identifiant du foyer -
"postalCode"- Similaire au code postal -
"acctID"- ID de compte -
"acctParentID"- ID parent du compte
Remarque : les métadonnées utilisateur réelles disponibles pour un programmeur dépendent de ce qu’un MVPD rend disponible. Voir Métadonnées utilisateur pour obtenir la liste actuelle des métadonnées utilisateur disponibles.
-
Par exemple :
// 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 {
...
}
}
Rappels déclenchés : setMetadataStatus()
setSelectedProvider(providerid) setSelectedProvider
Description : Appelez cette fonction lorsque l’utilisateur a sélectionné un MVPD depuis votre interface utilisateur de sélection du fournisseur afin d’envoyer la sélection du fournisseur à l’activateur d’accès ou appelez cette fonction avec un paramètre null si l’utilisateur a ignoré votre interface utilisateur de sélection du fournisseur sans sélectionner de fournisseur.
Rappels
déclenchée : setAuthentcationStatus(), sendTrackingData()
getSelectedProvider() getSelectedProvider
Description : Récupère les résultats de la sélection du client dans la boîte de dialogue de sélection du fournisseur. Vous pouvez l’utiliser à tout moment après la vérification initiale de l’authentification.
Cette fonction est asynchrone et renvoie son résultat à votre fonction de rappel selectedProvider().
- MVPD MVPD actuellement sélectionné ou valeur nulle si aucun MVPD n’a été sélectionné.
- AE_State Le résultat de l’authentification pour le client actuel est "Nouvel utilisateur", "Utilisateur non authentifié" ou "Utilisateur authentifié".
Rappels déclenchés : selectedProvider()
déconnexion logout
Description : Déconnecte le client actuel, en effaçant toutes les informations d’authentification et d’autorisation pour cet utilisateur. Supprime tous les jetons authN et authZ du système du client.
Rappels déclenchés : setAuthentcationStatus()
Définition de rappel calllback-definitions
Vous devez mettre en oeuvre ces rappels pour gérer les réponses à vos appels de requête asynchrones :
rightsLoaded() entitlementLoaded
Description : déclenché lorsque l’activation d’accès a terminé l’initialisation et est prêt à recevoir des requêtes. Mettez en oeuvre ce rappel pour savoir quand commencer la communication avec l’API Access Enabler.
setConfig(configXML) setconfig(configXML)
Description : Mettez en oeuvre ce rappel pour recevoir les informations de configuration et la liste MVPD.
Paramètres :
- configXML : objet xml contenant la configuration de la REQUESTOR actuelle, y compris la liste MVPD.
Déclenché par : setRequestor()
displayProviderDialog(provider) displayproviderdialog(providers)
Description : Mettez en oeuvre ce rappel pour appeler votre propre interface utilisateur personnalisée de sélection de fournisseur. Votre boîte de dialogue doit utiliser le nom d’affichage (et le logo facultatif) pour fournir les choix du client. Lorsque le client a fait un choix et a ignoré la boîte de dialogue, envoyez l’identifiant associé du fournisseur choisi dans l’appel à setSelectedProvider().
Paramètres :
- provider - Un tableau d’objets représentant les MVPD demandés :
var mvpd = {
ID: "someprov",
displayName: "Some Provider",
logoURL: "http://www.someprov.com/images/logo.jpg"
}
Déclenchée par : getAuthentication(), getAuthorization()
createIFrame(inWidth, inHeight) createIFrame(inWidth,inHeight)
Description : Mettez en oeuvre ce rappel si l’utilisateur a sélectionné un MVPD qui nécessite un iFrame dans lequel afficher l’interface utilisateur de sa page de connexion d’authentification.
Déclenchée par : setSelectedProvider()
setAuthenticationStatus(isAuthenticated, errorCode) set-authn-status-isauthn-error
Description : Mettez en oeuvre ce rappel pour recevoir l’état d’authentification (1=authentifié ou 0=non authentifié) et un message d’erreur descriptif si une erreur s’est produite lors de la tentative de détermination de l’état d’authentification (chaîne vide une fois la vérification terminée).
Paramètres :
- isAuthenticated - Fournit l’état d’authentification : 1 (authentifié) ou 0 (non authentifié).
- errorCode - Toute erreur survenue lors de la détermination de l’état d’authentification. Chaîne vide, le cas échéant.
Déclenché par : checkAuthentication(), getAuthentication(), checkAuthorization()
sendTrackingData(trackingEventType, trackingData) sendTrackingData(trackingEventType,trackingData)
Description : Mettez en oeuvre ce rappel pour recevoir des données de suivi lorsque des événements spécifiques se produisent. Vous pouvez l’utiliser, par exemple, pour effectuer le suivi du nombre d’utilisateurs qui se sont connectés avec les mêmes informations d’identification. Le suivi n’est actuellement pas configurable. Avec l’authentification Adobe Pass 1.6, sendTrackingData() consigne également des informations sur l’appareil, le client Access Enabler et le type de système d’exploitation. Le rappel sendTrackingData() reste rétrocompatible.
-
Valeurs possibles pour le type d’appareil :
- machine
- tablette
- mobile
- gameconsole
- unknown
-
Valeurs possibles pour le type de client Access Enabler :
- html5
- ios
- android
Transmet le type d’événement et un tableau d’informations associées. Les types d’événement sont les suivants :
Déclenché par : checkAuthentication(), getAuthentication(), checkAuthorization(), getAuthorization()
setToken(inRequestedResourceID, inToken) setToken(inRequestedResourceID,inToken)
Description : Mettez en oeuvre ce rappel pour recevoir le jeton multimédia de courte durée (inToken) et l’identifiant de la ressource (inRequestedResourceID) pour laquelle une demande d’autorisation ou de vérification d’autorisation a été effectuée et a abouti.
Déclenchée par : checkAuthorization(), getAuthorization()
tokenRequestFailed(inRequestedResourceID, inRequestErrorCode, inRequestDetailsErrorMessage) token-request-failed-error-msg
Description : Mettez en oeuvre ce rappel pour qu’il soit signalé lorsqu’une demande d’autorisation ou de vérification d’autorisation a échoué. Peut éventuellement être utilisé par un MVPD pour fournir un message personnalisé à afficher par le programmeur.
Paramètres :
- inRequestedResourceID - Chaîne fournissant l’ID de ressource utilisé dans la demande d’autorisation.
- inRequestErrorCode - Chaîne qui affiche le code d’erreur d’authentification Adobe Pass, indiquant la raison de l’échec ; les valeurs possibles sont "Erreur de non-authentification de l’utilisateur" et "Erreur de non-autorisation de l’utilisateur" ; pour plus d’informations, voir "Codes d’erreur de rappel" ci-dessous.
- inRequestDetailsErrorMessage - Chaîne descriptive supplémentaire adaptée à l’affichage. Si cette chaîne descriptive n’est disponible pour aucune raison, l’authentification Adobe Pass envoie une chaîne vide (""). Il peut être utilisé par un MVPD pour transmettre des messages d’erreur personnalisés ou des messages liés aux ventes. Par exemple, si un abonné se voit refuser l’autorisation d’une ressource, le MVPD peut répondre avec un
*inRequestDetailedErrorMessage*tel que : "Vous n’avez actuellement pas accès à ce canal dans votre package. Si vous souhaitez mettre à niveau votre package, cliquez sur *ici*." Le message est transmis par l’authentification Adobe Pass via ce rappel au site du programmeur. Le programmeur a alors la possibilité de l'afficher ou de l'ignorer. L’authentification Adobe Pass peut également utiliser*inRequestDetailedErrorMessage*pour informer le programmeur de la condition qui a pu entraîner une erreur. Par exemple, "Une erreur réseau s'est produite lors de la communication avec le service d'autorisation du fournisseur".
Déclenchée par : checkAuthorization(), getAuthorization()
preauthorizedResources(authorizedResources) preauthorizedResources(authorizedResources)
Description : Rappel déclenché par l’activateur d’accès qui fournit la liste des ressources autorisées renvoyée après un appel à checkPreauthorizedResources().
Paramètres :
- authorizedResources : liste des ressources autorisées.
Déclenchée par : checkPreauthorizedResources()
setMetadataStatus(key, encrypted, data) setMetadataStatus(key,encrypted,data)
Description : Rappel déclenché par l’activateur d’accès qui diffuse les métadonnées demandées via un appel getMetadata().
Plus d’informations : Métadonnées utilisateur
Paramètres :
- key (String) : clé des métadonnées pour lesquelles la demande a été effectuée.
- encrypted (Boolean) : indicateur signifiant si la "valeur" est chiffrée ou non. Si la valeur est "true", alors "value" sera en fait une représentation JSON Web Encrypted de la valeur réelle.
- data (objet JSON) : un objet JSON avec la représentation des métadonnées. Pour les requêtes simples ('
TTL_AUTHN', 'TTL_AUTHZ', 'DEVICEID'), le résultat est une chaîne (représentant le TTL d’authentification, le TTL d’autorisation ou l’ID de périphérique). Dans le cas d’une requête de métadonnées utilisateur, le résultat peut être un objet JSON ou primitif représentant la charge utile de métadonnées. La structure réelle des objets de métadonnées utilisateur JSON est similaire à celle-ci :
{
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"]
}
Par exemple :
// 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);
}
Déclenché par : getMetadata()
Haut de page
selectedProvider(result) selectedProvider(result)
Description : Mettez en oeuvre ce rappel pour recevoir le MVPD actuellement sélectionné et le résultat de l’authentification de l’utilisateur actuel encapsulé dans le paramètre result. Le paramètre result est un objet avec les propriétés suivantes :
- MVPD MVPD actuellement sélectionné ou valeur nulle si aucun MVPD n’a été sélectionné.
- AEM_State Résultat de l’authentification pour l’utilisateur actuel, un de "Nouvel utilisateur", "Utilisateur non authentifié" ou "Utilisateur authentifié"
Déclenché par : getSelectedProvider()