Manuale dell’API REST V2 (server-to-server) rest-api-v2-cookbook-server-to-server

Comunica con il servizio Adobe Pass per conto dell’app di streaming.

Raccogli e passa un identificatore di dispositivo univoco per il dispositivo di streaming, come richiesto dall'intestazione AP-Device-Identifier.

Raccogli e passa informazioni precise sul dispositivo di streaming, inclusa la porta di origine e i dettagli specifici del dispositivo, come richiesto dall'intestazione X-Device-Info.

Raccogli e passa l’indirizzo IP del dispositivo di streaming come richiesto dall’intestazione X-Forwarded-For.

Memorizza in modo sicuro parametri quali ID dispositivo, ID client e segreto client nell’app di streaming o nel servizio programmatore.

Formatta e invia i dati in conformità agli MVPD e alle app integrate, inclusi l’IP del dispositivo, la porta di origine, le informazioni specifiche del dispositivo, MRSS e gli identificatori facoltativi come ECID.

Gestisci e gestisci in modo sicuro i certificati condivisi con Adobe per la trasmissione di metadati utente crittografati.

Rispetta la validità del profilo di autenticazione e della decisione di autorizzazione durante la memorizzazione in cache, garantendo che gli stati di autenticazione e autorizzazione vengano invalidati al momento della notifica.

Restituisci le decisioni di autorizzazione e le istruzioni pertinenti all’app di streaming.

Il servizio Adobe Pass opera su più data center dislocati in diverse aree geografiche in tutti gli Stati Uniti per ottimizzare le prestazioni e ridurre al minimo la latenza.

• Il servizio Programmatore deve adottare una strategia di infrastruttura simile, garantendo tempi di risposta a bassa latenza da parte di Adobe Pass.

Il programmatore deve fornire l'intervallo IP pubblico del proprio ambiente di produzione.

• Questi IP verranno aggiunti a un inserisco nell'elenco Consentiti di all’interno dell’infrastruttura Adobe Pass.

Il servizio Programmer deve limitare il caching DNS a un massimo di 30 secondi per consentire il reindirizzamento dinamico nel caso in cui Adobe debba reindirizzare il traffico a causa di un centro dati non disponibile.

Deve consentire il test delle versioni prima della distribuzione in produzione.

Dovrebbe rimanere operativamente simile alla produzione, consentendo test realistici.

Idealmente, l’ambiente di staging dovrebbe essere connesso agli ambienti di test di Adobe Pass per:

• Consente ai programmatori di eseguire il test sull’infrastruttura di Adobe.

• Se necessario, consenti ad Adobe di fornire assistenza per il test e la risoluzione dei problemi.

Recupera credenziali client: il servizio Programmer recupera le credenziali client chiamando l'endpoint /o/client/register.

• Il servizio programmatore o l’app programmatore devono memorizzare le credenziali del client e utilizzarle a tempo indeterminato quando è necessario recuperare un token di accesso.

Recupera token di accesso: il servizio Programmer recupera il token di accesso chiamando l'endpoint /o/client/token.

• Il servizio programmatore o l’app programmatore devono memorizzare e utilizzare il token di accesso fino alla scadenza, quindi eliminarlo e ottenerne uno nuovo.

Recupera profili: Il servizio Programmatore verifica i profili esistenti per conto dell'app di streaming chiamando l'endpoint /api/v2/{serviceProvider}/profiles.

Scenario 1: sono presenti profili. Il servizio Programmatore può passare alla fase di preautorizzazione o alla fase di autorizzazione.

Scenario 2: Non sono presenti profili. Il servizio Programmatore può procedere al passaggio successivo per Autenticare l'utente.

Scenario 3: Non sono presenti profili. Il servizio Programmatore potrebbe continuare a fornire all'utente l'accesso temporaneo tramite la funzionalità TempPass.

• Questo scenario non rientra nell'ambito di questo documento. Per ulteriori informazioni, fare riferimento alla documentazione Flussi di accesso temporanei.

Recupera configurazione: Il servizio Programmatore recupera l'elenco degli MVPD disponibili chiamando l'endpoint /api/v2/{serviceProvider}/configuration.

