Link zu Ihren Aktionen (Dialogflow)

Du kannst für jede Aktion eine URL generieren, die direkt auf die spezifische Aktion verweist. Nutzer, die in einem Webbrowser oder in einem mobilen Browser auf den Assistant-Link klicken (früher „Aktionslink“ genannt), werden auf ihrem Gerät zu Assistant weitergeleitet und können dort direkt mit der entsprechenden Aktion interagieren.

Beispiele für nützliche Assistant-Links:

  • Nutzer mit sprachgestützten Anleitungen auf einer Anleitungswebsite verknüpfen
  • Nutzer über „Hilfe“ mit dem Kundensupport verknüpfen Seite.
  • Verknüpfen Sie Nutzer mit einem Update-Intent, damit sie Ihre zukünftigen Updates aktivieren können.

So generierst du eine URL für eine Aktion:

  1. Gehen Sie in der Actions Console zu Entwickeln > Aktionen:
  2. Klicken Sie auf die Aktion, für die Sie einen Link erstellen möchten.
  3. Aktivieren Sie im Abschnitt Links die Option Möchten Sie eine URL für diese Aktion aktivieren.
  4. Geben Sie einen Linktitel ein. Dieser Titel sollte ein Verb enthalten, das beschreibt, was die Aktion bewirkt. Wenn deine Aktion beispielsweise den Nutzer zu einem Transaktionsvorgang zum Kauf von Tickets für ein Konzert führt, wäre "Konzerttickets kaufen" ein nützlicher Linktitel.
  5. Klicken Sie auf Speichern.

Du kannst die angegebene URL kopieren und überall dort darauf verweisen, wo Nutzer zu dieser Aktion weitergeleitet werden sollen.

Assistant-Links können in der URL optional einen Intent und Parameter enthalten. Google verarbeitet die Parameter entsprechend dem in der URL angegebenen Intent-Typ.

Die allgemeine Syntax für die URL eines Assistant-Links lautet wie folgt:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$param=$value][&$utm_param=$utm_value]

Die URL-Parameter, die Sie festlegen können, sind in der folgenden Tabelle beschrieben:

URL-Parameter Beschreibung
$action_id Numerische Kennung der Aktion.
$intent Vollständiger Name eines integrierten oder benutzerdefinierten Intents.
$param Vollständiger Name eines Intent-Parameters, der im Aktionspaket angegeben ist.
$value URL-codierter Wert des Typs, der für $param im Aktionspaket
$utm_param Liste mit mindestens einem UTM-Parametertyp. Gültige Werte sind: utm_source, utm_medium, utm_campaign, utm_term und utm_content
$utm_value Stringwert des UTM-Parameters.

Enthält der Assistant-Link eine integrierten Intent (der Intent beginnt mit actions.intent.*) verwendet wird, versucht Google, alle integrierten Intent-Parameter in der URL zu extrahieren und an deine Aktion zu übergeben. Parameter, die Google nicht als integrierte Intent-Parameter einstuft, werden entfernt.

Bei dialogorientierten Aktionen sendet Google diese Parameter als Teil der AppRequest-Nachricht an Ihre Auftragsausführung.

Das folgende Beispiel zeigt, wie Sie eine Assistant-Link-URL angeben können, die einen integrierten Intent mit einem einzelnen Intent-Parameter enthält:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.GET_HOROSCOPE&param.astrologySign=%22cancer%22

Bei benutzerdefinierten Intents extrahiert Google nur die Parameter, die von Ihrer Aktion als Teil des Intents definiert werden, und verwirft alle anderen Parameter.

Das folgende Beispiel zeigt, wie Sie eine Assistant-Link-URL angeben können, die einen benutzerdefinierten Intent enthält:

https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK&param.topic=sports

Für die obige Beispiel-URL fügt Google im AppRequest ein JSON-Objekt als folgt:

argument {
  name: ‘topic’,
  raw_text: ‘sports’,
  text_value: ‘sports’,
}

