Uma intent integrada é um identificador exclusivo que você pode especificar para informar ao Google Assistente que sua ação pode atender a uma categoria específica de solicitações do usuário. Confira alguns exemplos de consultas do usuário que o Google Assistente faz a correspondência com intents integradas:
- Intenção integrada"Jogar": "Ok Google. Divirta-se com um jogo de memória"
- Intent integrada"Get horoscope": "Ok Google. Ver meu horóscopo"
Durante a descoberta de ações, o Google Assistente pode usar metadados sobre a ação, incluindo as intents integradas especificadas, para recomendar sua ação aos usuários. Para minimizar as idas e vindas da conversa, o Google Assistente também tenta verificar os parâmetros das consultas do usuário e transmiti-los para a ação.
Para conferir a lista completa de intents integradas com suporte do Google Assistente, incluindo parâmetros e exemplos de consultas do usuário, consulte a Referência de intents integradas.
Integrar intents integradas
Dependendo de como você está criando a Ação, há diferentes maneiras de integrar intents integradas.
Dialogflow
Se você estiver usando o Dialogflow para criar sua ação, poderá anexar uma intent integrada graficamente pelo console do Dialogflow.
Para anexar uma intent integrada ao Dialogflow, siga estas etapas:
- Abra o console do Dialogflow, selecione seu agente e navegue até a tela Intents.
Crie ou selecione a intent que o agente aciona quando recebe uma intent integrada específica. Abra a seção Eventos e clique em Adicionar evento.
No campo Eventos, digite o nome de um evento de intent integrada para seu agente (por exemplo,
actions_intent_PLAY_GAME
).Clique em Salvar.
SDK do Actions
Se você estiver usando o SDK do Actions para criar sua ação, precisará especificar o mapeamento entre as intents integradas e as ações no pacote.
Para anexar uma intent integrada com o SDK do Actions, siga estas etapas:
- Especifique a intent integrada no campo de nome da definição de Action.
- Faça upload do pacote de ações para o projeto do Actions usando a ferramenta
gactions
, conforme descrito em Visão geral do SDK do Actions.
Por exemplo, o snippet a seguir mostra como adicionar a intent
integrada CHECK_AIR_QUALITY
:
{
"actions":[
{
"description":"Default Welcome Intent",
"name":"MAIN",
"fulfillment":{
"conversationName":"conversation_1"
},
"intent":{
"name":"actions.intent.MAIN"
}
},
{
"description":"Check Air Quality",
"name":"CHECK_AIR_QUALITY",
"fulfillment":{
"conversationName":"conversation_1"
},
"intent":{
"name":"actions.intent.CHECK_AIR_QUALITY"
}
}
],
"conversations":{
"conversation_1":{
"name":"conversation_1",
"url":"https://example.com/fulfillment",
"fulfillmentApiVersion":2
}
}
}
Processar parâmetros de intent integrada
Quando a ação é invocada por uma intent integrada, o fulfillment pode receber outros parâmetros. O esquema de intent define os nomes e os tipos dos parâmetros como tipos primitivos ou entidades do schema.org (link em inglês). Para conferir o esquema de intents integradas de ações de conversa, consulte a Referência de intents integradas.
Os parâmetros para intents integradas são opcionais. O Google Assistente processará o preenchimento dos parâmetros com valores se eles puderem ser extraídos da invocação da intent integrada pelo usuário.
Por exemplo, o esquema da intent integrada actions.intent.CHECK_AIR_QUALITY
define quatro parâmetros opcionais:
Nome do parâmetro | Tipo |
---|---|
attributes |
Um valor de string. |
location |
Um objeto schema.org/Place . |
temporalCoverage |
Um objeto schema.org/Duration . |
timeIndicator |
Uma EnumeratedDuration (extensão específica do Google). |
O snippet de código a seguir mostra um exemplo da solicitação de webhook de conversa (JSON) quando um usuário invoca sua ação dizendo "Qual é a qualidade do ar em São Francisco amanhã?":
"inputs":[
{
"intent":"actions.intent.CHECK_AIR_QUALITY",
"rawInputs":[
{
"inputType":"VOICE",
"query":"what is the air quality in san francisco tomorrow"
}
],
"arguments":[
{
"name":"location",
"structuredValue":{
"geo":{
"longitude":-122.41941550000001,
"latitude":37.7749295
},
"@context":"https://schema.org",
"@type":"Place",
"name":"san francisco"
}
},
{
"name":"temporalCoverage",
"rawText":"2018-04-25",
"textValue":"2018-04-25"
}
]
}
]
Neste exemplo, os parâmetros usam os seguintes valores:
- O parâmetro
location
contém o valorschema.org/Place
para "São Francisco". - O parâmetro
temporalCoverage
contém o valorschema.org/Duration
para a data de amanhã em relação ao horário da invocação. - Não há valores para os parâmetros
attributes
etimeIndicator
, porque a frase de invocação do usuário não incluía essas informações.
Se você usar a biblioteca de cliente do Actions on Google para Node.js, poderá recuperar o valor dos parâmetros conforme mostrado no snippet a seguir:
app.intent('actions.intent.CHECK_AIR_QUALITY', (conv) => {
const attributes = conv.arguments.get('attributes');
const location = conv.arguments.get('location');
const temporal_coverage = conv.arguments.get('temporalCoverage');
Const time_indicator = conv.arguments.get('timeIndicator')
// Your Action logic. If you need to use any of the parameter values,
// you should check first that it is defined. Arguments.get returns
// undefined if it can't find a value for a parameter.
});
Testar integrações com intents integradas
Siga estas etapas para testar sua integração:
- Abra o simulador do Actions com a ação de teste ativada ou abra o Google Assistente no seu dispositivo.
- Fale ou digite uma consulta associada a essa intent integrada. Por exemplo, "Quero jogar".
- Na caixa de diálogo de seleção de app exibida, encontre a ação.
- Selecione seu app para enviar uma intent a ele.
Práticas recomendadas para usar intents integradas
Siga estas práticas recomendadas ao usar intents integradas:
- Mapear intents integradas para ações específicas: quando uma intent integrada específica
acionar sua Ação, direcione o usuário à intent e
funcionalidade específicas dela com o mínimo de atrito possível. Por
exemplo, se a ação oferecer suporte à intent integrada
PLAY_GAME
e receber essa intent, encaminhe o usuário imediatamente para o recurso do jogo da sua ação. Evite perguntar novamente se o usuário quer jogar. - Processar parâmetros de intent integrada: use os valores de parâmetro de intent integrados que o Google Assistente envia para o fulfillment. Evite solicitar novamente esses valores ao usuário.