Berechtigungen

Du kannst Berechtigungen in deiner Aktion verwenden, um personenbezogene Daten vom Nutzer anzufordern, um eine Anfrage auszuführen. Eine Lebensmittellieferaktion kann beispielsweise eine Berechtigung zur Standortermittlung auf einem Gerät verwenden, um Informationen zum Standort des Nutzers anzufordern.

Wenn du deiner Aktion eine Berechtigung hinzufügst, zeigt Assistant eine standardmäßige, einheitliche Oberfläche an, über die der Nutzer die Berechtigung zur Bereitstellung der Informationen für deine Aktion anfordern kann.

Verfügbare Berechtigungen

Folgende Berechtigungen können von deiner Aktion angefordert werden:

  • DEVICE_PRECISE_LOCATION: Fordert den genauen Gerätestandort des Nutzers an (Koordinaten und Adresse).
  • DEVICE_COARSE_LOCATION: Fragt den ungefähren Gerätestandort des Nutzers an (Postleitzahl und Stadt).

Berechtigungen einrichten

Wenn du Berechtigungen für deine Aktion einrichten möchtest, fügst du der Szene einen neuen Slottyp hinzu. Anschließend konfigurieren Sie den Slot für die Datenberechtigung, die Sie anfordern möchten.

Berechtigungsslottyp hinzufügen

Mit dem Slottyp actions.type.Permission können Sie Ihrer Aktion die Möglichkeit geben, Nutzerinformationen abzurufen.

So konfigurieren Sie diesen Slottyp:

  1. Rufen Sie die Actions Console auf und wählen Sie ein Projekt aus oder erstellen Sie eines.
  2. Klicken Sie im Hauptmenü auf Entwickeln.
  3. Klicken Sie unter Szenen auf die Szene, der Sie den Berechtigungsablauf hinzufügen möchten.
  4. Klicken Sie im Bereich Slot-Füllung der Szene auf +, um eine neue Anzeigenfläche hinzuzufügen.

  5. Wählen Sie im Drop-down-Menü Typ auswählen den Slottyp actions.type.Permission aus.

  6. Geben Sie im Feld Name der Anzeigenfläche eingeben einen Namen ein.

  7. Aktivieren Sie Benutzerdefiniertes Slotwert-Rückschreiben, um das Ergebnis in einen Sitzungsparameter zu schreiben.

Slot konfigurieren

Sie können jetzt einen Kontextstring und eine Liste der Berechtigungen angeben, die zum Konfigurieren des Slots gewährt werden sollen. Der Kontextstring ist der Grund dafür, warum du Informationen vom Nutzer anforderst, und wird Nutzern angezeigt, wenn sie aufgefordert werden, deiner Aktion die Berechtigung zu erteilen.

Sie können den Kontextstring und die Berechtigungen im Abschnitt Slot konfigurieren konfigurieren, wie im folgenden Screenshot dargestellt:

Das folgende Code-Snippet zeigt ein Beispiel für eine Slotkonfiguration:

{
  "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValueSpec",
  "context": "Context string",
  "permissions": ["DEVICE_PRECISE_LOCATION"]
}

Die Eingabeaufforderung, die Nutzern angezeigt wird, hat die Form "$context_string, I'll need just need to get your current location from Google. Ist das in Ordnung?“

Mithilfe der Berechtigungscodes können Sie die folgenden Nutzerinformationen abrufen:

Berechtigung Beschreibung
DEVICE_PRECISE_LOCATION Genauer Gerätestandort (Koordinaten und Adresse)
DEVICE_COARSE_LOCATION Ungefährer Gerätestandort (Postleitzahl und Stadt)

Ergebnis der Berechtigung abrufen

In den folgenden Abschnitten wird beschrieben, wie Sie den Berechtigungsstatus prüfen und die Informationen des Nutzers lesen, wenn er eine Berechtigung erteilt.

Berechtigungsstatus prüfen

Wenn der Nutzer die Berechtigung erteilt, wird der resultierende Status in den Sitzungsparameter geschrieben, der mit dem Slot verknüpft ist.

Sie können den Berechtigungsstatus prüfen, indem Sie den Wert von session.params.<slot_name>.permissionStatus in der Bedingung einer Szene prüfen.

