Chat-App mit anderen Diensten und Tools verbinden

Anwendungen sind zwar leistungsstark, arbeiten aber häufig zusammen mit anderen Systemen und erfordern, dass Companion-Anwendungen Konten verbinden, Datenzugriff autorisieren, zusätzliche Daten anzeigen oder Nutzereinstellungen konfigurieren.

Anwendungskonfiguration anfordern

Zusätzlich zur Darstellung von URLs als Teil einer normalen Antwort kann in Apps in Reaktion auf eine Nachricht auch eine Konfigurations-URL für Nutzer bereitgestellt werden.

Konfigurations-URL zurückgeben

Wenn für eine Anfrage eine zusätzliche Konfiguration erforderlich ist, die nicht direkt in der Anwendung abgeschlossen werden kann, geben Sie eine Antwort im folgenden Format zurück:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "<your-config-URL>"
  }
}

Dadurch wird Google Chat angewiesen, dem Nutzer eine private Aufforderung zu senden, über einen Link zur bereitgestellten Konfigurations-URL für die Authentifizierung, Autorisierung oder Konfiguration. Eine Anfrage-Konfigurationsantwort schließt sich mit einer regulären Antwortnachricht gegenseitig aus. Texte, Karten oder andere Attribute werden ignoriert.

App, die den Nutzer dazu auffordert, eine Konfigurations-URL anzugeben.

Jedes Ereignis in Ihrer App enthält außerdem einen configCompleteRedirectUrl-Parameter. Diese URL sollte in der Konfigurations-URL codiert sein, die nach Abschluss des Vorgangs verwendet werden soll. Die Weiterleitung zu dieser URL signalisiert Google Chat, dass die Konfigurationsanfrage erfüllt wurde.

Wenn Ihre App startet, kann der Ablauf von der spezifischen empfangenen Nachricht abhängen. Bei einer Nachricht wie @app help sollte eine Anwendung mit einer Nachricht ohne zusätzliche Konfiguration antworten.

Wenn ein Nutzer erfolgreich zur configCompleteRedirectUrl weitergeleitet wird, die in der ursprünglichen Nachricht angegeben ist, führt Google Chat die folgenden Schritte aus:

  1. Aufforderung, die dem Nutzer angezeigt wurde, löschen
  2. Konvertieren Sie die ursprüngliche Nachricht in öffentlich, sodass sie für andere Mitglieder des Gruppenbereichs sichtbar ist
  3. Senden Sie die ursprüngliche Nachricht ein zweites Mal an dieselbe App

Ein Besuch von configCompleteRedirectUrl wirkt sich nur auf eine einzelne Nutzernachricht aus. Wenn ein Nutzer mehrmals versucht hat, einer Anwendung eine Nachricht zu senden, und daher mehrere Aufforderungen erhalten haben, wirkt sich das Klicken auf eine bestimmte Anfrage und das Ausführen des Authentifizierungs-/Konfigurationsprozesses nur auf diese bestimmte Nachricht / Aufforderung aus. Andere Nachrichten und Aufforderungen bleiben unverändert.

Wenn ein Ereignis auf diese Weise neu weitergeleitet wird, sollte es in der Regel mit dem ursprünglichen Ereignis identisch sein. Es gibt jedoch Situationen, in denen sich die Ereignisse unterscheiden können. Wenn in einer Nachricht beispielsweise App A und App B erwähnt werden, kann der Nutzer den Nachrichtentext bearbeiten, wenn Anwendung A vor der Authentifizierung bei Anwendung B mit einer normalen Nachricht antwortet. In diesem Fall erhält App B den bearbeiteten Nachrichtentext, nachdem der Nutzer die Authentifizierung abgeschlossen hat.

Nutzer in App-Nachrichten identifizieren

Jede an Ihre Anwendung gesendete Nachricht enthält die Identität des Nutzers, der mit der Anwendung interagiert.

Das folgende JSON-Fragmentbeispiel zeigt das erwartete Format der Nutzeridentität in einer Nachricht an Ihre Anwendung.

{
  ...,
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Sasha",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "sasha@example.com"
  }
}

Verwende den Wert der users.name-Property als primäre ID für den Nutzer. Der Wert ist eine stabile und eindeutige ID für jeden Nutzer.

Google Chat-Nutzer außerhalb von Google Chat identifizieren

In einigen Fällen, z. B. beim Anfordern der OAuth-Autorisierung für eine API, muss Ihre App auf eine URL außerhalb von Google Chat verweisen und gleichzeitig die Nutzeridentität beibehalten. In diesen Fällen identifizieren Sie den Nutzer am besten, indem Sie die Zielanwendung mit Google Log-in schützen.

Verwenden Sie das Identitätstoken, das bei der Anmeldung ausgestellt wird, um die User-ID abzurufen. Die sub-Anforderung enthält die eindeutige ID des Nutzers und kann mit der ID aus Google Chat korreliert werden.

Die beiden IDs sind zwar nicht identisch, können aber leicht erzwungen werden. Um den Wert der sub-Anforderung auf einen Google Chat-Nutzernamen zu erzwingen, stellen Sie dem Wert "users/" voran. Der Anspruchswert 123 entspricht beispielsweise dem Nutzernamen users/123 in Nachrichten an Ihre Chat-App.

Vollständiges Beispiel

Die MyProfile App zeigt, wie Sie mit der Antwort REQUEST_CONFIG die Anwendungskonfiguration initiieren und das Identitätstoken aus der Google Log-in-Antwort verwenden, um den Nutzer zu identifizieren.