Quyền

Bạn có thể sử dụng quyền trong Hành động của mình để yêu cầu dữ liệu cá nhân từ người dùng cho mục đích hoàn tất một yêu cầu. Ví dụ: Hành động giao đồ ăn có thể sử dụng quyền truy cập thông tin vị trí của thiết bị để yêu cầu thông tin về địa điểm của người dùng.

Khi bạn thêm một quyền vào Hành động của mình, Trợ lý sẽ hiển thị một giao diện chuẩn và nhất quán để yêu cầu người dùng cấp quyền nhằm cung cấp thông tin cho Hành động của bạn.

Các quyền hiện có

Hành động của bạn có thể yêu cầu các quyền sau đây:

  • DEVICE_PRECISE_LOCATION: Yêu cầu vị trí chính xác của thiết bị của người dùng (tọa độ và địa chỉ đường phố).
  • DEVICE_COARSE_LOCATION: Yêu cầu thông tin vị trí thô của thiết bị của người dùng (mã bưu chính và thành phố).

Thiết lập quyền

Để thiết lập quyền cho Hành động của mình, bạn cần thêm một loại vị trí mới vào cảnh. Sau đó, bạn định cấu hình vị trí cho quyền dữ liệu mà bạn muốn yêu cầu.

Thêm loại vùng quyền

Bạn có thể cấp cho Hành động của mình khả năng thu thập thông tin người dùng thông qua loại vùng actions.type.Permission.

Để định cấu hình loại vị trí này, hãy làm theo các bước sau:

  1. Chuyển đến Bảng điều khiển Actions rồi chọn hoặc tạo một dự án.
  2. Nhấp vào Phát triển trong trình đơn trên cùng.
  3. Trong mục Scenes (Cảnh), hãy nhấp vào cảnh mà bạn muốn thêm quy trình cấp quyền.
  4. Trong phần Lấp đầy vị trí của cảnh đó, hãy nhấp vào dấu + để thêm một vị trí mới.

  5. Trong trình đơn thả xuống Chọn loại, hãy chọn loại vùng actions.type.Permission.

  6. Trong trường Nhập tên vùng, đặt tên cho vùng.

  7. Bật tính năng Ghi lại giá trị vị trí tuỳ chỉnh để ghi kết quả vào một thông số phiên.

Định cấu hình vị trí

Giờ đây, bạn có thể cung cấp một chuỗi ngữ cảnh và danh sách các quyền được cấp để định cấu hình khu vực. Chuỗi ngữ cảnh là lý do khiến bạn yêu cầu thông tin từ người dùng và hiển thị với người dùng khi họ được yêu cầu cấp quyền đối với Hành động của bạn.

Bạn có thể định cấu hình chuỗi ngữ cảnh và các quyền trong phần Định cấu hình vị trí, như trong ảnh chụp màn hình sau:

Đoạn mã sau đây cho thấy một cấu hình vị trí mẫu:

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

Lời nhắc mà người dùng nhìn thấy sẽ có dạng "$context_string, tôi chỉ cần lấy thông tin vị trí hiện tại của bạn từ Google. Như vậy có được không?"

Bạn có thể lấy thông tin người dùng sau đây bằng mã quyền:

Quyền Nội dung mô tả
DEVICE_PRECISE_LOCATION Vị trí chính xác của thiết bị (tọa độ và địa chỉ đường phố)
DEVICE_COARSE_LOCATION Vị trí tương đối của thiết bị (mã bưu chính và thành phố)

Yêu cầu kết quả cấp quyền

Các phần sau đây mô tả cách kiểm tra trạng thái quyền và đọc thông tin của người dùng nếu họ cấp quyền.

Kiểm tra trạng thái quyền

Khi người dùng cấp quyền, trạng thái kết quả sẽ được ghi vào thông số phiên liên kết với vị trí đó.

Bạn có thể kiểm tra trạng thái quyền bằng cách kiểm tra giá trị của session.params.<slot_name>.permissionStatus trong điều kiện của một cảnh.

Để kiểm tra trạng thái của khu vực cấp quyền, hãy làm theo các bước sau:

  1. Chuyển đến Bảng điều khiển Actions rồi nhấp vào Phát triển trong trình đơn trên cùng.
  2. Trong Scenes (Cảnh), hãy nhấp vào cảnh có chứa ô cấp quyền.
  3. Trong phần Condition (Điều kiện) của cảnh, hãy nhấp vào + để thêm điều kiện mới.

  4. Nhập điều kiện sau để kiểm tra trạng thái quyền (trong đó <slot_name> là tên của tham số phiên hoạt động bạn đã định cấu hình trong vị trí):

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

  5. Trong phần Condition (Điều kiện) của cảnh, hãy nhấp vào + để thêm điều kiện mới.

  6. Nhập điều kiện sau để xử lý trường hợp người dùng không đồng ý chia sẻ thông tin của họ:

    scene.slots.status == "FINAL"

  7. Trong phần Condition (Điều kiện) của cảnh, hãy nhấp vào + để thêm điều kiện mới.

  8. Nhập điều kiện sau để xử lý trường hợp người dùng đã cấp quyền và không cần hỏi lại:

    "DEVICE_PRECISE_LOCATION" in user.permissions

Đọc thông tin người dùng

Nếu người dùng cấp quyền, thông tin người dùng sẽ được cung cấp trong các yêu cầu tiếp theo.

Trong đoạn mã dưới đây, bạn có thể xem thông tin vị trí thiết bị có trong một yêu cầu đối với webhook trong device.currentLocation:

Yêu cầu tệp 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": ""
          }
        }
      }
    }

Để biết thêm thông tin về giản đồ của loại vị trí, hãy xem tài liệu tham khảo về Location.

Bạn có thể truy cập vào thông tin có trong yêu cầu từ webhook, như hiển thị trong đoạn mã sau:

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

Sử dụng quyền trong câu lệnh

Bạn cũng có thể tham chiếu đến quyền này trong câu lệnh tĩnh. Ví dụ: đối với vị trí của thiết bị, bạn có thể sử dụng $device.currentLocation.coordinates.* và $device.currentLocation.postalAddress.*. Đoạn mã sau đây cho biết cách tham chiếu đến thành phố của người dùng trong một câu lệnh:

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