As ações de conversa foram descontinuadas em 13 de junho de 2023. Para mais informações, consulte Desativação do recurso Ações de conversa.

Esta página foi traduzida pela API Cloud Translation.

Links do Assistente

É possível gerar um URL que leva diretamente a uma intent específica da sua ação. Os usuários que clicam em um link do Assistente (antes chamado de links de ação) em um navegador da Web ou para dispositivos móveis são direcionados a Google Assistente no dispositivo, onde eles interagem diretamente com sua ação.

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

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

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 a partir de uma página de ajuda.
Vincular usuários a uma intent de atualização para que eles possam ativar suas atualizações futuras.

Gerar um link do Assistente

É possível 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 produção). Por exemplo, se o link do Google Assistente estiver ativado na versão Alfa da sua Ação, o link estará disponível para os testadores Alfa.

Se quiser gerar um URL para uma ação, siga estas etapas:

No Console do Actions, acesse Implantar > Links do Google Assistente.
Em Intent, selecione a intent para que você quer gerar um link.
Ative a opção Gostaria de ativar a vinculação para intent_name?.
(Opcional) Na seção Parâmetros da campanha, insira as informações que você quiser capture também no link como parâmetros de URL.
(Opcional) Insira um Título do link. Use esse título para descrever o que a ação faz. Para exemplo, se a ação levar o usuário a um fluxo de transação para comprar ingressos para um show, o título do link pode ser "comprar ingressos para shows".

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

Testar links do Assistente

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

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

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

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

Parâmetros do link do Google Assistente

Os links do Google Assistente podem conter uma intent e parâmetros no URL. Use o seção Parâmetros da campanha para adicionar parâmetros da campanha.

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

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

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

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

Especificação do URL do link do Google 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 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 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â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.

URLs de links do Google Assistente com intents integradas

Se o link do Google Assistente tiver uma intent integrada (a intent começa com actions.intent.), o Google Assistente tentará extrair qualquer intent integrada no URL e os transmite para a ação. Todos os parâmetros que O Google Assistente não entende porque os parâmetros de intent integrados são removidos.

Em 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 do 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.PLAY_GAME&param.name=%22ExampleGame%22

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

Para as intenções do usuário, o Google Assistente extrai apenas os parâmetros que são definido pela ação como parte da intent e descarta todos os outros parâmetros.

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

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

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

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

URLs de link do Google Assistente com parâmetros UTM

Os parâmetros de UTM são strings que o Google Assistente envia ao seu Ação quando os usuários clicam em um link do Google Assistente Você pode usar informações contidas em essas strings mais tarde 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 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 Assistente adiciona os seguintes argumentos à AppRequest mensagem:

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

Com os links avançados do Assistente, você pode aumentar a descoberta da sua Ação usando seu site usando assisti.js. Os usuários podem testar sua Ação e vincular da Conta do Google ao serviço usando a vinculação de contas.

Quando um usuário acessa seu site, ele vê a opção "Testar com o Google Assistente" que aciona o fluxo do link do Assistente do Rich Assistente.

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

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

Pré-requisitos

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

Projeto do Actions.
Link do Assistente ativado para sua ação.
(Opcional) A vinculação de contas está ativada para sua ação.

Desenvolvimento local

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

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>
```
Adicione a tag HTML a seguir em algum lugar da página. Isso carrega a opção in-line "Testar com o Google Assistente". botão:
```
<google-assistant-link-group>
  
  <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 do Assistente será acionado. Assistente ou redireciona o usuário para a página do diretório do Assistente para sua Ação.

acionamento proativo

Se você quiser que o fluxo de links avançados do Assistente 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 usuários na primeira visita, sem que eles selecionem o botão inline.

Adicione um id à tag do grupo de contas vinculadas do Google 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>

Coloque uma tag <google-assistant-proactive-action-link> na sua página da Web e defina o atributo groupId dela 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 em domínios de sua propriedade que foram verificados com o Google. No desenvolvimento local, esse requisito é ignorado com o acesso ao projeto do Actions, o login na sua Conta do Google e a configuração do parâmetro de consulta dev=true na sua tag de script.

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

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

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

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 a seguir se aplicam para que o URL do link do Google Assistente podem ser distribuídos e referenciados fora do diretório ou de outros serviços serviços:

Continue para oferecer suporte a todos os links do Google Assistente. Se você distribuir um link do Google Assistente que for corrompido, seu projeto do Actions poderá ser sinalizado como não íntegros e removidos.
Ao publicar um link, você apoia o acionamento de fontes não confiáveis. Para qualquer ações vinculadas, você deve confirmar explicitamente com o usuário antes de tomar qualquer em ações do mundo real. Por exemplo, uma ação que desativa uma casa inteligente appliance deve solicitar que o usuário diga: "Tem certeza de que quer desativar o $applianceName?"

Nesse contexto, uma ação real é qualquer ação que afeta a própria serviços, dados, dispositivos, redes, computadores ou APIs. Por exemplo, enviar um e-mail, realizar uma transação, alterar o status de uma casa inteligente appliance, criando uma assinatura ou atualizando um conteúdo.