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:
- No Console do Actions, acesse Implantar > Links do Assistente.
- Em Intent, selecione para qual intent 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ê quer capturar 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. 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.
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:
- Gere o link do Assistente no Console do Actions.
- Envie o link do Google Assistente como um URL para você mesmo em um e-mail, uma mensagem de chat ou outro formato.
- 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 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¶m.$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¶m.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¶m.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.
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:
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 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>
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.
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>
Coloque uma tag
<google-assistant-proactive-action-link>
na sua página da Web e defina o atributogroupId
comoid
:<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:
- Registre seu domínio público no Console do Actions em Implantar > Verificação de marca > Conectar site.
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.