• Il servizio programmatore può implementare un meccanismo di filtro personalizzato per perfezionare l’elenco degli MVPD dalla risposta di configurazione, in modo tale che l’app di streaming visualizzi solo i provider previsti nascondendone altri (ad esempio, MVPD in fase di sviluppo, test MVPD, TempPass). In questo modo gli utenti ricevono una selezione accurata al momento di scegliere il proprio provider TV.

Crea sessione di autenticazione: Il servizio Programmer avvia una sessione di autenticazione chiamando l'endpoint /api/v2/{serviceProvider}/essions.

• Il servizio Programmatore deve restituire code e url all'app di streaming.

Scenario 1: L'app di streaming può aprire un browser o una visualizzazione Web, pertanto deve caricare l'autenticazione url.

• L’utente invia il proprio nome utente e password all’interno della pagina di accesso di MVPD. Dopo l’autenticazione corretta, il reindirizzamento finale mostra una pagina di successo.

Scenario 2: L'app di streaming non può aprire un browser, pertanto deve visualizzare l'autenticazione code. È necessaria un'applicazione Web separata per richiedere all'utente di immettere code, creare l'autenticazione url e aprire: /api/v2/authenticate/{serviceProvider}/{code}.

• L’utente invia il proprio nome utente e password all’interno della pagina di accesso di MVPD. Dopo l’autenticazione corretta, il reindirizzamento finale mostra una pagina di successo.

Recupera profilo per codice specifico: Il servizio Programmatore deve implementare un meccanismo di polling utilizzando code per verificare se il profilo è stato generato e salvato correttamente chiamando l'endpoint /api/v2/{serviceProvider}/profiles/code/{code}.

• Il servizio Programmatore deve avviare il meccanismo di polling nelle seguenti condizioni:

  • Autenticazione eseguita all'interno dell'applicazione primaria (schermo): Il servizio Programmatore deve avviare il polling quando l'utente raggiunge la pagina di destinazione finale, dopo che il componente browser carica l'URL specificato per il parametro redirectUrl nella richiesta dell'endpoint Sessions.

  • Autenticazione eseguita all'interno di un'applicazione secondaria (a schermo): L'applicazione del servizio Programmer deve avviare il polling non appena l'utente avvia il processo di autenticazione, subito dopo aver ricevuto la risposta dell'endpoint Sessions e aver visualizzato il codice di autenticazione per l'utente.

• Il servizio Programmatore deve interrompere il meccanismo di polling nelle seguenti condizioni:

  • Autenticazione riuscita: Le informazioni del profilo dell'utente sono state recuperate correttamente, confermando il relativo stato di autenticazione. A questo punto, il polling non è più necessario.

  • Sessione di autenticazione e scadenza codice: La sessione di autenticazione e il codice scadono, come indicato dalla marca temporale notAfter (ad esempio, 30 minuti) nella risposta dell'endpoint Sessions. In questo caso, l’utente deve riavviare il processo di autenticazione e arrestare immediatamente il polling che utilizza il codice di autenticazione precedente.

  • È stato generato un nuovo codice di autenticazione: Se l'utente richiede un nuovo codice di autenticazione sul dispositivo principale (schermo), la sessione esistente non è più valida e il polling che utilizza il codice di autenticazione precedente deve essere interrotto immediatamente.

• Il servizio Programmer deve configurare la frequenza del meccanismo di polling nelle seguenti condizioni:

  • Autenticazione eseguita nell'applicazione primaria (schermo): Il servizio Programmatore deve eseguire il polling ogni 3-5 secondi o più.

  • Autenticazione eseguita all'interno di un'applicazione secondaria (a schermo): Il servizio Programmatore deve eseguire il polling ogni 3-5 secondi o più.

• Il servizio Programmatore deve memorizzare in cache parti delle informazioni del profilo dell’utente in un archivio persistente per evitare richieste inutili e migliorare l’esperienza utente.

Recupera decisioni di preautorizzazione: Il servizio Programmer recupera le decisioni di preautorizzazione per un elenco di risorse chiamando l'endpoint /api/v2/{serviceProvider}/Decisions/preauthorize/{mvpd}.

• Il servizio programmatore deve trasmettere l’elenco dei permessi e negare le decisioni di preautorizzazione all’app di streaming.

