Permissões

Use as permissões na sua Ação para solicitar dados pessoais do usuário para concluir uma solicitação. Por exemplo, uma ação de entrega de comida pode usar uma permissão de localização do dispositivo para solicitar informações sobre a localização do usuário.

Quando você adiciona uma permissão à ação, o Google Assistente apresenta uma interface padrão consistente para solicitar a permissão do usuário e fornecer as informações.

Permissões disponíveis

As seguintes permissões podem ser solicitadas pela sua Ação:

  • DEVICE_PRECISE_LOCATION: solicita o local exato do dispositivo do usuário (coordenadas e endereço).
  • DEVICE_COARSE_LOCATION: solicita a localização aproximada do dispositivo do usuário (código postal e cidade).

Configurar permissões

Para configurar permissões para sua ação, adicione um novo tipo de slot à cena. Em seguida, configure o slot para a permissão de dados que você quer solicitar.

Adicionar tipo de slot de permissão

Você pode conceder à sua Ação a capacidade de coletar informações do usuário com o tipo de slot actions.type.Permission.

Para configurar esse tipo de slot, siga estas etapas:

  1. Acesse o Console do Actions e selecione ou crie um projeto.
  2. Clique em Desenvolver no menu superior.
  3. Em Cenas, clique na cena a que você quer adicionar o fluxo de permissão.
  4. Na seção Preenchimento de slot da cena, clique em + para adicionar um novo slot.

  5. No menu suspenso Selecionar tipo, escolha o tipo de slot actions.type.Permission.

  6. No campo Inserir nome do slot, insira um nome para o slot.

  7. Ative o writeback do valor do slot personalizado para gravar o resultado em um parâmetro de sessão.

Configurar slot

Agora é possível fornecer uma string de contexto e uma lista de permissões a serem concedidas para configurar o slot. A string de contexto é a justificativa para a solicitação de informações do usuário. Ela é mostrada aos usuários quando é solicitado que concedam permissão à sua Ação.

A string de contexto e as permissões podem ser configuradas na seção Configurar slot, conforme mostrado na captura de tela a seguir:

O snippet de código a seguir mostra um exemplo de configuração de slot:

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

A solicitação exibida aos usuários vai estar no formato de "$context_string, basta verificar sua localização atual com o Google. Tudo bem?"

Você pode conseguir as seguintes informações do usuário usando os códigos de permissão:

Permissão Descrição
DEVICE_PRECISE_LOCATION Local exato do dispositivo (coordenadas e endereço)
DEVICE_COARSE_LOCATION Localização aproximada do dispositivo (código postal e cidade)

Acessar resultado da permissão

As seções a seguir descrevem como verificar o status da permissão e ler as informações do usuário se ele a conceder.

Verificar o status da permissão

Quando o usuário concede a permissão, o status resultante é gravado no parâmetro de sessão associado ao slot.

Você pode conferir o status da permissão conferindo o valor de session.params.<slot_name>.permissionStatus na condição de uma cena.

Para verificar o status do slot de permissão, siga estas etapas:

  1. Acesse o Console do Actions e clique em Desenvolver no menu superior.
  2. Em Cenas, clique na cena que contém o slot de permissão.
  3. Na seção Condição da cena, clique em + para adicionar uma nova condição.

  4. Insira a seguinte condição para verificar o status da permissão, em que <slot_name> é o nome do parâmetro de sessão que você configurou no seu slot:

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

  5. Na seção Condição da cena, clique em + para adicionar uma nova condição.

  6. Insira a condição a seguir para processar o caso em que o usuário não consente em compartilhar as informações:

    scene.slots.status == "FINAL"

  7. Na seção Condição da cena, clique em + para adicionar uma nova condição.

  8. Insira a seguinte condição para processar o caso em que o usuário já concedeu permissão e não precisa ser perguntada novamente:

    "DEVICE_PRECISE_LOCATION" in user.permissions

Ler as informações dos usuários

Se o usuário conceder a permissão, as informações dele serão fornecidas nas solicitações seguintes.

No snippet abaixo, é possível ver as informações de local do dispositivo contidas em uma solicitação para o webhook em device.currentLocation:

Solicitação 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": ""
          }
        }
      }
    }

Para mais informações sobre o esquema do tipo de local, consulte a referência do Location.

Acesse as informações contidas na solicitação do webhook, conforme mostrado no snippet a seguir:

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

Usar permissão nas solicitações

Também é possível referenciar a permissão em prompts estáticos. Por exemplo, para a localização do dispositivo, use $device.currentLocation.coordinates.* e $device.currentLocation.postalAddress.*. O snippet de código a seguir mostra como referenciar a cidade do usuário em um comando:

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