Assistant-Links

Du kannst eine URL generieren, die direkt mit einem bestimmten Intent deiner Aktion verknüpft ist. Nutzer, die in einem Webbrowser oder mobilen Browser auf einen Assistant-Link (früher als Aktionslinks bezeichnet) klicken, werden auf ihrem Gerät zu Assistant weitergeleitet. Dort interagiert sie direkt mit deiner Aktion.

Assistant-Links unterscheiden sich von Verzeichnis-Weblinks, über die ein Nutzer zur Seite deiner Aktion im Assistant-Verzeichnis weitergeleitet wird.

Hier sind einige Situationen, in denen Assistant-Links nützlich sein können:

  • Verknüpfung von Nutzern mit sprachgestützten Anleitungen von einer Website mit Anleitungen
  • Nutzer über eine Hilfeseite mit einem Kundensupport verknüpfen.
  • Verknüpfen Sie Nutzer mit einem Update-Intent, damit sie zukünftige Updates aktivieren können.

Sie können Assistant-Links innerhalb Ihres Projekts in der Actions Console generieren. Assistant-Links sind in allen Bereitstellungskanälen (Alpha, Beta und Produktion) verfügbar. Wenn dein Assistant-Link beispielsweise in der Alphaversion deiner Aktion aktiviert ist, ist der Link für Alphatester verfügbar.

So generierst du eine URL für eine Aktion:

  1. Gehen Sie in der Actions Console zu Bereitstellen > Assistant-Links.
  2. Wählen Sie als Intent den Intent aus, für den Sie einen Link generieren möchten.
  3. Aktivieren Sie die Option Möchten Sie die Verknüpfung für intent_name aktivieren?.
  4. Optional: Geben Sie im Bereich Kampagnenparameter alle Informationen ein, die zusätzlich im Link als URL-Parameter erfasst werden sollen.
  5. Optional: Geben Sie einen Linktitel ein. Beschreiben Sie mit diesem Titel, was die Aktion bewirkt. Wenn deine Aktion den Nutzer beispielsweise durch einen Transaktionsvorgang zum Kauf von Tickets für ein Konzert führt, könnte der Linktitel "Konzertkarten kaufen" lauten.

Nachdem Sie Ihre Informationen eingegeben haben, können Sie die generierte URL oder das generierte Code-Snippet für den Assistant-Link aufrufen und kopieren. Verwende den Assistant-Link, um Nutzer zu dieser Aktion weiterzuleiten.

Sie können Assistant-Links für jeden Intent (Haupt- oder benutzerdefiniert mit oder ohne Parameter) über den Simulator oder auf einem Gerät testen.

So testen Sie Assistant-Link auf einem Gerät:

  1. Generieren Sie den Assistant-Link in der Actions Console.
  2. Senden Sie den Assistant-Link als URL per E-Mail, Chatnachricht oder in einem anderen Format an sich selbst.
  3. Melden Sie sich auf einem Gerät mit integriertem Assistant mit demselben Konto in Assistant an, mit dem Sie Ihr Actions-Projekt erstellt haben.
  4. Klicken Sie auf demselben Gerät auf den Assistant-Link, den Sie an sich selbst gesendet 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.

Assistant-Links können optional einen Intent und Parameter in der URL enthalten. Im Bereich Kampagnenparameter können Sie Kampagnenparameter hinzufügen.

Wenn ein Assistant-Link keine zusätzlichen Parameter enthält, verknüpft Google Assistant den Intent MAIN (actions.intent.MAIN) deiner Aktion mit folgendem Verhalten:

  • Wenn Sie den Intent MAIN im Assistant-Link nicht explizit aktiviert haben, ordnet Assistant den Haupt-Intent ohne Parameter zu, ähnlich wie bei „Mit app_name sprechen“.
  • Wenn Sie den Intent MAIN explizit aktiviert haben, übergibt Assistant die Parameter an Ihre Aktionen.

Hier ist ein Beispiel für eine Assistant-Link-URL mit dem Intent MAIN ohne zusätzliche Parameter:

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

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

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, werden in der folgenden Tabelle beschrieben:

URL-Parameter Beschreibung
$action_id Numerische Kennung der Aktion.
$intent Vollständiger Name eines integrierten oder Nutzer-Intents.
$param Vollständiger Name eines Intent-Parameters, der im Aktionspaket angegeben ist.
$value URL-codierter Wert des Typs, der im Aktionspaket für $param deklariert wurde.
$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.

Wenn der Assistant-Link einen integrierten Intent enthält (der Intent beginnt mit actions.intent.), versucht Google Assistant, alle integrierten Intent-Parameter aus der URL zu extrahieren und an Ihre Aktion zu übergeben. Alle Parameter, die Assistant nicht als integrierte Intent-Parameter versteht, werden entfernt.

Bei Konversationsaktionen sendet Assistant diese Parameter als Teil der AppRequest-Nachricht an die 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.PLAY_GAME&param.name=%22ExampleGame%22

