Links do Assistente

Você pode gerar um URL vinculado diretamente a uma intent específica da sua ação. Os usuários que clicam em um link do Google Assistente (anteriormente chamados de links de ação) em um navegador da Web ou para dispositivos móveis são direcionados ao Google Assistente no dispositivo, onde interagem diretamente com a ação.

Os links do Google Assistente são diferentes dos links da Web de diretórios, que enviam um usuário para a página da sua ação no diretório do Google Assistente.

Veja algumas situações em que os links do Google Assistente podem ser úteis:

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

Gerar um link do Assistente

Você pode gerar links do Assistente no seu projeto, no Console do Actions. Os links do Assistente estão disponíveis em todos os canais de implantação (Alfa, Beta e de produção). Por exemplo, se o link do Google Assistente estiver ativado na versão Alfa da sua ação, ele vai ficar disponível para os testadores Alfa.

Para gerar o URL de uma ação, siga estas etapas:

1. No Console do Actions, acesse Implantar > Links do Assistente.
2. Em Intent, selecione para qual intent você quer gerar um link.
3. Ative a opção Gostaria de ativar a vinculação para intent_name?.
4. (Opcional) Na seção Parâmetros da campanha, insira as informações que você quer capturar no link como parâmetros de URL.
5. Opcional: insira um Título do link. Use esse título para descrever o que a ação faz. Por exemplo, se a ação direcionar o usuário a um fluxo de transação para comprar ingressos para um show, o título do link poderá ser "comprar ingressos de um show".

Depois de inserir suas informações, é possível ver e copiar o URL ou snippet de código gerado para o link do Assistente. Use o link do Google Assistente sempre que quiser direcionar os usuários para essa ação específica.

Observação:se você ativar um link do Assistente após a implantação da ação, será necessário implantá-la novamente para que o link entre em vigor.

Observação: os usuários do Dialogflow devem seguir as etapas nesta página.

Testar links do Assistente

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

Para testar o link do Google Assistente em um dispositivo, siga estas etapas:

1. Gere o link do Assistente no Console do Actions.
2. Envie o link do Google Assistente como um URL para você mesmo em um e-mail, uma mensagem de chat ou outro formato.
3. Em um dispositivo com Google Assistente, faça login com a mesma conta que você usou para criar seu projeto do Actions.
4. No mesmo dispositivo, clique no link do Google Assistente que você enviou para si mesmo.

Depois de confirmar que o link do Google Assistente funciona conforme o esperado, você precisa implantar a ação novamente para disponibilizar o link aos usuários.

Parâmetros de link do Google Assistente

Opcionalmente, os links do Assistente podem conter uma intent e parâmetros no URL. Use a seção Parâmetros de campanha para adicionar parâmetros de campanha.

Quando um link do Google Assistente não tem outros parâmetros, ele é vinculado à intent MAIN (actions.intent.MAIN) da ação com o seguinte comportamento:

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

Confira um exemplo de URL de link do Google Assistente usando a intent MAIN sem outros parâmetros:

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

Especificação do URL do link do Assistente

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 configurados sã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 do usuário.
$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âmetros de 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.

URLs de link do Google Assistente com intents integradas

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

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

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

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.PLAY_GAME&param.name=%22ExampleGame%22

URLs de link do Google Assistente com intenções de usuário

Para intents de usuário, o Google Assistente extrai apenas os parâmetros definidos pela ação como parte da intent e descarta todos os outros parâmetros.

O exemplo a seguir mostra como especificar um URL de link do Google Assistente que inclua uma intent de usuário:

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

No URL de exemplo acima, no AppRequest, o Google Assistente adiciona um objeto JSON da seguinte maneira:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

URLs de link do Assistente com parâmetros UTM

Os parâmetros do UTM são strings que o Google Assistente envia para sua ação quando os usuários clicam em um link do Assistente. Você pode usar as informações contidas nessas strings posteriormente para análise.

Os parâmetros UTM que o Google Assistente 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 de link do Google Assistente que inclua 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 Assistente 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',
}

Links avançados do Assistente

Os links avançados do Assistente oferecem uma maneira de aumentar a descoberta da Ação no seu site usando o help.js. Os usuários podem testar sua Ação e vincular a Conta do Google ao serviço usando a vinculação de contas.

Quando um usuário acessa seu site, ele vê um botão "Testar com o Google Assistente", que aciona o fluxo de links do Assistente avançado.

