Elenco di controllo REST API V2 rest-api-v2-checklist

Requisiti

Rischi

Utilizza un’applicazione registrata con ambito REST API v2.

Rischi che scatenano risposte di errore HTTP 401 "Non autorizzato", sovraccarico delle risorse di sistema e aumento della latenza.

Memorizza le credenziali del client nell’archivio permanente e riutilizzale per ogni richiesta di token di accesso.

Rischia la perdita dell'autenticazione quando vengono rigenerate le credenziali del client.

Memorizza i token di accesso nell’archiviazione persistente e riutilizzali fino alla scadenza.

Non richiedere un nuovo token per ogni chiamata API REST v2, aggiorna i token di accesso solo alla scadenza.

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Requisiti

Rischi

Recupera la risposta di configurazione solo quando viene richiesto di richiedere all’utente di selezionare il proprio MVPD (provider TV) prima della fase di autenticazione.

Non è necessario recuperare la risposta di configurazione quando:

• Utente già autenticato.
• All’utente viene offerto l’accesso temporaneo.
• L’autenticazione dell’utente è scaduta, ma è possibile richiedere all’utente di confermare che è ancora un abbonato del MVPD selezionato in precedenza.

Rischi di sovraccarico delle risorse di sistema e aumento della latenza.

Memorizza la selezione del provider di Pay TV (MVPD) dell'utente in un archivio permanente per utilizzarla in tutte le fasi successive:

• Dall’archivio di risposta della configurazione, l’utente ha selezionato "id" MVPD.
• Dall’archivio di risposta della configurazione, l’utente ha selezionato MVPD "displayName".
• Dall’archivio di risposta della configurazione, l’utente ha selezionato "logoUrl" MVPD.

Rischi di sovraccarico delle risorse di sistema e aumento della latenza.

Requisiti

Rischi

Avvia il meccanismo di polling nelle seguenti condizioni:

Autenticazione eseguita nell'applicazione primaria (schermata)

• L’applicazione primaria (streaming) 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 (schermo)