Bei Nutzer-Intents extrahiert Google Assistant nur die Parameter, die von deiner Aktion als Teil des Intents definiert wurden, und verwirft alle anderen Parameter.

Das folgende Beispiel zeigt, wie Sie eine Assistant-Link-URL angeben können, die einen Nutzer-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 Assistant in der Datei AppRequest so ein JSON-Objekt hinzu:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

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

Die UTM-Parameter, die Assistant an deine Aktion sendet, umfassen Folgendes:

  • 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 Assistant 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',
}

Mithilfe von Rich Assistant-Links kannst du mithilfe von assist.js die Auffindbarkeit deiner Aktion über deine Website erhöhen. Nutzer können deine Aktion ausprobieren und ihr Google-Konto über die Kontoverknüpfung mit deinem Dienst verknüpfen.

Wenn ein Nutzer deine Website besucht, sieht er die Schaltfläche „Mit Google Assistant testen“, wodurch der Rich Assistant-Linkvorgang ausgelöst wird.

Wenn du die Kontoverknüpfung für deine Aktion aktivierst, können Nutzer über alle ihre Geräte mit integriertem Assistant auf deine Aktion zugreifen. Außerdem können Nutzer ihr Konto mit Ihrem Dienst mit ihrem Google-Konto verknüpfen, um die Nutzung zu personalisieren.

Bei der Kontoverknüpfung wird für Rich Assistant-Links die Autorisierungs-URL verwendet, die in der Actions Console für Ihr Projekt festgelegt ist. Weitere Informationen finden Sie in der Dokumentation zur Kontoverknüpfung.

Voraussetzungen

Wenn Sie Rich Assistant-Links verwenden möchten, benötigen Sie Folgendes:

Lokale Entwicklung

So fügen Sie Ihrer Website einen Rich Assistant-Link hinzu:

  1. Füge die folgende JavaScript-Bibliothek in deine Seite ein. Ersetzen Sie dabei <PROJECT_ID> durch die ID Ihres Actions-Projekts:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
    </script>
    
  2. Fügen Sie das folgende HTML-Tag irgendwo auf Ihrer Seite ein. Dadurch wird die Inline-Schaltfläche „Try it with Google Assistant“ (Mit Google Assistant testen) geladen:

    <google-assistant-link-group>
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    

Proaktives Auslösen

Wenn der Rich Assistant-Linkfluss automatisch gestartet werden soll, wenn Nutzer deine Seite zum ersten Mal besuchen, verwende das Tag <google-assistant-proactive-link>. Wenn Sie dieses Tag anwenden, wird der Link bei ihrem ersten Besuch ohne Nutzer aktiviert, ohne dass diese die Inline-Schaltfläche auswählen müssen.

  1. Fügen Sie Ihrem Gruppen-Tag für Assistant-Verknüpfungen ein id hinzu:

    <google-assistant-link-group id="my-group">
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    
  2. Platzieren Sie ein <google-assistant-proactive-action-link>-Tag auf Ihrer Webseite und legen Sie das groupId-Attribut auf id fest:

    <google-assistant-link-group id="my-group">
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    
    <google-assistant-proactive-link
    groupId="my-group">
    </google-assistant-proactive-link>
    

Bereitstellung

Rich Assistant-Links funktionieren nur für Domains, die Ihnen gehören und die Sie von Google bestätigt haben. Bei der lokalen Entwicklung ist diese Anforderung umgangen. Sie müssen Zugriff auf das Actions-Projekt haben, in Ihrem Google-Konto angemeldet sein und den Abfrageparameter dev=true im Skript-Tag festlegen.

  <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
  </script>

So stellst du deine Aktion mit den Rich Assistant-Links bereit:

  1. Registrieren Sie Ihre urheberrechtsfreie Domain in der Actions Console unter Bereitstellen > Markenüberprüfung > Website verbinden.
  2. Entfernen Sie den dev=true-Abfrageparameter aus dem Skript:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}">
    </script>
    

Einschränkungen und Best Practices

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

  • Alle Assistant-Links werden weiterhin 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.
  • Durch das Veröffentlichen eines Links wird das Auslösen von nicht vertrauenswürdigen Quellen unterstützt. Für verknüpfte Aktionen musst du den Nutzer explizit bestätigen, bevor du eine reale Aktion ausführen kannst. Beispiel: Eine Aktion, die eine Smart-Home-Appliance ausschaltet, sollte den Nutzer fragen: "Möchten Sie $applianceName wirklich ausschalten?"

    In diesem Kontext ist eine reale Aktion eine Aktion, die sich auf die Dienste, Daten, Geräte, Netzwerke, Computer oder APIs des Nutzers auswirkt. Beispiele: Senden einer E-Mail, Ausführen einer Transaktion, Ändern des Status einer Smart-Home-Appliance, Erstellen eines Abos oder Aktualisieren von Inhalten.