• Il servizio Programmer non è necessario per memorizzare le decisioni di preautorizzazione nell'archiviazione persistente. Tuttavia, si consiglia di memorizzare nella cache le decisioni sulle autorizzazioni per migliorare l’esperienza utente. Questo consente di evitare inutili chiamate per risorse già preautorizzate, riducendo la latenza e migliorando le prestazioni.

• Il servizio Programmer può determinare il motivo di una decisione di preautorizzazione negata esaminando il codice di errore e il messaggio inclusi nella risposta dall'endpoint Decisions Preauthorize. Questi dettagli forniscono informazioni sul motivo specifico per cui la richiesta di preautorizzazione è stata negata, aiutando a informare l’esperienza utente o a attivare eventuali operazioni necessarie nell’applicazione. Assicurati che eventuali meccanismi di esecuzione di nuovi tentativi implementati per recuperare le decisioni di preautorizzazione non generino un ciclo infinito se la decisione di preautorizzazione viene negata. Valuta la possibilità di limitare i nuovi tentativi a un numero ragionevole e di gestire i rifiuti in modo appropriato fornendo all’utente un feedback chiaro.

• Il servizio programmatore può ottenere una decisione di preautorizzazione per un numero limitato di risorse in una singola richiesta API, di solito fino a 5, a causa delle condizioni imposte dagli MVPD. Questo numero massimo di risorse può essere visualizzato e modificato dopo aver concordato con gli MVPD tramite Adobe Pass TVE Dashboard da uno degli amministratori dell'organizzazione o da un rappresentante di autenticazione Adobe Pass che agisce per tuo conto.

Recupera decisione di autorizzazione: Il servizio programmatore recupera la decisione di autorizzazione per una risorsa specifica passata dall'app di streaming chiamando l'endpoint /api/v2/{serviceProvider}/decision/authorize/{mvpd}.

• Il servizio Programmer non è necessario per memorizzare le decisioni di autorizzazione nell'archiviazione persistente.

• Il servizio Programmer può determinare il motivo di una decisione di autorizzazione negata esaminando il codice di errore e il messaggio inclusi nella risposta dall'endpoint Decisions Authorize. Questi dettagli forniscono ad insight il motivo specifico per cui la richiesta di autorizzazione è stata negata, aiutando a informare l’esperienza utente o a attivare eventuali operazioni necessarie nell’app di streaming. Assicurati che eventuali meccanismi di esecuzione di nuovi tentativi implementati per recuperare le decisioni di autorizzazione non generino un loop infinito se la decisione di autorizzazione viene negata. Valuta la possibilità di limitare i nuovi tentativi a un numero ragionevole e di gestire i rifiuti in modo appropriato fornendo all’utente un feedback chiaro.

• Il servizio Programmatore può valutare altre regole di business e restituire una decisione di autorizzazione appropriata all'app Streaming.

• Il servizio Programmatore non è necessario per aggiornare un token multimediale scaduto durante la riproduzione attiva del flusso. Se il token multimediale scade durante la riproduzione, il flusso deve poter continuare senza interruzioni. Tuttavia, il client deve richiedere una nuova decisione di autorizzazione e ottenere un nuovo token multimediale la volta successiva che l’utente tenta di riprodurre una risorsa.

• Il servizio programmatore può ottenere una decisione di autorizzazione per un numero limitato di risorse in una singola richiesta API, di solito fino a 1, a causa delle condizioni imposte dagli MVPD.

Avvia disconnessione di Adobe Pass: il servizio Programmer avvia il flusso di disconnessione come richiesto dall'app di streaming chiamando l'endpoint /api/v2/{serviceProvider}/logout/{mvpd}.

• Il servizio Programmatore può eliminare tutte le informazioni memorizzate sull'utente autenticato.

• Il servizio Programmer deve seguire le istruzioni fornite negli attributi actionName e actionType della risposta dell'endpoint Logout per garantire il corretto completamento del processo di logout.

  • Se l'attributo actionType nella risposta è impostato su "interattivo", il servizio Programmatore deve restituire il valore dell'attributo url all'app di streaming.

    • Scenario 1: L'app di streaming può aprire un browser o una visualizzazione Web, pertanto deve caricare la disconnessione url.

    • Scenario 2: L'app di streaming non è in grado di aprire un browser, pertanto il processo di disconnessione può essere interrotto in quanto la sessione di MVPD non è persistita in una cache del browser del dispositivo di streaming.