Manuale dell’SDK iOS/tvOS iostvos-sdk-cookbook

Creare le funzioni di callback:

• setRequestorComplete()

• Attivato da setRequestor(), restituisce esito positivo o negativo.

• Il successo indica che puoi procedere con le chiamate di adesione.

• displayProviderDialog(mvpds)

  • Attivato da getAuthentication() solo se l'utente non ha selezionato un provider (MVPD) e non è ancora autenticato.
  • Il parametro mvpds è un array di provider disponibili per l'utente.

• setAuthenticationStatus(status, errorcode)

  • Attivato da checkAuthentication() ogni volta.
  • Attivato da getAuthentication() solo se l'utente è già autenticato e ha selezionato un provider.
  • Lo stato restituito è success o failure, il codice di errore descrive il tipo di errore.

• navigateToUrl(url)

  • Attivazione eseguita da getAuthentication() dopo la selezione di un MVPD da parte dell'utente. Il parametro url fornisce il percorso della pagina di accesso di MVPD.

• sendTrackingData(event, data)

  • Attivato da checkAuthentication(), getAuthentication(), checkAuthorization(), getAuthorization(), setSelectedProvider().
  • Il parametro event indica quale evento di adesione si è verificato; il parametro data è un elenco di valori relativi all'evento.

• setToken(token, resource)

  • Attivazione da checkAuthorization() e getAuthorization() dopo un'autorizzazione riuscita per visualizzare una risorsa.
  • Il parametro token è il token multimediale di breve durata. Il parametro resource è il contenuto che l'utente è autorizzato a visualizzare.

• tokenRequestFailed(resource, code, description)

  • Attivazione da checkAuthorization() e getAuthorization() dopo un'autorizzazione non riuscita.
  • Il parametro resource è il contenuto che l'utente stava tentando di visualizzare. Il parametro code è il codice di errore che indica il tipo di errore che si è verificato. Il parametro description descrive l'errore associato al codice di errore.

• selectedProvider(mvpd)

  • Attivato da getSelectedProvider().
  • Il parametro mvpd fornisce informazioni sul provider selezionato dall'utente.

• setMetadataStatus(metadata, key, arguments)

  • Attivato da getMetadata().
  • Il parametro metadata fornisce i dati specifici richiesti; il parametro key è la chiave utilizzata nella richiesta getMetadata() e il parametro arguments è lo stesso dizionario passato a getMetadata().

• "preauthorizedResources(authorizedResources)"

  • Attivato da checkPreauthorizedResources().

  • Il parametro authorizedResources presenta le risorse che l'utente
    è autorizzato a visualizzare.

• "presentTvProviderDialog(viewController)"

  • Attivazione eseguita da getAuthentication() quando il richiedente corrente supporta almeno MVPD con supporto SSO.
  • Il parametro viewController è la finestra di dialogo SSO di Apple e deve essere presentato sul controller della visualizzazione principale.

• "dismissTvProviderDialog(viewController)"

  • Attivato da un’azione dell’utente (selezionando "Annulla" o "Altri provider TV" dalla finestra di dialogo SSO di Apple).
  • Il parametro viewController è la finestra di dialogo SSO di Apple e deve essere chiuso dal controller della visualizzazione principale.

Avviare l'applicazione di livello superiore.

Avvia autenticazione Adobe Pass

a. Chiamare init per creare una singola istanza di Adobe Pass Authentication AccessEnabler.

• Dipendenza: Adobe Pass Authentication Native iOS/tvOS Library (AccessEnabler)

b. Chiamare setRequestor() per stabilire l'identità del programmatore; passare requestorID del programmatore e (facoltativamente) un array di endpoint di autenticazione Adobe Pass. Per tvOS dovrai anche fornire la chiave pubblica e il segreto. Per informazioni dettagliate, consulta la documentazione senza client.

• Dipendenza: ID richiedente autenticazione Adobe Pass valido (utilizzare l'account di autenticazione Adobe Pass)
  per il manager).

• Trigger:

  setRequestorComplete() callback.

Sono disponibili due opzioni di implementazione: una volta inviate le informazioni di identificazione del richiedente al server back-end, il livello applicazione dell'interfaccia utente può scegliere uno dei due approcci seguenti:

1. Attendere l'attivazione del callback setRequestorComplete() (parte del delegato AccessEnabler). Questa opzione fornisce la massima certezza che setRequestor() è stato completato, quindi è consigliata per la maggior parte delle implementazioni.

2. Continuare senza attendere l'attivazione del callback setRequestorComplete() e iniziare a emettere richieste di adesione. Queste chiamate (checkAuthentication, checkAuthorization, getAuthentication, getAuthorization, checkPreauthorizedResource, getMetadata, logout) sono in coda dalla libreria AccessEnabler, che eseguirà le chiamate di rete effettive dopo setRequestor(). Questa opzione può talvolta essere interrotta se, ad esempio, la connessione di rete è instabile.

