Vincular às suas ações (Dialogflow)

É possível gerar um URL por ação que vai levar diretamente à ação específica. Os usuários que clicarem no link do Assistente (antes chamado de links de ação) em um navegador da Web ou para dispositivos móveis serão direcionados para o Google Assistente no dispositivo, onde vão interagir diretamente com a ação correspondente.

Estes são alguns exemplos de links úteis do Google Assistente:

  • Vincular usuários a instruções por voz de um site de instruções.
  • Vincular usuários a uma experiência de suporte ao cliente de uma página de "recebimento de ajuda" página.
  • Vincular usuários a uma intent de atualização para que eles possam aceitar as atualizações futuras.
.

Se quiser gerar um URL para uma ação, faça o seguinte:

  1. No Console do Actions, acesse Desenvolver > Ações.
  2. Clique na ação para a qual você quer gerar um link.
  3. Na seção Links, ative Gostaria de ativar um URL para esta ação.
  4. Digite um Título do link. Esse título precisa incluir um verbo que descreva o que a ação vai fazer. Por exemplo, se a sua Ação levar o usuário a um fluxo de transação para comprar ingressos para um show, um título de link útil seria "comprar ingressos de shows".
  5. Clique em Salvar.

Você pode copiar o URL fornecido e fazer referência a ele sempre que quiser direcionar os usuários a essa ação específica.

Os links do Google Assistente podem conter uma intent e parâmetros no URL. O Google processa os parâmetros de acordo com o tipo de intenção especificada no URL.

A sintaxe geral do URL de um link do Assistente é a seguinte:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$param=$value][&$utm_param=$utm_value]

Os parâmetros de URL que podem ser definidos estão descritos na tabela a seguir:

Parâmetro de URL Descrição
$action_id Identificador numérico da ação.
$intent Nome completo de uma intent integrada ou personalizada.
$param Nome completo de um parâmetro de intent especificado no pacote de ações.
$value Valor codificado de URL do tipo declarado para $param no Pacote de ações.
$utm_param Lista de um ou mais tipos de parâmetro UTM. Os valores válidos incluem: utm_source, utm_medium. utm_campaign, utm_term e utm_content.
$utm_value Valor de string do parâmetro UTM.

Se o link do Assistente tiver uma intent integrada (a intent começa com actions.intent.*), o Google vai tentar extrair todos os parâmetros de intent integrados no URL e transmiti-los para sua ação. Todos os parâmetros que o Google não entender como de intent integrada são removidos.

Para ações de conversa, o Google envia esses parâmetros para o fulfillment como parte da mensagem AppRequest.

O exemplo abaixo mostra como especificar um URL de link do Google Assistente que inclui uma intent integrada com um único parâmetro de intent:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.GET_HOROSCOPE&param.astrologySign=%22cancer%22

Para intents personalizadas, o Google extrai apenas os parâmetros definidos pela sua ação como parte da intent e descarta todos os outros parâmetros.

O exemplo abaixo mostra como especificar um URL do link do Google Assistente que inclui uma intent personalizada:

https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK&param.topic=sports

Para o URL de exemplo acima, no AppRequest, o Google adiciona um objeto JSON como da seguinte forma:

argument {
  name: ‘topic’,
  raw_text: ‘sports’,
  text_value: ‘sports’,
}

Se você não especificar uma intent no link do Google Assistente, o Google será vinculado à intent MAIN (actions.intent.MAIN) da sua ação por padrão com o seguinte comportamento:

  • Se você não ativar explicitamente a intent MAIN no link do Google Assistente, o Google vai acionar a intent principal sem nenhum parâmetro, semelhante ao comportamento para "Falar com app_name".
  • Se você ativar explicitamente a intent MAIN, o Google vai transmitir os parâmetros para suas ações.

O exemplo abaixo mostra como especificar um URL de link do Google Assistente sem intent:

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

Os parâmetros de UTM são strings que o Google envia para sua ação quando os usuários clicam em um link do Assistente, que você pode usar para análise posteriormente.

Os parâmetros UTM que o Google envia para sua ação incluem o seguinte:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

O exemplo a seguir mostra como especificar um URL do link do Google Assistente que inclui parâmetros UTM:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale

Para o URL de exemplo acima, o Google adiciona os seguintes argumentos à mensagem AppRequest:

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’,
}

Você pode testar links do Google Assistente para qualquer intent (principal ou personalizada, com ou sem parâmetros) no simulador ou em um dispositivo.

Para testar o link do Google Assistente:

  1. Ativar o link do Assistente no console.
  2. Faça login no Assistente com a mesma conta que você usou para criar o projeto do Actions on Google.
  3. Crie uma versão clicável do seu link do Assistente (por e-mail, chat, documento etc.).
  4. Em um dispositivo com Google Assistente, clique no link criado na etapa anterior.

Depois de confirmar que o link do Google Assistente funciona como esperado, implante novamente a ação para disponibilizar o link aos usuários.

Restrições e práticas recomendadas

Como o URL do link do Assistente agora pode ser distribuído e referenciado fora do diretório ou de outros serviços do Google, observe as seguintes restrições e práticas recomendadas:

  • Continue a oferecer suporte a todos os links do Google Assistente. Se você distribuir um link do Assistente que depois for corrompido, seu projeto do Actions poderá ser sinalizado como não íntegro e removido.

  • Ao publicar um link, você apoia o acionamento de fontes não confiáveis. Para todas as ações vinculadas, é necessário confirmar explicitamente com o usuário antes de realizar qualquer "ação real". Por exemplo, uma ação que desativa um eletrodoméstico de casa inteligente solicita que o usuário diga "Tem certeza de que quer desativar o $applianceName?"

    Nesse contexto, uma "ação do mundo real" qualquer ação que afete serviços, dados, dispositivos, redes, computadores ou APIs do usuário. Por exemplo, enviar um e-mail, realizar uma transação, alterar o status de um dispositivo de casa inteligente, criar uma assinatura ou atualizar um conteúdo.