Links do Assistente

Você pode gerar um URL vinculado diretamente a uma intent específica da sua ação. Os usuários que clicarem em um link do Assistente (anteriormente 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 interagirão diretamente com sua ação.

Os links do Assistente são diferentes dos links da Web de diretórios, que direcionam os usuários para a página do Action no diretório do Assistente.

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

  • Como vincular usuários a instruções guiadas por voz em um website de instruções.
  • Como 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 optar por suas atualizações futuras.

Você pode gerar links do Assistente dentro do 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 Assistente estiver ativado na versão Alfa da ação, o link 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 a intent para gerar um link.
  3. Ative a opção Deseja ativar a vinculação para intent_name?.
  4. (Opcional) Na seção Parâmetros da campanha, insira qualquer informação que você queira capturar também no link como parâmetros de URL.
  5. (Opcional) Digite um Título do link. Use esse título para descrever o que a ação faz. Por 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 poderá ser "comprar ingressos de shows".

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

É possível testar os links do 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 Assistente em um dispositivo, siga estas etapas:

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

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

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

Quando um link do Google Assistente não contém parâmetros adicionais, o Google Assistente é vinculado à 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 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ê ativar explicitamente a intent MAIN, o Google Assistente transmitirá os parâmetros para as ações.

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

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

A sintaxe geral para o 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 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 de usuário.
$param Nome completo de um parâmetro de intent especificado no pacote Action.
$value Valor codificado de URL do tipo declarado para $param no pacote Action.
$utm_param Lista de um ou mais tipos de parâmetros 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 Assistente vai tentar extrair os parâmetros de intent incorporadas 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 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

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

O exemplo a seguir mostra como especificar um URL de link do 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, no AppRequest, o Google Assistente adiciona um objeto JSON da seguinte maneira:

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

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

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

Os links avançados do Assistente permitem que você aumente a descoberta da sua ação no seu site usando a assistência.js. Os usuários podem testar sua ação e vincular a Conta do Google ao serviço usando a vinculação de conta.

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.

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

Quando usado com a vinculação de conta, os links do Assistente usam seu 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.

Pré-requisitos

Para usar os links do Assistente, você precisa do seguinte:

Desenvolvimento local

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

  1. Inclua a biblioteca JavaScript a seguir na sua página, substituindo <PROJECT_ID> pelo código 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 de sua página. O botão "Testar com o Google Assistente" 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>

Acionamento proativo

Se você quiser que o fluxo avançado de links 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ê aplicar essa tag, o link será ativado na primeira visita sem que os usuários selecionem o botão in-line.

  1. Adicione um id à tag do grupo de vinculações 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 avançados do Assistente funcionam apenas para domínios de sua propriedade e que foram verificados com o Google. Ao desenvolver localmente, esse requisito é ignorado ao ter acesso ao projeto do Actions, ao fazer login na sua Conta do Google e ao definir 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 sua ação com os links avançados do Assistente:

  1. Registre seu domínio público no Console do Actions em Deploy > Brand Verification > Connect 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 a seguir são aplicadas para que o URL do link do Assistente possa ser distribuído e referenciado fora do diretório ou de outros serviços do Google:

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

  • Ao publicar um link, você pode acionar acionadores de fontes não confiáveis. Para qualquer ação vinculada, você precisa 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 pedir para o usuário dizer "Tem certeza de que quer desativar $applianceName?"

    Nesse contexto, uma ação 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.