So prüfen Sie den Status des Berechtigungsslots:

  1. Rufen Sie die Actions Console auf und klicken Sie im Hauptmenü auf Entwickeln.
  2. Klicken Sie unter Szenen auf die Szene, die die Berechtigung enthält.
  3. Klicken Sie im Abschnitt Bedingung der Szene auf +, um eine neue Bedingung hinzuzufügen.

  4. Geben Sie die folgende Bedingung ein, um den Berechtigungsstatus zu prüfen (wobei <slot_name> der Name des Sitzungsparameters ist, den Sie in Ihrem Slot konfiguriert haben):

    scene.slots.status == "FINAL" && (session.params.<slot_name>.permissionStatus == "PERMISSION_GRANTED" || session.params.<slot_name>.permissionStatus == "ALREADY_GRANTED")

  5. Klicken Sie im Abschnitt Bedingung der Szene auf +, um eine neue Bedingung hinzuzufügen.

  6. Geben Sie die folgende Bedingung für den Fall ein, dass der Nutzer der Weitergabe seiner Daten nicht zustimmt:

    scene.slots.status == "FINAL"

  7. Klicken Sie im Abschnitt Bedingung der Szene auf +, um eine neue Bedingung hinzuzufügen.

  8. Geben Sie die folgende Bedingung ein, wenn der Nutzer die Berechtigung bereits erteilt hat und nicht noch einmal gefragt werden muss:

    "DEVICE_PRECISE_LOCATION" in user.permissions

Nutzerinformationen lesen

Wenn der Nutzer die entsprechende Berechtigung erteilt, werden die Nutzerdaten in nachfolgenden Anfragen bereitgestellt.

Im folgenden Snippet sehen Sie Informationen zum Gerätestandort, die in einer Anfrage an den Webhook unter device.currentLocation enthalten sind:

Anfrage (JSON) 
  {
      "handler": {
        "name": "handler"
      },
      "intent": {
        "name": "",
        "params": {
          "deviceLoc": {
            "original": "",
            "resolved": {
              "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue",
              "permissionStatus": "PERMISSION_GRANTED",
              "grantedPermissions": [
                "DEVICE_PRECISE_LOCATION"
              ]
            }
          }
        },
        "query": "Yes"
      },
      "scene": {
        "name": "Scene",
        "slotFillingStatus": "FINAL",
        "slots": {
          "deviceLoc": {
            "mode": "REQUIRED",
            "status": "SLOT_UNSPECIFIED",
            "value": {
              "grantedPermissions": [
                "DEVICE_PRECISE_LOCATION"
              ],
              "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue",
              "permissionStatus": "PERMISSION_GRANTED"
            },
            "updated": true
          }
        },
        "next": {
          "name": "actions.scene.END_CONVERSATION"
        }
      },
      "session": {
        "id": "session_id",
        "params": {
          "deviceLoc": {
            "grantedPermissions": [
              "DEVICE_PRECISE_LOCATION"
            ],
            "permissionStatus": "PERMISSION_GRANTED",
            "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue"
          }
        },
        "typeOverrides": [],
        "languageCode": ""
      },
      "user": {
        "locale": "en-US",
        "params": {},
        "accountLinkingStatus": "ACCOUNT_LINKING_STATUS_UNSPECIFIED",
        "verificationStatus": "VERIFIED",
        "packageEntitlements": [],
        "permissions": [
          "DEVICE_PRECISE_LOCATION"
        ],
        "lastSeenTime": "2021-02-08T20:43:47Z"
      },
      "home": {
        "params": {}
      },
      "device": {
        "capabilities": [
          "SPEECH",
          "RICH_RESPONSE",
          "LONG_FORM_AUDIO"
        ],
        "currentLocation": {
          "coordinates": {
            "latitude": 37.422,
            "longitude": -122.084
          },
          "postalAddress": {
            "revision": 0,
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94043",
            "sortingCode": "",
            "administrativeArea": "California",
            "locality": "Mountain View",
            "sublocality": "",
            "addressLines": ["1600 Amphitheatre Parkway"],
            "recipients": [],
            "organization": ""
          }
        }
      }
    }

Weitere Informationen zum Schema des Standorttyps finden Sie in der Referenz zu Location.

Sie können über Ihren Webhook auf die Informationen in der Anfrage zugreifen, wie im folgenden Snippet gezeigt:

Webhook 
  app.handle('handler', (conv) => {
    let location = conv.device.currentLocation;
    conv.add(`Your postal code is ${location.postalCode}`);
  });

Berechtigung in Prompts verwenden

Sie können die Berechtigung auch in statischen Prompts referenzieren. Für den Gerätestandort können Sie beispielsweise $device.currentLocation.coordinates.* und $device.currentLocation.postalAddress.* verwenden. Das folgende Code-Snippet zeigt, wie in einer Eingabeaufforderung auf die Stadt des Nutzers verwiesen wird:

candidates:
  - first_simple:
      variants:
        - speech: >-
            There are no events scheduled tomorrow in the city of $device.currentLocation.postalAddress.locality.