• L’applicazione principale (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.

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Arresta il meccanismo di polling nelle seguenti condizioni:

Autenticazione riuscita

• Le informazioni del profilo dell’utente vengono recuperate correttamente, confermando il loro stato di autenticazione, pertanto il polling non è più necessario.

Sessione di autenticazione e scadenza del codice

• La sessione di autenticazione e il codice scadono, l’utente deve riavviare il processo di autenticazione e il polling che utilizza il codice di autenticazione precedente deve essere interrotto immediatamente.

Nuovo codice di autenticazione generato

• Se l’utente richiede un nuovo codice di autenticazione, la sessione esistente viene invalidata e il polling che utilizza il codice di autenticazione precedente deve essere interrotto immediatamente.

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Configura la frequenza del meccanismo di polling nelle seguenti condizioni:

Autenticazione eseguita nell'applicazione primaria (schermata)

• 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 principale (streaming) deve eseguire il polling ogni 3-5 secondi.

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Memorizza parti delle informazioni del profilo dell’utente nell’archiviazione persistente per migliorare le prestazioni e ridurre al minimo le chiamate REST API v2 non necessarie.

La memorizzazione nella cache deve concentrarsi sui seguenti campi di risposta dei profili:

mvpd

• L'applicazione client può utilizzarlo per tenere traccia del provider TV selezionato dall'utente e continuare a utilizzarlo ulteriormente durante le fasi di pre-autorizzazione o autorizzazione.
• Alla scadenza del profilo utente corrente, l’applicazione client può utilizzare la selezione di MVPD memorizzata e chiedere semplicemente all’utente di confermare.

attributi

• Utilizzato per personalizzare l’esperienza utente in base a diverse chiavi di metadati utente (ad esempio, zip, maxRating, ecc.).
• I metadati dell’utente diventano disponibili al termine del flusso di autenticazione, pertanto l’applicazione client non deve eseguire query su un endpoint separato per recuperare le informazioni sui metadati dell’utente, in quanto sono già incluse nelle informazioni del profilo.
• Alcuni attributi di metadati possono essere aggiornati durante la fase di autorizzazione, a seconda di MVPD (ad esempio, Charter) e dell’attributo di metadati specifico (ad esempio, familyID). Di conseguenza, l’applicazione client potrebbe dover eseguire nuovamente la query sulle API dei profili dopo l’autorizzazione per recuperare i metadati dell’utente più recenti.

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Requisiti

Rischi

Utilizza le decisioni di preautorizzazione per il filtro dei contenuti e mai per le decisioni di riproduzione.

Rischi che violano gli accordi contrattuali tra programmatore, MVPD e Adobe.

Rischio di aggirare i sistemi di monitoraggio e di avviso.

Gestisci i codici di errore avanzati in modo appropriato e utilizza il campo Azione per determinare i passaggi di correzione necessari.

Solo un numero limitato di codici di errore avanzati richiede un nuovo tentativo, mentre la maggior parte richiede risoluzioni alternative come specificato nel campo Azione.

Assicurarsi che qualsiasi meccanismo di ripetizione dei tentativi implementato per recuperare le decisioni di pre-autorizzazione non generi un loop infinito e che limiti i tentativi a un numero ragionevole (ad esempio, 2-3).

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Memorizza nella cache le decisioni di autorizzazione riuscite per migliorare le prestazioni e ridurre al minimo le chiamate REST API v2 non necessarie, in quanto gli aggiornamenti degli abbonamenti durante l’esecuzione dell’applicazione non sono frequenti.

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Requisiti

Rischi

Ottenere decisioni di autorizzazione prima della riproduzione, indipendentemente dall'esistenza di una decisione di preautorizzazione.

Consenti ai flussi di continuare senza interruzioni anche se il token multimediale scade durante la riproduzione e richiedi una nuova decisione di autorizzazione contenente un token multimediale (nuovo) quando l'utente effettua la richiesta di riproduzione successiva, indipendentemente dal fatto che si tratti della stessa risorsa o di una risorsa diversa.

I flussi attivi in esecuzione per periodi di tempo prolungati possono scegliere di richiedere una nuova decisione di autorizzazione in seguito a operazioni video quali la sospensione del contenuto, l'avvio di interruzioni commerciali o la modifica di configurazioni a livello di risorsa quando il sistema MRSS subisce modifiche.

Rischi che violano gli accordi contrattuali tra programmatore, MVPD e Adobe.

Rischio di aggirare i sistemi di monitoraggio e di avviso.

Gestisci i codici di errore avanzati in modo appropriato e utilizza il campo Azione per determinare i passaggi di correzione necessari.

Solo un numero limitato di codici di errore avanzati richiede un nuovo tentativo, mentre la maggior parte richiede risoluzioni alternative come specificato nel campo Azione.

Assicurarsi che qualsiasi meccanismo di esecuzione di nuovi tentativi implementato per recuperare le decisioni di autorizzazione non generi un loop infinito e che limiti i nuovi tentativi a un numero ragionevole (ad esempio, 2-3).

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Requisiti

Rischi

Implementa l’API di logout per consentire agli utenti di disconnettersi manualmente, terminando il loro profilo autenticato e seguire il nome dell’azione REST API v2 specificato per ogni profilo rimosso:

• Per gli MVPD che supportano un endpoint di logout, l’applicazione client deve passare all’"url" fornito in un user-agent.
• Per i profili di tipo "appleSSO", l’applicazione client richiede di guidare l’utente anche alla disconnessione dal livello partner (impostazioni di sistema di Apple).

Rischia il malfunzionamento dell'applicazione client a causa del supporto mancante sul lato dell'applicazione client.

Requisiti

Rischi

Invia l'intestazione Authorization per ogni richiesta REST API v2.

Rischi che scatenano risposte di errore HTTP 401 "Non autorizzato", sovraccarico delle risorse di sistema e aumento della latenza.

Invia l'intestazione AP-Device-Identifier per ogni richiesta REST API v2.

Anche quando la richiesta proviene da un server per conto di un dispositivo, il valore dell'intestazione AP-Device-Identifier deve riflettere l'identificatore effettivo del dispositivo di streaming.

Rischi che attivano le risposte di errore HTTP 400 "Richiesta non valida", sovraccarico delle risorse di sistema e aumento della latenza.

Invia l'intestazione X-Device-Info per ogni richiesta REST API v2.

Anche quando la richiesta proviene da un server per conto di un dispositivo, il valore dell'intestazione X-Device-Info deve riflettere le informazioni effettive sul dispositivo di streaming.

Rischi classificati come provenienti da una piattaforma sconosciuta e trattati come insicuri, soggetti a norme più restrittive, come TTL di autenticazione più brevi.

Inoltre, alcuni campi, come connectionIp e connectionPort del dispositivo di streaming, sono obbligatori per funzionalità quali l'autenticazione di base di Spectrum.

Calcola e archivia un identificatore di dispositivo stabile che non cambia in seguito a aggiornamenti o riavvii per l'intestazione AP-Device-Identifier.

Per le piattaforme senza un identificatore hardware, generare un identificatore univoco dagli attributi dell'applicazione e mantenerlo.

Rischia di perdere l’autenticazione quando l’identificatore del dispositivo cambia.

Assicurati di inviare solo i parametri e le intestazioni previsti dell’API REST v2.

Rischi che attivano le risposte di errore HTTP 400 "Richiesta non valida", sovraccarico delle risorse di sistema e aumento della latenza.

Requisiti

Rischi

Gestisci i codici di errore avanzati in modo appropriato e utilizza il campo Azione per determinare i passaggi di correzione necessari.

Solo un numero limitato di codici di errore avanzati richiede un nuovo tentativo, mentre la maggior parte richiede risoluzioni alternative come specificato nel campo Azione.

La maggior parte dei codici di errore avanzati elencati nella documentazione di Codici di errore avanzati - REST API V2 può essere impedita completamente se gestita correttamente durante la fase di sviluppo prima di avviare l'applicazione.

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Rischia il malfunzionamento dell'applicazione client a causa di una gestione mancante dei codici di errore avanzati, causando messaggi di errore non chiari, istruzioni utente non corrette o comportamenti di fallback non corretti.

Differenziare tra la gestione delle risposte di errore HTTP (ad es. 400, 401, 403, 404, 405, 500) e delle risposte di successo (ad es. 200, 201) che contengono payload di codici di errore avanzati, come descritto in precedenza.

Solo un numero limitato di codici di errore HTTP richiede un nuovo tentativo, mentre la maggior parte richiede risoluzioni alternative.

La maggior parte delle risposte di errore HTTP può essere evitata completamente se gestita correttamente durante la fase di sviluppo prima di avviare l'applicazione.

Rischi di sovraccarico delle risorse di sistema, aumento della latenza e potenziale attivazione delle risposte di errore HTTP 429 "Troppe richieste".

Rischia il malfunzionamento dell'applicazione client a causa di una gestione mancante dei codici di errore avanzati, causando messaggi di errore non chiari, istruzioni utente non corrette o comportamenti di fallback non corretti.

Requisiti

Rischi

Sviluppa e testa l’applicazione utilizzando gli ambienti ufficiali non di produzione per l’autenticazione di Adobe Pass:

• Prequal-Produzione
• Release-Staging

Esegui un controllo qualità completo in questi ambienti prima di lanciare la versione di produzione.

Le applicazioni client non devono passare alla fase Release-Production senza aver prima completato la convalida end-to-end in ambienti non di produzione.

Rischi di lancio con difetti critici e gravi.

La mancanza di un percorso di debug breve ed efficiente può impedire al supporto e al team tecnico di Adobe di intervenire rapidamente.

Pratiche

Rischi

Verifica in modo proattivo la validità del token di accesso per aggiornarlo quando è scaduto.

Prima di ritentare la richiesta originale, verificare che il token di accesso venga aggiornato in base a eventuali tentativi per la gestione di errori HTTP 401 "Non autorizzati".

Rischi che scatenano risposte di errore HTTP 401 "Non autorizzato", sovraccarico delle risorse di sistema e aumento della latenza.

Pratiche

Rischi

Memorizza la risposta di configurazione in memoria o nell’archiviazione persistente per un breve periodo di tempo (ad esempio, 3-5 minuti) per migliorare le prestazioni e ridurre al minimo le chiamate REST API v2 non necessarie.

Rischi di sovraccarico delle risorse di sistema e aumento della latenza.

Pratiche

Rischi

Convalida il codice di autenticazione inviato tramite l'input dell'utente nell'applicazione secondaria (seconda) (schermata) prima di chiamare l'API /api/v2/authenticate nelle seguenti condizioni:

Autenticazione eseguita nell'applicazione secondaria (schermata) con mvpd preselezionato

• Utilizza Riprendi sessione di autenticazione - POST /api/v2/{serviceProvider}/session/{code}

Autenticazione eseguita nell'applicazione secondaria (schermo) senza mvpd preselezionato

• Utilizza Recupera sessione di autenticazione - GET /api/v2/{serviceProvider}/session/{code}

L’applicazione client riceverebbe un errore se il codice di autenticazione fornito fosse stato digitato in modo errato o nel caso in cui la sessione di autenticazione fosse scaduta.

Rischia varie risposte di errore e problemi del flusso di lavoro durante l’autenticazione.

Assicurati che l’applicazione client possa gestire più profili chiedendo all’utente di selezionare un profilo o applicando una logica personalizzata, ad esempio selezionando automaticamente il profilo con il periodo di validità più lungo.

Rischia il malfunzionamento dell'applicazione client a causa del supporto mancante sul lato dell'applicazione client.

Supporta i flussi non di base nel caso in cui l’attività dell’applicazione client richieda:

• Flussi di accesso degradati (funzionalità premium)
• Flussi di accesso temporanei (funzionalità Premium)
• Flussi di accesso Single Sign-On (funzionalità standard)

Rischi che creano un’esperienza utente non ideale.

Pratiche

Rischi

Visualizza un feedback chiaro degli utenti se viene negata una decisione di preautorizzazione, utilizzando i messaggi forniti da MVPD o Adobe tramite codici di errore avanzati.

Rischi che creano un’esperienza utente non ideale.

Pratiche

Rischi

Convalidare i token multimediali utilizzando la libreria Media Token Verifier.

Mettono a rischio i sistemi di frode, come ad esempio lo strappo a flusso.

Visualizza un feedback chiaro degli utenti se una decisione di autorizzazione viene negata, utilizzando i messaggi forniti da MVPD o Adobe tramite codici di errore avanzati.

Rischi che creano un’esperienza utente non ideale.

Pratiche

Rischi

Evitare di chiamare automaticamente (a livello di programmazione) l'API di disconnessione in scenari quali la preautorizzazione o l'autorizzazione negata, in quanto l'API di disconnessione deve essere richiamata solo in risposta a una richiesta diretta dell'utente.

Rischia di confondere l’utente sul fatto che l’autenticazione non riesca.

Pratiche

Rischi

Riutilizza il codice dell’API REST v1 per calcolare l’identificatore del dispositivo e le informazioni sul dispositivo con modifiche minori, ma assicurati di inviare solo i parametri e le intestazioni previsti per l’API REST v2.

Riutilizzare il codice da REST API v1 per richiamare l'API DCR per recuperare un token di accesso.

-

Pratiche

Rischi

Verifica che i seguenti flussi di base siano testati tra dispositivi e piattaforme:

Flussi di autenticazione

• Scenario di autenticazione applicazione primaria (schermata)
• Scenario di autenticazione applicazione secondaria (schermata)

(Facoltativo) Flussi di preautorizzazione

• Scenario delle decisioni relative alle autorizzazioni di prova
• Verifica scenario decisioni di rifiuto

Flussi di autorizzazione

• Scenario delle decisioni relative alle autorizzazioni di prova
• Verifica scenario decisioni di rifiuto

Flussi di disconnessione

Verificare inoltre altri flussi di accesso, se applicabili:

• Flussi di accesso degradati (funzionalità premium)
• Flussi di accesso temporanei (funzionalità Premium)
• Flussi di accesso Single Sign-On (funzionalità standard)

Integrazioni MVPD di livello superiore (per i provider più utilizzati).

Rischio di guasti imprevisti nella produzione, in particolare nelle piattaforme testate con minore frequenza o flussi rari come scenari negativi.

Utilizza il sito Web Adobe Developer.

-

Fase

Obbligatorio

(fortemente) consigliato

Memorizza credenziali client nella cache

Token di accesso alla cache

Convalidare e aggiornare i token di accesso

Riduci al minimo i recuperi delle risposte di configurazione

Risposta alla configurazione della cache

Ottimizzazione del meccanismo di polling

Memorizza nella cache parti dei profili

Supporta più profili

Supporta la funzionalità di degrado (se richiesta dall'azienda)

Supporta la funzionalità TempPass (se richiesta dall'azienda)

Supporta la funzionalità Single Sign-On (se richiesta dall'azienda)

Decisioni di pre-autorizzazione per la cache

Ripeti ottimizzazione del meccanismo

Migliorare l’esperienza utente utilizzando codici di errore per le decisioni di preautorizzazione negate

Recupera la decisione di autorizzazione quando l'utente richiede la riproduzione

Ripeti ottimizzazione del meccanismo

Migliora l'esperienza utente utilizzando codici di errore per le decisioni di autorizzazione negate

Convalida del token multimediale

Implementare l'API di disconnessione per consentire agli utenti di disconnettersi manualmente

Evita di chiamare automaticamente l'API di disconnessione

Obbligatorio

(fortemente) consigliato

Segui le specifiche delle intestazioni obbligatorie

Riutilizzare il codice dall’API REST v1

Implementa gestione avanzata degli errori

Implementa gestione degli errori HTTP

-