Riferimento API di JavaScript SDK javascript-sdk-api-reference
Riferimento API api-reference
Queste funzioni avviano richieste di interazione con un MVPD. Tutte le chiamate sono asincrone. È necessario implementare callback per gestire le risposte:
setRequestor (inRequestorID, endpoint, opzioni) setrequestor(inRequestorID,endpoints,options)
Descrizione: identifica il sito da cui provengono le richieste. Devi effettuare questa chiamata prima di qualsiasi altra chiamata API in una sessione di comunicazione.
Parametri:
-
inRequestorID - Identificatore univoco assegnato dall'Adobe al sito di origine durante la registrazione.
-
endpoint - Questo parametro è facoltativo. Può corrispondere a uno dei seguenti valori:
- Array che consente di specificare gli endpoint per i servizi di autenticazione e autorizzazione forniti da Adobe (a scopo di debug possono essere utilizzate istanze diverse). Nel caso in cui vengano forniti più URL, l’elenco MVPD è composto dagli endpoint di tutti i fornitori di servizi. Ogni MVPD è associato al provider di servizi più veloce, ovvero il provider che ha risposto per primo e che supporta tale MVPD. Per impostazione predefinita (se non viene specificato alcun valore), viene utilizzato il provider di servizi Adobe (http://sp.auth.adobe.com/).
Esempio:
setRequestor("IFC", ["http://sp.auth-dev.adobe.com/adobe-services"])
-
opzioni - Oggetto JSON contenente il valore ID applicazione, le impostazioni senza aggiornamento del valore ID visitatore (disconnessione in background) e le impostazioni MVPD (iFrame). Tutti i valori sono facoltativi.
- Se specificato, l’ID visitatore Experience Cloud viene riportato su tutte le chiamate di rete eseguite dalla libreria. Il valore può essere successivamente utilizzato per i rapporti di analisi avanzati.
- Se l'identificatore univoco dell'applicazione è specificato -
applicationId- il valore verrà aggiunto a tutte le chiamate successive effettuate dall'applicazione come parte dell'intestazione HTTP X-Device-Info. Questo valore può essere recuperato in seguito dai report ESM utilizzando la query corretta.
Nota: tutte le chiavi JSON fanno distinzione tra maiuscole e minuscole.
Esempio:
setRequestor("IFC", {
"visitorID": "THE_ECID_VALUE",
"applicationId": "APP_ID_VALUE"
})
- Il programmatore può ignorare le impostazioni MVPD configurate nell'autenticazione di Adobe Pass, specificando se un iFrame è necessario o meno per l'accesso (chiave iFrameRequired) e le dimensioni iFrame (chiavi iFrameWidth e iFrameHeight). L’oggetto JSON presenta il seguente modello:
{
"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>
}
}
}
Tutte le chiavi di primo livello nel modello precedente sono facoltative e hanno valori predefiniti (backgroundLogin, backgroundLogut sono false per impostazione predefinita e mvpdConfig è null, il che significa che nessuna impostazione MVPD viene ignorata).
- Nota: specificando valori o tipi non validi per i parametri di cui sopra si verificherà un comportamento non definito.
Di seguito è riportata una configurazione di esempio per lo scenario seguente: attivazione dell’accesso senza aggiornamento e della disconnessione, modifica di MVPD1 con accesso con reindirizzamento a pagina intera (non iFrame) e accesso di MVPD2 con iFrame con larghezza=500 e altezza=300:
{
"backgroundLogin": true,
"backgroundLogout": true,
"mvpdConfig":{
"MVPD1":{
"iFrameRequired": false
},
"MVPD2":{
"iFrameRequired": true,
"iFrameWidth": 500,
"iFrameHeight": 300
}
}
}
Callback attivati: setConfig()
getAuthorization(inResourceID, redirect_url) getauthorization(inresourceid,redirect_url)
Descrizione: richiede l'autorizzazione per la risorsa specificata. Ogni volta che un cliente tenta di accedere a una risorsa autorizzabile, chiama questa funzione per ottenere un token di autorizzazione di breve durata da Access Enabler. Gli ID risorsa sono concordati con l'MVPD che fornisce l'autorizzazione.
Utilizza il token di autenticazione nella cache per il cliente corrente. Se non viene trovato alcun token di questo tipo, avvia prima il processo di autenticazione, quindi continua con l’autorizzazione.
Parametri:
inResourceID- ID della risorsa per la quale l'utente richiede l'autorizzazione.redirect_url- Fornire facoltativamente un URL di reindirizzamento, in modo che il processo di autorizzazione dell'MVPD restituisca l'utente a quella pagina anziché alla pagina da cui è stata avviata l'autorizzazione.
Callback attivati: setToken() al completamento, tokenRequestFailed al fallimento
getAuthentication(redirect_url) getauthentication(redirect_url
Descrizione: richiede l'autenticazione per il cliente corrente. Generalmente chiamato in risposta a un clic su un pulsante di accesso. Verifica la presenza di un token di autenticazione memorizzato nella cache per il cliente corrente. Se tale token non viene trovato, avvia il processo di autenticazione. Viene visualizzata la finestra di dialogo di selezione del provider predefinita o personalizzata, quindi viene utilizzato il provider selezionato per reindirizzare all'interfaccia di accesso di MVPD.
In caso di esito positivo, crea e memorizza un token di autenticazione per l’utente. Se l'autenticazione non riesce, il provider restituisce un messaggio di errore appropriato al callback setAuthenticationStatus().
Parametri:
- redirect_url: facoltativamente, fornisci un URL di reindirizzamento, in modo che il processo di autenticazione di MVPD restituisca l’utente a quella pagina invece che alla pagina da cui è stata avviata l’autenticazione.
Callback attivati: setAuthenticationStatus(), displayProviderDialog(), sendTrackingData()
checkAuthN checkauthn
Descrizione: verifica lo stato di autenticazione corrente per il cliente corrente. Non associato ad alcuna interfaccia utente.
Callback attivati: setAuthenticationStatus()
checkAuthorization(inResourceID) checkauthorization(inresourceid)
Descrizione: Questo metodo viene utilizzato dall'applicazione per controllare lo stato di autorizzazione per il cliente corrente e la risorsa specificata. Viene innanzitutto verificato lo stato di autenticazione. Se non viene autenticato, il callback tokenRequestFailed() viene attivato e il metodo viene chiuso. Se l’utente è autenticato, attiva anche il flusso di autorizzazione. Vedi i dettagli sul metodo [getAuthorization()] (#getAuthZ.
Parametri:
inResourceID- ID della risorsa per la quale l'utente richiede l'autorizzazione.
Callback attivati:
setToken(), tokenRequestFailed(), sendTrackingData(), setAuthenticationStatus()
checkPreauthorizedResources(resources) checkPreauthorizedResources(resources)
Descrizione: richiede lo stato di autorizzazione "verifica preliminare" per un elenco di
risorse.
Parametri:
- resources: il parametro resources è una matrice di risorse per le quali deve essere controllata l'autorizzazione. Ogni elemento dell’elenco deve essere una stringa che rappresenta l’ID della risorsa. L'ID risorsa è soggetto alle stesse limitazioni dell'ID risorsa nella chiamata
getAuthorization(), ovvero è un valore concordato tra il Programmatore e l'MVPD, o un frammento RSS del supporto.
checkPreauthorizedResources(resources-cache=true) checkPreauthorizedResources(resources-cache=true)
Questa variante API è disponibile a partire dalla versione 4.0 dell’SDK JS
Parametri:
-
resources: il parametro resources è una matrice di risorse per le quali deve essere controllata l'autorizzazione. Ogni elemento dell’elenco deve essere una stringa che rappresenta l’ID della risorsa. L'ID risorsa è soggetto alle stesse limitazioni dell'ID risorsa nella chiamata
getAuthorization(), ovvero è un valore concordato tra il Programmatore e l'MVPD, o un frammento RSS del supporto. -
cache: per utilizzare la cache interna durante la verifica della presenza di risorse preautorizzate. Parametro facoltativo. Impostazione predefinita: true. Se true, il comportamento è identico a quello dell’API precedente, il che significa che le chiamate successive a questa funzione utilizzeranno una cache interna per risolvere le risorse preautorizzate. Se si passa false per questo parametro, la cache interna verrà disabilitata e verrà generata una chiamata al server ogni volta che viene chiamata l'API checkPreauthorizedResources.
Callback attivati: preauthorizedResources()
getMetadata(Key) getMetadata
Descrizione: recupera le informazioni esposte come metadati dalla libreria di Access Enabler.
Esistono due tipi di metadati:
- Statico (TTL token di autenticazione, TTL token di autorizzazione e ID dispositivo)
- Metadati utente (include informazioni specifiche dell'utente passate dal MVPD al dispositivo dell'utente durante i flussi di autenticazione e/o autorizzazione)
Ulteriori informazioni: Metadati utente
Parametri:
-
chiave: un ID che specifica i metadati richiesti:
-
Se la chiave è
"TTL_AUTHN",, viene eseguita la query per ottenere l'ora di scadenza del token di autenticazione. -
Se la chiave è
"TTL_AUTHZ"e i parametri sono una matrice contenente l'ID risorsa come stringa, la query viene eseguita per ottenere la scadenza del token di autorizzazione associato alla risorsa specificata. -
Se la chiave è
"DEVICEID", viene eseguita la query per ottenere l'ID dispositivo corrente. Tieni presente che questa funzione è disabilitata per impostazione predefinita e i programmatori devono contattare l’Adobe per informazioni sull’abilitazione e sulle tariffe. -
Se key è incluso nel seguente elenco di tipi di metadati utente, un oggetto JSON contenente i metadati utente corrispondenti viene inviato alla funzione di callback
setMetadataStatus(): -
"zip"- Codice postale -
"encryptedZip"- Codice postale crittografato -
"householdID"- Identificatore famiglia. Nel caso in cui un MVPD non supporti account secondari, questo sarà identico a userID. -
"maxRating"- Valutazione genitori massima per l'utente -
"userID"- Identificatore utente. Nel caso in cui un MVPD supporti account secondari e l'utente non sia l'account principale, userID sarà diverso da familyID. -
"channelID"- Elenco dei canali che l'utente può visualizzare -
"is_hoh"- Flag che identifica se un utente è a capo del nucleo familiare -
"encryptedZip"- Codice postale crittografato -
"typeID"- Flag che identifica se l'account utente è primario/secondario -
"primaryOID"- Identificatore famiglia -
"postalCode"- Simile al CAP -
"acctID"- ID account -
"acctParentID"- ID padre account
Nota: i metadati utente effettivi disponibili per un programmatore dipendono da ciò che un MVPD rende disponibile. Per l'elenco corrente dei metadati utente disponibili, vedere Metadati utente.
-
Ad esempio:
// 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 {
...
}
}
Callback attivati: setMetadataStatus()
setSelectedProvider(providerid) setSelectedProvider
Descrizione: Chiama questa funzione quando l'utente ha selezionato un MVPD dall'interfaccia utente di selezione del provider per inviare la selezione del provider all'Access Enabler o chiama questa funzione con un parametro null nel caso in cui l'utente abbia rifiutato l'interfaccia utente di selezione del provider senza selezionare un provider.
Callback
attivato: setAuthenticationStatus(), sendTrackingData()
getSelectedProvider() getSelectedProvider
Descrizione: recupera i risultati della selezione del cliente nella finestra di dialogo di selezione del provider. Può essere utilizzato in qualsiasi momento dopo il controllo di autenticazione iniziale.
Questa funzione è asincrona e restituisce il risultato alla funzione di callback selectedProvider().
- MVPD Il MVPD attualmente selezionato o null se non è stato selezionato alcun MVPD.
- AE_State Il risultato dell'autenticazione per il cliente corrente è "Nuovo utente", "Utente non autenticato" o "Utente autenticato"
Callback attivati: selectedProvider()
logout logout
Descrizione: Disconnette il cliente corrente, cancellando tutte le informazioni di autenticazione e autorizzazione per tale utente. Elimina tutti i token authN e authZ dal sistema del cliente.
Callback attivati: setAuthenticationStatus()
Definizione callback calllback-definitions
Devi implementare questi callback per gestire le risposte alle chiamate di richiesta asincrone:
entitlementLoaded() entitlementLoaded
Descrizione: attivato quando l'attivatore di accesso ha completato l'inizializzazione ed è pronto per ricevere le richieste. Implementa questo callback per sapere quando avviare la comunicazione con l’API di Access Enabler.
setConfig(configXML) setconfig(configXML)
Descrizione: implementare questo callback per ricevere le informazioni di configurazione e l'elenco MVPD.
Parametri:
- configXML: oggetto xml contenente la configurazione per il REQUESTOR corrente, incluso l'elenco MVPD.
Attivato da: setRequestor()
displayProviderDialog(providers) displayproviderdialog(providers)
Descrizione: implementa questo callback per richiamare l'interfaccia utente personalizzata per la selezione del provider. La finestra di dialogo deve utilizzare il nome visualizzato (e il logo opzionale) per fornire le scelte del cliente. Quando il cliente ha effettuato una scelta e ha chiuso la finestra di dialogo, invia l'ID associato per il provider scelto nella chiamata a setSelectedProvider().
Parametri:
- provider - Matrice di oggetti che rappresenta gli MVPD richiesti:
var mvpd = {
ID: "someprov",
displayName: "Some Provider",
logoURL: "http://www.someprov.com/images/logo.jpg"
}
Attivato da: getAuthentication(), getAuthorization()
createIFrame(inWidth, inHeight) createIFrame(inWidth,inHeight)
Descrizione: implementa questo callback se l'utente ha selezionato un MVPD che richiede un iFrame in cui visualizzare la relativa interfaccia utente della pagina di accesso per l'autenticazione.
Attivato da: setSelectedProvider()
setAuthenticationStatus(isAuthenticated, errorCode) set-authn-status-isauthn-error
Descrizione: implementare questo callback per ricevere lo stato di autenticazione (1=autenticato o 0=non autenticato) e un messaggio di errore descrittivo in caso di errore durante il tentativo di determinare lo stato di autenticazione (stringa vuota al completamento del controllo).
Parametri:
- isAuthenticated - Fornisce lo stato di autenticazione: 1 (autenticato) o 0 (non autenticato).
- errorCode - Qualsiasi errore che si è verificato durante la determinazione dello stato di autenticazione. Stringa vuota se non presente.
Attivato da: checkAuthentication(), getAuthentication(), checkAuthorization()
sendTrackingData(trackingEventType, trackingData) sendTrackingData(trackingEventType,trackingData)
Descrizione: implementa questo callback per ricevere i dati di tracciamento quando si verificano eventi specifici. Puoi utilizzarlo, ad esempio, per tenere traccia del numero di utenti che hanno effettuato l’accesso con le stesse credenziali. Il tracciamento non è attualmente configurabile. Con Adobe Pass Authentication 1.6, sendTrackingData() segnala inoltre informazioni sul dispositivo, sul client Access Enabler e sul tipo di sistema operativo. Il callback sendTrackingData() rimane compatibile con le versioni precedenti.
-
Valori possibili per il tipo di dispositivo:
- computer
- tablet
- mobile
- gameconsole
- sconosciuto
-
Valori possibili per il tipo di client Access Enabler:
- html5
- ios
- androide
Passa il tipo di evento e una matrice di informazioni associate. I tipi di evento sono:
Attivato da: checkAuthentication(), getAuthentication(), checkAuthorization(), getAuthorization()
setToken(inRequestedResourceID, inToken) setToken(inRequestedResourceID,inToken)
Descrizione: implementare questo callback per ricevere il token multimediale di breve durata (inToken) e l'ID della risorsa (inRequestedResourceID) per cui è stata effettuata e completata una richiesta di autorizzazione o di autorizzazione di controllo.
Attivato da: checkAuthorization(), getAuthorization()
tokenRequestFailed(inRequestedResourceID, inRequestErrorCode, inRequestDetailedErrorMessage) token-request-failed-error-msg
Descrizione: implementare il callback da segnalare quando una richiesta di autorizzazione o di controllo-autorizzazione non è riuscita. Facoltativamente può essere utilizzato da un MVPD per fornire un messaggio personalizzato che deve essere visualizzato dal programmatore.
Parametri:
- inRequestedResourceID - Stringa che fornisce l'ID risorsa utilizzato nella richiesta di autorizzazione.
- inRequestErrorCode - Stringa che visualizza il codice di errore di autenticazione di Adobe Pass, che indica il motivo dell'errore. I valori possibili sono "Errore utente non autenticato" e "Errore utente non autorizzato". Per ulteriori dettagli, vedere "Codici di errore di callback" di seguito.
- inRequestDetailedErrorMessage - Stringa descrittiva aggiuntiva adatta alla visualizzazione. Se questa stringa descrittiva non è disponibile per alcun motivo, Adobe Pass Authentication invia una stringa vuota ("). Può essere utilizzato da un MVPD per trasmettere messaggi di errore personalizzati o messaggi relativi alle vendite. Ad esempio, se a un sottoscrittore viene negata l'autorizzazione per una risorsa, MVPD potrebbe rispondere con un
*inRequestDetailedErrorMessage*come: "Attualmente non si dispone dell'accesso a questo canale nel pacchetto. Se desideri aggiornare il pacchetto, fai clic su *qui*." Il messaggio viene passato dall'autenticazione di Adobe Pass tramite questo callback al sito del programmatore. Il programmatore ha quindi la possibilità di visualizzarlo o ignorarlo. L'autenticazione di Adobe Pass può inoltre utilizzare*inRequestDetailedErrorMessage*per notificare al programmatore la condizione che potrebbe aver causato un errore. Ad esempio, "Errore di rete durante la comunicazione con il servizio di autorizzazione del provider".
Attivato da: checkAuthorization(), getAuthorization()
preauthorizedResources(authorizedResources) preauthorizedResources(authorizedResources)
Descrizione: richiamata attivata da Access Enabler che distribuisce l'elenco delle risorse autorizzate restituito dopo una chiamata a checkPreauthorizedResources().
Parametri:
- authorizedResources: elenco delle risorse autorizzate.
Attivato da: checkPreauthorizedResources()
setMetadataStatus(chiave, crittografata, dati) setMetadataStatus(key,encrypted,data)
Descrizione: callback attivato dall'Access Enabler che distribuisce i metadati richiesti tramite una chiamata getMetadata().
Ulteriori informazioni: Metadati utente
Parametri:
- chiave (stringa): chiave dei metadati per cui è stata effettuata la richiesta.
- crittografato (booleano): flag che indica se il "valore" è crittografato o meno. Se questo è "true", "value" sarà in realtà una rappresentazione JSON Web Encrypted del valore effettivo.
- dati (oggetto JSON): un oggetto JSON con la rappresentazione dei metadati.Per le richieste semplici ('
TTL_AUTHN', 'TTL_AUTHZ', 'DEVICEID'), il risultato è un valore String (che rappresenta il TTL di autenticazione, il TTL di autorizzazione o l'ID dispositivo). Nel caso di una richiesta di metadati utente, il risultato può essere un oggetto primitivo o JSON che rappresenta il payload di metadati. La struttura effettiva degli oggetti metadati utente JSON è simile alla seguente:
{
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"]
}
Ad esempio:
// 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);
}
Attivato da: getMetadata()
Torna all'inizio
selectedProvider(result) selectedProvider(result)
Descrizione: implementa questo callback per ricevere l'MVPD attualmente selezionato e il risultato dell'autenticazione dell'utente corrente racchiuso nel parametro result. Il parametro result è un oggetto con le seguenti proprietà:
- MVPD Il MVPD attualmente selezionato o null se non è stato selezionato alcun MVPD.
- AE_State Il risultato dell'autenticazione per l'utente corrente, uno dei seguenti: "Nuovo utente", "Utente non autenticato" o "Utente autenticato"
Attivato da: getSelectedProvider()