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

Recupera credenziali client: L'applicazione di streaming recupera le credenziali client chiamando l'endpoint /o/client/register.

• L’applicazione di streaming deve memorizzare le credenziali del client e utilizzarle a tempo indefinito quando è necessario recuperare un token di accesso.

Recupera token di accesso: L'applicazione di streaming recupera il token di accesso chiamando l'endpoint /o/client/token.

• L’applicazione di streaming deve archiviare e utilizzare il token di accesso fino alla scadenza, quindi eliminarlo e ottenerne uno nuovo.

Recupera profili: L'applicazione di streaming verifica i profili esistenti chiamando l'endpoint /api/v2/{serviceProvider}/profiles.

Scenario 1: sono presenti profili esistenti. L'applicazione di streaming può passare alla Fase di preautorizzazione o alla Fase di autorizzazione.

Scenario 2: Non sono presenti profili. L'applicazione di streaming potrebbe procedere al passaggio successivo per Autenticare l'utente.

Scenario 3: Non sono presenti profili, l'applicazione di streaming 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: L'applicazione di streaming recupera l'elenco degli MVPD disponibili chiamando l'endpoint /api/v2/{serviceProvider}/configuration.

• L’applicazione di streaming può implementare un meccanismo di filtro personalizzato per perfezionare l’elenco degli MVPD dalla risposta di configurazione, visualizzando solo i fornitori previsti e nascondendo 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: L'applicazione di streaming avvia una sessione di autenticazione chiamando l'endpoint /api/v2/{serviceProvider}/essions.

Scenario 1: L'applicazione 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'applicazione 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: L'applicazione di streaming 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}.

• L'applicazione di streaming deve avviare il meccanismo di polling nelle seguenti condizioni:

  • Autenticazione eseguita all'interno dell'applicazione primaria (schermo): L'applicazione primaria (streaming) deve avviare il polling quando l'utente raggiunge la pagina di destinazione finale, dopo che il componente del 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 primaria (in streaming) 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.

• L'applicazione di streaming 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.

• L'applicazione di streaming deve configurare la frequenza del meccanismo di polling nelle seguenti condizioni:

  • Autenticazione eseguita all'interno dell'applicazione principale (schermo): L'applicazione principale (streaming) deve eseguire il polling ogni 3-5 secondi o più.

  • Autenticazione eseguita all'interno di un'applicazione secondaria (schermo): L'applicazione primaria (streaming) deve eseguire il polling ogni 3-5 secondi o più.

• L’applicazione di streaming deve memorizzare in cache parti delle informazioni del profilo dell’utente in un archivio persistente per evitare richieste non necessarie e migliorare l’esperienza utente.

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

• L’applicazione di streaming non è necessaria per archiviare 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.

• L'applicazione di streaming può determinare il motivo di una decisione di preautorizzazione negata esaminando il codice di errore e il messaggio inclusi nella risposta dall'endpoint di preautorizzazione delle decisioni. 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.

• L’applicazione di streaming 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: L'applicazione di streaming recupera la decisione di autorizzazione per una risorsa specifica chiamando l'endpoint /api/v2/{serviceProvider}/decision/authorize/{mvpd}.

• L'applicazione di streaming non è necessaria per archiviare le decisioni di autorizzazione nell'archiviazione persistente.

• L'applicazione di streaming 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 informazioni sul motivo specifico per cui la richiesta di autorizzazione è 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 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.

• Non è necessario che l’applicazione di streaming aggiorni un token multimediale scaduto mentre il flusso è in riproduzione attiva. 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.

• L’applicazione di streaming 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 Adobe Pass: L'applicazione di streaming avvia il flusso di disconnessione chiamando l'endpoint /api/v2/{serviceProvider}/logout/{mvpd}.

• L'applicazione di streaming deve seguire le istruzioni fornite negli attributi actionName e actionType della risposta dell'endpoint di disconnessione per garantire il completamento corretto del processo di disconnessione.

  • Se l'attributo actionType nella risposta è impostato su "interattivo":

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

    • Scenario 2: L'applicazione 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.