Chiamare checkAuthentication() per verificare la presenza di un'autenticazione esistente senza avviare il flusso di autenticazione completo. Se la chiamata ha esito positivo, puoi passare direttamente al flusso di autorizzazione. In caso contrario, passare al flusso di autenticazione.

• Dipendenza: Chiamata riuscita a setRequestor() (questa dipendenza si applica anche a tutte le chiamate successive).

• Trigger: setAuthenticationStatus() callback.

Chiamare getAuthentication() per avviare il flusso di autenticazione o per ottenere la conferma che l'utente è già
autenticato.

Trigger:

• Il callback setAuthenticationStatus(), se l'utente è già autenticato. In questo caso, passare direttamente al Flusso di autorizzazione.

• Il callback displayProviderDialog(), se l'utente non è ancora autenticato.

Presenta all’utente l’elenco dei provider inviati a
displayProviderDialog().

Dopo che l'utente ha selezionato un provider, ottenere l'URL del MVPD dell'utente dal callback navigateToUrl: o navigateToUrl:useSVC: e aprire un controller UIWebView/WKWebView o SFSafariViewController e indirizzare tale controller all'URL.

Tramite l'istanza di UIWebView/WKWebView o SFSafariViewController creata nel passaggio precedente, l'utente arriva alla pagina di accesso di MVPD e immette le credenziali di accesso. Diverse operazioni di reindirizzamento si verificano all'interno del controller.

Dopo che l’utente ha effettuato l’accesso, il livello dell’applicazione rileva il caricamento di un URL personalizzato specifico. Questo URL personalizzato specifico non è valido e non è destinato al controller per caricarlo effettivamente. Deve essere interpretato solo dall'applicazione come un segnale del completamento del flusso di autenticazione e della sicurezza della chiusura del controller UIWebView/WKWebView o SFSafariViewController. Nel caso in cui sia necessario utilizzare un controller SFSafariViewController, l'URL personalizzato specifico è definito da application's custom scheme (ad esempio adbe.u-XFXJeTSDuJiIQs0HVRAg://adobe.com), altrimenti questo URL personalizzato specifico è definito dalla costante ADOBEPASS_REDIRECT_URL (ovvero adobepass://ios.app).

Chiudere il controller UIWebView/WKWebView o SFSafariViewController e chiamare il metodo API handleExternalURL:url di AccessEnabler, che indica ad AccessEnabler di recuperare il token di autenticazione dal server back-end.

(Facoltativo) Chiamare checkPreauthorizedResources(resources) per verificare quali risorse l'utente è autorizzato a visualizzare. Il parametro resources è un array di risorse protette associate al token di autenticazione dell'utente. Un uso per le informazioni di autorizzazione ottenute dal MVPD dell’utente è quello di decorare l’interfaccia utente (ad esempio, simboli bloccati/sbloccati accanto al contenuto protetto).

• Trigger: preauthorizedResources() callback
• Punto di esecuzione: dopo il completamento del flusso di autenticazione

Se l’autenticazione ha esito positivo, procedi al flusso di autorizzazione.

Chiamare getAuthentication() per avviare il flusso di autenticazione o per ottenere la conferma che l'utente è già autenticato.
Trigger:

• Il callback presentTvProviderDialog(), se l'utente non è autenticato e il richiedente corrente dispone almeno di un MVPD che supporta l'SSO. Se nessun MVPD supporta l'SSO, verrà utilizzato il flusso di autenticazione classico.

Dopo aver selezionato un provider, la libreria AccessEnabler otterrà un token di autenticazione con le informazioni fornite dal framework VSA di Apple.

Verrà attivato il callback setAuthenticationsStatus(). A questo punto l’utente deve essere autenticato con l’SSO di Apple.

[Facoltativo] Chiamare checkPreauthorizedResources(resources) per verificare quali risorse l'utente è autorizzato a visualizzare. Il parametro resources è un array di risorse protette associate al token di autenticazione dell'utente. Un uso per le informazioni di autorizzazione ottenute dal MVPD dell’utente è quello di decorare l’interfaccia utente (ad esempio, simboli bloccati/sbloccati accanto al contenuto protetto).

• Trigger: preauthorizedResources() callback
• Punto di esecuzione: dopo il completamento del flusso di autenticazione

Se l’autenticazione ha esito positivo, procedi al flusso di autorizzazione.

Chiama getAuthentication() per avviare
flusso di autenticazione o per ottenere la conferma che l’utente è già
autenticato.
Trigger:

• Il callback presentTvProviderDialog(), se l'utente non è autenticato e il richiedente corrente dispone almeno di un MVPD che supporta l'SSO. Se nessun MVPD supporta l'SSO, verrà utilizzato il flusso di autenticazione classico.

Dopo che l'utente ha selezionato un provider, verrà chiamato il callback status(). Verrà fornito un codice di registrazione e la libreria AccessEnabler inizierà a eseguire il polling del server per un'autenticazione a seconda schermata riuscita.

