权限

您可以在 Action 中使用权限来请求用户提供个人数据以完成请求。例如,送餐 Action 可以使用设备位置信息权限来请求有关用户位置信息的信息。

当您向 Action 添加权限时,Google 助理会提供一个标准一致的界面,用于向用户请求权限,以便为您的 Action 提供信息。

可用权限

您的 Action 可以请求以下权限:

  • DEVICE_PRECISE_LOCATION:请求用户的确切设备位置(坐标和街道地址)。
  • DEVICE_COARSE_LOCATION:请求用户的粗略设备位置信息(邮政编码和城市)。

设置权限

如需为您的 Action 设置权限,您可以向场景添加新的槽类型。然后,您可以为要请求的数据权限配置槽。

添加权限槽类型

您可以使用 actions.type.Permission 槽类型向 Action 授予获取用户信息的权限。

如需配置此槽类型,请按以下步骤操作:

  1. 转到 Actions 控制台,然后选择或创建一个项目。
  2. 点击顶部菜单中的 Develop
  3. Scenes 下,点击您要添加权限流的场景。
  4. 在场景的槽填充部分下,点击 + 以添加新槽。
  5. Select type 下拉列表中,选择 actions.type.Permission 槽类型。

  6. Enter slot name 字段中,为槽命名。

  7. 启用自定义广告位值回写以将结果写入会话参数。

配置槽位

现在,您可以提供上下文字符串以及为了配置槽位而需授予的权限的列表。上下文字符串用于说明您向用户请求信息的原因,当要求用户向您的 Action 授予权限时,系统会向用户显示该上下文字符串。

您可以在配置槽位部分配置上下文字符串和权限,如以下屏幕截图所示:

以下代码段显示了一个槽配置示例:

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

向用户显示的提示将采用 "$context_string, I'm need to get your current location from Google. 可以吗?”

您可以使用权限代码获取以下用户信息:

权限 说明
DEVICE_PRECISE_LOCATION 设备的确切位置(坐标和街道地址)
DEVICE_COARSE_LOCATION 粗略的设备位置信息(邮政编码和城市)

获取权限结果

下面几部分将介绍如何查看权限状态,以及在用户授予权限时如何读取用户的信息。

查看权限状态

当用户授予权限时,生成的状态会写入与槽关联的会话参数。

您可以通过在场景条件中检查 session.params.<slot_name>.permissionStatus 的值来检查权限状态。

如需查看权限槽的状态,请按以下步骤操作:

  1. 前往 Actions 控制台,然后点击顶部菜单中的 Develop
  2. Scenes 下,点击包含权限槽的场景。
  3. 在场景的 Condition 部分下,点击 + 以添加新条件。
  4. 输入以下条件以检查权限状态(其中 <slot_name> 是您在相应槽位中配置的会话参数的名称):

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

  5. 在场景的 Condition 部分下,点击 + 以添加新条件。

  6. 输入以下条件来处理用户不同意共享其信息的情况:

    scene.slots.status == "FINAL"
    

  7. 在场景的 Condition 部分下,点击 + 以添加新条件。

  8. 输入以下条件,以处理用户已授予权限且无需再次询问的情况:

    "DEVICE_PRECISE_LOCATION" in user.permissions
    

读取用户信息

如果用户授予权限,则后续请求中会提供相应的用户信息。

在以下代码段中,您可以在 device.currentLocation 下看到对 webhook 的请求中包含的设备位置信息:

请求 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": ""
          }
        }
      }
    }
    

如需详细了解位置类型的架构,请参阅 Location 参考文档

您可以从 webhook 访问请求中包含的信息,如以下代码段所示:

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

在提示中使用权限

您还可以在静态提示中引用权限。例如,对于设备位置,您可以使用 $device.currentLocation.coordinates.*$device.currentLocation.postalAddress.*。以下代码段展示了如何在提示中引用用户所在的城市:

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