REST API V2-Cookbook (Client-zu-Server) rest-api-v2-cookbook-client-to-server

Client-Anmeldeinformationen abrufen: Die Streaming-Anwendung ruft Client-Anmeldeinformationen durch Aufruf des Endpunkts /o/client/register ab.

• Die Streaming-Anwendung muss die Client-Anmeldeinformationen speichern und sie unbegrenzt verwenden, wenn ein Zugriffs-Token abgerufen werden muss.

Zugriffs-Token abrufen: Die Streaming-Anwendung ruft das Zugriffs-Token durch Aufruf des Endpunkts /o/client/ ab.

• Die Streaming-Anwendung muss das Zugriffstoken speichern und verwenden, bis es abläuft. Dann muss es verworfen und ein neues abgerufen werden.

Profile abrufen: Streaming-Anwendung sucht nach vorhandenen Profilen, indem der Endpunkt /api/v2/{serviceProvider}/profiles aufgerufen wird.

Szenario 1: Profile vorhanden sind, kann die Streaming-Anwendung in die Phase Vorabautorisierung oder Autorisierung.

Szenario 2: Es sind keine vorhandenen Profile vorhanden. Die Streaming-Anwendung kann mit dem nächsten Schritt fortfahren, um den zu authentifizieren.

Szenario 3: Es sind keine vorhandenen Profile vorhanden. Die Streaming-Anwendung kann fortfahren, dem Benutzer über die Funktion TempPass temporären Zugriff bereitzustellen.

• Dieses Szenario würde den Rahmen dieses Dokuments sprengen. Weitere Informationen finden Sie in der Dokumentation Temporärer".

Konfiguration abrufen: Die Streaming-Anwendung ruft die Liste der verfügbaren MVPDs ab, indem sie den Endpunkt /api/v2/{serviceProvider}/configuration aufruft.

• Die Streaming-Anwendung kann einen benutzerdefinierten Filtermechanismus implementieren, um die Liste der MVPDs aus der Konfigurationsantwort zu verfeinern und nur die vorgesehenen Anbieter anzuzeigen, während andere ausgeblendet werden (z. B. MVPDs in Entwicklung, MVPDs testen, TempPass). Dadurch wird sichergestellt, dass Benutzenden bei der Auswahl ihres TV-Anbieters eine kuratierte Auswahl angezeigt wird.

Authentifizierungssitzung erstellen: Die Streaming-Anwendung initiiert eine Authentifizierungssitzung, indem sie den Endpunkt /api/v2/{serviceProvider}/sessions aufruft.

Szenario 1: Die Streaming-Anwendung kann einen Browser oder eine Webansicht öffnen, daher muss sie die url laden.

• Der Benutzer gibt seinen Benutzernamen und sein Kennwort auf der Anmeldeseite von MVPD ein. Nach erfolgreicher Authentifizierung zeigt die endgültige Umleitung eine Erfolgsseite an.

Szenario 2: Die Streaming-Anwendung kann keinen Browser öffnen, daher muss sie die code anzeigen. Eine separate Web-Anwendung ist erforderlich, um den Benutzer zur Eingabe der code aufzufordern, die url zu erstellen und zu öffnen: /api/v2/Authenticate/{serviceProvider}/{code}.

• Der Benutzer gibt seinen Benutzernamen und sein Kennwort auf der Anmeldeseite von MVPD ein. Nach erfolgreicher Authentifizierung zeigt die endgültige Umleitung eine Erfolgsseite an.

Profil für bestimmten Code abrufen: Die Streaming-Anwendung muss einen Abrufmechanismus mithilfe des code implementieren, um zu überprüfen, ob das Profil erfolgreich generiert und gespeichert wurde, indem der Endpunkt /api/v2/{serviceProvider}/profiles/code/{code} aufgerufen wird.