Se il codice di registrazione fornito è stato utilizzato per l'autenticazione nella seconda schermata, verrà attivato il callback setAuthenticatiosStatus(). A questo punto l’utente deve essere autenticato con l’SSO di Apple.

[Facoltativo] Chiamare checkPreauthorizedResources(resources) per verificare quali risorse l'utente è autorizzato a visualizzare. Il parametro resources è un array di risorse protette associate al token di autenticazione dell'utente. Un uso per le informazioni di autorizzazione ottenute dal MVPD dell’utente è quello di decorare l’interfaccia utente (ad esempio, simboli bloccati/sbloccati accanto al contenuto protetto).

• Trigger: preauthorizedResources() callback

• Punto di esecuzione: dopo il completamento del flusso di autenticazione

Se l’autenticazione ha esito positivo, procedi al flusso di autorizzazione.

Chiamare getAuthorization() per avviare il flusso di autorizzazione.

• Dipendenza: ID risorsa validi concordati con gli MVPD.
• Gli ID delle risorse devono essere gli stessi utilizzati su qualsiasi altro dispositivo o piattaforma e devono essere gli stessi in tutti gli MVPD. Per informazioni sugli ID delle risorse, vedere Identificazione delle risorse protette

Convalida autenticazione e autorizzazione.

• Se la chiamata getAuthorization() ha esito positivo: l'utente dispone di token AuthN e AuthZ validi (l'utente è autenticato e autorizzato a guardare il contenuto multimediale richiesto).

• Se getAuthorization() non riesce: esaminare l'eccezione generata per determinarne il tipo (AuthN, AuthZ o altro):

  • In caso di errore di autenticazione (AuthN), riavvia il flusso di autenticazione.
  • Se si trattava di un errore di autorizzazione (AuthZ), l’utente non è autorizzato a guardare il contenuto multimediale richiesto e deve visualizzare all’utente un qualche tipo di messaggio di errore.
  • Se si è verificato un altro tipo di errore (errore di connessione, errore di rete, ecc.) quindi visualizza un messaggio di errore appropriato.

Convalida il token multimediale breve.
Utilizza la libreria Adobe Pass Authentication Media Token Verifier per verificare il token multimediale di breve durata restituito dalla chiamata getAuthorization() precedente:

• Se la convalida ha esito positivo: riproduci il file multimediale richiesto per l’utente.
• Se la convalida non riesce: il token AuthZ non è valido, la richiesta di supporto deve essere rifiutata e l’utente deve visualizzare un messaggio di errore.

Tornare al normale flusso dell'applicazione.

L’utente seleziona il file multimediale da visualizzare.

Il supporto è protetto? L'applicazione verifica se il supporto selezionato è protetto:

• Se il supporto selezionato è protetto, l'applicazione avvia il flusso di autorizzazione.

• Se il supporto selezionato non è protetto, riprodurlo per
  utente.

Chiamare logout() per disconnettersi. AccessEnabler cancella tutti i valori e i token memorizzati nella cache. Dopo aver cancellato la cache, AccessEnabler effettua una chiamata al server per pulire le sessioni lato server. Poiché la chiamata al server potrebbe causare un reindirizzamento SAML all’IdP (consentendo la pulizia della sessione sul lato IdP), questa chiamata deve seguire tutti i reindirizzamenti. Per questo motivo, questa chiamata deve essere gestita all'interno di un controller UIWebView/WKWebView o SFSafariViewController.

a. Seguendo lo stesso modello del flusso di lavoro di autenticazione, il dominio AccessEnabler invia una richiesta al livello dell'applicazione dell'interfaccia utente, tramite il callback navigateToUrl: o navigateToUrl:useSVC:, per creare un controller UIWebView/WKWebView o SFSafariViewController e istruire tale utente a caricare l'URL fornito nel parametro url del callback. Questo è l'URL dell'endpoint di disconnessione sul server back-end.

b. L'applicazione deve monitorare l'attività del controller UIWebView/WKWebView or SFSafariViewController e rilevare il momento in cui viene caricato un URL personalizzato specifico, mentre viene eseguito diversi reindirizzamenti. Questo URL personalizzato specifico non è valido e non è destinato al controller per caricarlo effettivamente. Deve essere interpretato solo dall'applicazione come un segnale del completamento del flusso di disconnessione e della sicurezza della chiusura del controller UIWebView/WKWebView o SFSafariViewController. Quando il controller carica questo URL personalizzato specifico, l'applicazione deve chiudere il controller UIWebView/WKWebView or SFSafariViewController e chiamare il metodo API handleExternalURL:url di AccessEnabler. Nel caso in cui sia necessario utilizzare un controller SFSafariViewController, l'URL personalizzato specifico è definito da application's custom scheme (ad esempio, adbe.u-XFXJeTSDuJiIQs0HVRAg://adobe.com), altrimenti questo URL personalizzato specifico è definito dalla costante ADOBEPASS_REDIRECT_URL (ovvero adobepass://ios.app).