Wenn du im Assistant-Link keinen Intent angibst, verknüpft Google standardmäßig den MAIN-Intent (actions.intent.MAIN) deiner Aktion mit dem folgenden Verhalten:

  • Wenn Sie den Intent MAIN im Assistant-Link nicht explizit aktiviert haben, löst Google den Haupt-Intent ohne Parameter aus, ähnlich wie bei „Mit app_name sprechen“.
  • Wenn Sie den Intent MAIN explizit aktiviert haben, übergibt Google die Parameter an Ihre Actions.

Das folgende Beispiel zeigt, wie Sie eine Assistant-Link-URL ohne Intent angeben können:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4

UTM-Parameter sind Strings, die Google an Ihre Aktion sendet, wenn Nutzer auf einen Assistant-Link klicken. Diese können Sie später für Analysen verwenden.

Google sendet die folgenden UTM-Parameter an deine Aktion:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

Das folgende Beispiel zeigt, wie Sie eine Assistant-Link-URL angeben können, die UTM-Parameter enthält:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale

Für die obige Beispiel-URL fügt Google der AppRequest-Nachricht die folgenden Argumente hinzu:

argument {
  name: ‘utm_source’,
  raw_text: ‘Google’,
  text_value: ‘Google’,
}
argument {
  name: ‘utm_medium’,
  raw_text: ‘email’,
  text_value: ‘email’,
}
argument {
  name: ‘utm_campaign’,
  raw_text: ‘holiday sale’,
  text_value: ‘holiday sale’,
}

Sie können Assistant-Links über den Simulator oder ein Gerät auf alle Intents (Haupt- oder benutzerdefinierten Intents, mit oder ohne Parameter) testen.

So testen Sie die Assistant-Verknüpfung:

  1. Assistant-Link in der Konsole aktivieren
  2. Melden Sie sich in Assistant mit demselben Konto an, mit dem Sie Ihr Actions on Google-Projekt erstellt haben.
  3. Erstellen Sie eine anklickbare Version Ihres Assistant-Links (in E-Mails, Chats, Dokumenten usw.).
  4. Klicken Sie auf einem Gerät mit integriertem Assistant auf den Link, den Sie im vorherigen Schritt erstellt haben.

Nachdem du bestätigt hast, dass der Assistant-Link wie erwartet funktioniert, musst du deine Aktion noch einmal bereitstellen, um den Link für deine Nutzer verfügbar zu machen.

Einschränkungen und Best Practices

Da Ihre Assistant-Link-URL jetzt außerhalb des Verzeichnisses oder anderer Google-Dienste verteilt und referenziert werden kann, gelten die folgenden Einschränkungen und Best Practices:

  • Achte darauf, dass du weiterhin alle deine Assistant-Links unterstützt. Wenn Sie einen Assistant-Link verteilen, der später nicht mehr funktioniert, wird Ihr Actions-Projekt möglicherweise als fehlerhaft gemeldet und entfernt.

  • Wenn Sie einen Link veröffentlichen, wird das Auslösen von Links durch nicht vertrauenswürdige Quellen unterstützt. Bevor du eine Aktion in der realen Welt führst, musst du dich bei allen verknüpften Aktionen ausdrücklich mit dem Nutzer bestätigen lassen. Beispielsweise sollte eine Aktion, die ein Smart-Home-Gerät ausschalten soll, den Nutzer fragen: „Bist du sicher, dass du $applianceName ausschalten möchtest?“

    In diesem Zusammenhang ist es ist eine Aktion, die sich auf die Dienste, Daten, Geräte, Netzwerke, Computer oder APIs des Nutzers auswirkt. Dazu gehören beispielsweise das Senden einer E-Mail, das Ausführen einer Transaktion, das Ändern des Status einer Smart-Home-Appliance, das Erstellen eines Abos oder das Aktualisieren eines Inhalts.