• Die Streaming-Anwendung muss Abrufmechanismus den folgenden Bedingungen starten:

  • Authentifizierung innerhalb der primären (Bildschirm-)Anwendung durchgeführt: Die primäre (Streaming-)Anwendung sollte beginnen, den Abruf durchzuführen, wenn die Benutzerin oder der Benutzer die endgültige Zielseite erreicht, nachdem die Browser-Komponente die URL geladen hat, die für den redirectUrl-Parameter in der Endpunktanforderung Sitzungen angegeben ist.

  • Authentifizierung in einer sekundären (Bildschirm-)Anwendung: Die primäre (Streaming-)Anwendung sollte beginnen, den Abruf durchzuführen, sobald der Benutzer den Authentifizierungsprozess einleitet - direkt nach Erhalt der Sessions-Endpunktantwort und Anzeige des Authentifizierungs-Codes für den Benutzer.

• Die Streaming-Anwendung muss Abrufmechanismus folgenden Bedingungen stoppen:

  • Erfolgreiche Authentifizierung: Die Profilinformationen des Benutzers wurden erfolgreich abgerufen und bestätigen seinen Authentifizierungsstatus. Zu diesem Zeitpunkt ist keine Abfrage mehr erforderlich.

  • Authentifizierungssitzung und Code-Ablauf: Die Authentifizierungssitzung und der Code laufen ab, wie durch den notAfter Zeitstempel (z. B. 30 Minuten) in der Endpunktantwort Sitzungen angegeben. In diesem Fall muss der Benutzer den Authentifizierungsprozess neu starten, und das Abrufen mit dem vorherigen Authentifizierungs-Code sollte sofort gestoppt werden.

  • Generierter neuer Authentifizierungs-Code: Wenn der Benutzer einen neuen Authentifizierungs-Code auf dem Primärgerät (Bildschirm) anfordert, ist die vorhandene Sitzung nicht mehr gültig und das Abrufen mit dem vorherigen Authentifizierungs-Code sollte sofort gestoppt werden.

• Die Streaming-Anwendung muss Abrufintervall konfigurieren unter den folgenden Bedingungen:

  • Authentifizierung wird innerhalb der primären (Bildschirm-)Anwendung durchgeführt: Die primäre (Streaming-)Anwendung sollte alle 3-5 Sekunden oder länger eine Abfrage durchführen.

  • Authentifizierung in einer sekundären (Bildschirm-)Anwendung: Die primäre (Streaming-)Anwendung sollte alle 3-5 Sekunden oder länger abfragen.

• Die Streaming-Anwendung sollte Teile der Profilinformationen des Benutzers in einem beständigen Speicher zwischenspeichern, um unnötige Anfragen zu vermeiden und das Benutzererlebnis zu verbessern.

Vorabautorisierungsentscheidungen abrufen: Die Streaming-Anwendung ruft Vorabautorisierungsentscheidungen für eine Liste von Ressourcen ab, indem der Endpunkt /api/v2/{serviceProvider}/decisions/preauthorize/{mvpd} aufgerufen wird.

• Die Streaming-Anwendung ist nicht erforderlich, um Entscheidungen vor der Autorisierung in einem persistenten Speicher zu speichern. Es wird jedoch empfohlen, Zulassungsentscheidungen im Speicher zwischenzuspeichern, um das Benutzererlebnis zu verbessern. Dadurch werden unnötige Aufrufe von Ressourcen vermieden, die bereits vorab autorisiert wurden, die Latenz verringert und die Leistung verbessert.

• Die Streaming-Anwendung kann den Grund für eine abgelehnte Vorautorisierungsentscheidung ermitteln, indem sie den Fehlercode und die Nachricht) überprüft die in der Antwort vom Vorautorisierungs-Endpunkt von Decisions enthalten sind. Diese Details bieten Einblicke in den spezifischen Grund, aus dem die Vorabautorisierungsanfrage abgelehnt wurde, und helfen, das Benutzererlebnis oder den Trigger über die erforderliche Handhabung in der Anwendung zu informieren. Stellen Sie sicher, dass ein Wiederholungsmechanismus, der zum Abrufen von Entscheidungen vor der Autorisierung implementiert ist, nicht zu einer Endlosschleife führt, wenn die Entscheidung vor der Autorisierung abgelehnt wird. Erwägen Sie, weitere Zustellversuche auf eine angemessene Anzahl zu beschränken und Ablehnungen elegant zu handhaben, indem Sie dem Benutzer klares Feedback senden.