Ao ativar a vinculação de conta para sua Ação, os usuários podem acessá-la em qualquer dispositivo com Google Assistente. Além disso, os usuários podem vincular a conta do seu serviço à Conta do Google, o que permite uma experiência mais personalizada.

Quando usadas com a vinculação de contas, as vinculações do Rich Assistente usam o URL de autorização, que é definido no seu projeto no console do Actions. Para mais informações, consulte a documentação de vinculação de contas.

Observação: se o usuário não tiver feito login na Conta do Google, o link do Assistente avançado acionará a ação no Google Assistente no dispositivo do usuário (se o Assistente estiver disponível) ou direcionará o usuário para a página do diretório do Assistente da ação.

Pré-requisitos

Para usar links do Assistente avançado, você precisa do seguinte:

• Projeto de ações.
• Link do Assistente ativado para a ação.
• (Opcional) Vinculação de contas ativada para a Ação.

Desenvolvimento local

Para incluir um link avançado do Assistente no seu site, siga estas etapas:

1. Inclua a seguinte biblioteca JavaScript na sua página, substituindo <PROJECT_ID> pelo ID do projeto do Actions:

   <script async
   src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
   </script>
   

2. Adicione a seguinte tag HTML em algum lugar da sua página. O botão "Testar com o Google Assistente" inline será carregado:

   <google-assistant-link-group>
     <!-- One or more <google-assistant-link> tags -->
     <google-assistant-link href="{ASSISTANT_LINK_1}">
     </google-assistant-link>
     <google-assistant-link href="{ASSISTANT_LINK_2}">
     </google-assistant-link>
   </google-assistant-link-group>
   

   Observação :se um usuário do Google Assistente não estiver conectado, o primeiro link acionará o Assistente ou redirecionará o usuário para a página do diretório do Google Assistente para sua ação.

Acionamento proativo

Se você quiser que o fluxo de links do Assistente avançado seja iniciado automaticamente quando os usuários acessarem sua página pela primeira vez, use a tag <google-assistant-proactive-link>. Quando você aplica essa tag, o link é ativado sem os usuários na primeira visita, sem que eles selecionem o botão inline.

Observação: enquanto o acionamento proativo permanece ativo por algum tempo, os usuários ainda precisam selecionar o botão inline para reativar esse fluxo.

1. Adicione um id à sua tag do grupo de contas vinculadas do Assistente:

   <google-assistant-link-group id="my-group">
     <!-- One or more <google-assistant-link> tags -->
     <google-assistant-link href="{ASSISTANT_LINK_1}">
     </google-assistant-link>
     <google-assistant-link href="{ASSISTANT_LINK_2}">
     </google-assistant-link>
   </google-assistant-link-group>
   

2. Coloque uma tag <google-assistant-proactive-action-link> na sua página da Web e defina o atributo groupId como id:

   <google-assistant-link-group id="my-group">
     <!-- One or more <google-assistant-link> tags -->
     <google-assistant-link href="{ASSISTANT_LINK_1}">
     </google-assistant-link>
     <google-assistant-link href="{ASSISTANT_LINK_2}">
     </google-assistant-link>
   </google-assistant-link-group>
   
   <google-assistant-proactive-link
   groupId="my-group">
   </google-assistant-proactive-link>
   

Implantação

Os links do Assistente avançado só funcionam nos domínios de sua propriedade que foram verificados com o Google. No desenvolvimento local, esse requisito é ignorado quando você tem acesso ao projeto do Actions, faz login na sua Conta do Google e define o parâmetro de consulta dev=true na tag de script.

  <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
  </script>

Para implantar a ação com os links avançados do Assistente, faça o seguinte:

1. Registre seu domínio público no Console do Actions em Implantar > Verificação de marca > Conectar site.

2. Remova o parâmetro de consulta dev=true do script:

   <script async
   src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}">
   </script>
   

Restrições e práticas recomendadas

As restrições e práticas recomendadas abaixo se aplicam para que o URL do link do Google Assistente possa ser distribuído e referenciado fora do diretório ou de outros serviços do Google:

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

• Publicar um link significa que você oferece suporte ao acionamento de fontes não confiáveis. Para qualquer ação vinculada, é necessário confirmar explicitamente com o usuário antes de realizar qualquer ação no mundo real. Por exemplo, uma ação que desativa um dispositivo de casa inteligente precisa solicitar que o usuário diga: "Você quer mesmo desativar o $applianceName?"

  Nesse contexto, uma ação real é qualquer ação que afeta os 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.