• Aufgrund von Bedingungen, die von MVPDs auferlegt werden, kann die Streaming-Anwendung in einer einzigen API-Anfrage eine Vorabautorisierungsentscheidung für eine begrenzte Anzahl von Ressourcen erhalten, in der Regel bis zu 5. Diese maximale Anzahl von Ressourcen kann angezeigt und geändert werden, nachdem eine Vereinbarung mit MVPDs über das Adobe Pass TVE-Dashboard von einem Ihrer Organisationsadministratoren oder einem in Ihrem Namen handelnden Adobe Pass-Authentifizierungsmitarbeiter getroffen wurde.

Autorisierungsentscheidung abrufen: Die Streaming-Anwendung ruft die Autorisierungsentscheidung für eine bestimmte Ressource ab, indem sie den Endpunkt /api/v2/{serviceProvider}/decision/authorize/{mvpd} aufruft.

• Die Streaming-Anwendung ist nicht erforderlich, um Autorisierungsentscheidungen in einem persistenten Speicher zu speichern.

• Die Streaming-Anwendung kann den Grund für eine Entscheidung über die verweigerte Autorisierung ermitteln, indem sie den Fehlercode und die Nachricht überprüft, die in der Antwort des Endpunkts Decisions Authorize enthalten sind. Diese Details bieten Einblicke in den spezifischen Grund, aus dem die Autorisierungsanfrage abgelehnt wurde, und helfen, das Benutzererlebnis oder den Trigger über die erforderliche Handhabung in der Anwendung zu informieren. Stellen Sie sicher, dass ein zum Abrufen von Autorisierungsentscheidungen implementierter Wiederholungsmechanismus nicht zu einer Endlosschleife führt, wenn die Autorisierungsentscheidung abgelehnt wird. Erwägen Sie, weitere Zustellversuche auf eine angemessene Anzahl zu beschränken und Ablehnungen elegant zu handhaben, indem Sie dem Benutzer klares Feedback senden.

• Die Streaming-Anwendung ist nicht erforderlich, um ein abgelaufenes Medien-Token zu aktualisieren, während der Stream aktiv wiedergegeben wird. Wenn das Medien-Token während der Wiedergabe abläuft, sollte der Stream ununterbrochen fortgesetzt werden können. Der Client muss jedoch beim nächsten Versuch, eine Ressource abzuspielen, eine neue Autorisierungsentscheidung anfordern und ein neues Medien-Token abrufen.

• Aufgrund von Bedingungen, die von MVPDs auferlegt werden, kann die Streaming-Anwendung in einer einzelnen API-Anfrage, normalerweise bis zu 1, eine Autorisierungsentscheidung für eine begrenzte Anzahl von Ressourcen erhalten.

Adobe Pass-Abmeldung initiieren: Die Streaming-Anwendung initiiert den Abmeldefluss, indem sie den Endpunkt /api/v2/{serviceProvider}/logout/{mvpd} aufruft.

• Die Streaming-Anwendung muss den Anweisungen in den actionName und actionType Attributen der Antwort des Abmeldeendpunkts folgen, um sicherzustellen, dass der Abmeldevorgang korrekt abgeschlossen wird.

  • Wenn das actionType Attribut in der Antwort auf „interaktiv“ festgelegt ist:

    • Szenario 1: Die Streaming-Anwendung kann einen Browser oder eine Webansicht öffnen, daher muss sie die Abmelde-url laden.

    • Szenario 2: Die Streaming-Anwendung kann keinen Browser öffnen. Daher kann der Abmeldevorgang angehalten werden, da die MVPD-Sitzung nicht in einem Browser-Cache für Streaming-Geräte beibehalten wurde.