Puoi generare un URL che rimandi direttamente a un intent specifico dell'Azione. Gli utenti che fanno clic su un link all'assistente (precedentemente chiamato link Azioni) in un browser web o mobile vengono indirizzati all'assistente sul proprio dispositivo, dove interagiscono direttamente con l'Azione.
I link all'assistente sono diversi dai link web delle directory, che indirizzano l'utente alla pagina dell'azione nella directory dell'assistente.
Ecco alcune situazioni in cui i link all'assistente possono essere utili:
- Indirizzare gli utenti a istruzioni vocali da un sito web di istruzioni.
- Collegamento degli utenti all'esperienza di assistenza clienti da una pagina di assistenza.
- Collegamento degli utenti a un intent di aggiornamento in modo che possano attivare i tuoi aggiornamenti futuri.
Genera un link all'assistente
Puoi generare link all'assistente dall'interno del tuo progetto nella console di Actions. I link all'assistente sono disponibili in tutti i canali di deployment (alpha, beta e produzione). Ad esempio, se il link all'assistente è attivo nella release alpha dell'Azione, il link è disponibile per gli alpha tester.
Per generare un URL per un'Azione, procedi nel seguente modo:
- Nella console di Actions, vai a Esegui il deployment > Link all'assistente.
- Per Intent, seleziona l'intent per cui vuoi generare un link.
- Attiva l'opzione Vuoi attivare il collegamento per intent_name?.
- (Facoltativo) Nella sezione Parametri campagna, inserisci le informazioni da acquisire in aggiunta al link come parametri URL.
- (Facoltativo) Inserisci un Titolo link. Utilizza questo titolo per descrivere lo scopo dell'Azione. Ad esempio, se l'Azione interrompe l'utente in un flusso di transazioni per acquistare biglietti per un concerto, il titolo del link potrebbe essere "Acquista biglietti dei concerti".
Dopo aver inserito le informazioni, puoi visualizzare e copiare l'URL o lo snippet di codice generato per il link all'assistente. Usa il link Assistente dove vuoi indirizzare gli utenti a questa specifica Azione.
Testa i link all'assistente
Puoi testare i link all'assistente per qualsiasi intent (principale o personalizzato, con o senza parametri) tramite il simulatore o su un dispositivo.
Per testare il tuo link all'assistente su un dispositivo, svolgi i seguenti passaggi:
- Genera il link all'assistente nella console di Actions.
- Invia il link dell'assistente come URL a te stesso in un'email, un messaggio di chat o un altro formato.
- Su un dispositivo con l'assistente integrato, accedi all'assistente con lo stesso account utilizzato per creare il progetto Actions.
- Sullo stesso dispositivo, fai clic sul link dell'assistente che hai inviato a te stesso.
Dopo aver verificato che il link all'assistente funzioni come previsto, devi eseguire nuovamente il deployment dell'Azione per rendere il link disponibile ai tuoi utenti.
Parametri del link all'assistente
I link all'assistente possono facoltativamente contenere un intent e parametri nell'URL. Utilizza la sezione Parametri campagna per aggiungere parametri della campagna.
Quando un link all'assistente non contiene parametri aggiuntivi, l'Assistente Google si collega
all'intent MAIN
(actions.intent.MAIN
) dell'azione con il seguente
comportamento:
- Se non hai attivato esplicitamente l'intent
MAIN
nel link dell'assistente, l'assistente corrisponde all'intent principale senza alcun parametro, in modo simile al comportamento di "Parla con app_name". - Se hai attivato esplicitamente l'intent
MAIN
, l'assistente passa i parametri alle tue azioni.
Ecco un esempio di URL del link all'assistente che utilizza l'intent MAIN
senza
parametri aggiuntivi:
https://assistant.google.com/services/invoke/uid/000000d139bbc4d4
Specifica dell'URL del link all'assistente
La sintassi generale dell'URL di un link all'assistente è la seguente:
https://assistant.google.com/services/invoke[/$action_id][?intent=$intent¶m.$param=$value][&$utm_param=$utm_value]
I parametri URL che puoi impostare sono descritti nella seguente tabella:
Parametro URL | Descrizione |
---|---|
$action_id |
Identificatore numerico dell'azione. |
$intent |
Nome completo di un'istanza integrata o di un intent dell'utente. |
$param |
Nome completo di un parametro intent specificato nel pacchetto Azioni. |
$value |
Valore con codifica URL del tipo dichiarato per $param nel
pacchetto Azioni. |
$utm_param |
Elenco di uno o più tipi di parametri UTM. I valori validi includono:
utm_source , utm_medium ,
utm_campaign , utm_term e
utm_content . |
$utm_value |
Valore stringa del parametro UTM. |
URL link all'assistente con intent integrati
Se il link all'assistente contiene un intent integrato (l'intent inizia con actions.intent.
), l'Assistente Google prova a estrarre eventuali parametri di intent integrati nell'URL e li passa all'Azione. Tutti i parametri che
l'assistente non comprende come parametri per intent integrati vengono rimossi.
Per le azioni conversazionali, l'assistente invia questi parametri al fulfillment
come parte del messaggio AppRequest
.
L'esempio seguente mostra come specificare un URL del link all'assistente che include un intent integrato con un singolo parametro di intent:
https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.PLAY_GAME¶m.name=%22ExampleGame%22
URL dei link all'assistente con intent dell'utente
Per gli intent dell'utente, l'Assistente Google estrae solo i parametri definiti dall'Azione come parte dell'intent e ignora qualsiasi altro parametro.
L'esempio seguente mostra come specificare l'URL di un link all'assistente che include un intent dell'utente:
https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK¶m.topic=sports
Per l'URL di esempio sopra riportato, in AppRequest
, l'assistente aggiunge un oggetto JSON come segue:
argument {
name: 'topic',
raw_text: 'sports',
text_value: 'sports',
}
URL link all'assistente con parametri UTM
I parametri UTM sono stringhe che l'Assistente Google invia all'azione quando gli utenti fanno clic su un link all'assistente. Puoi utilizzare le informazioni contenute in queste stringhe in un secondo momento per l'analisi.
I parametri UTM che l'assistente invia all'Azione includono quanto segue:
utm_source
utm_medium
utm_campaign
utm_term
utm_content
L'esempio seguente mostra come specificare l'URL del link dell'assistente che include parametri UTM:
https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale
Per l'URL di esempio riportato sopra, l'assistente aggiunge i seguenti argomenti nel
messaggio 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',
}
Link Assistente avanzato
I link avanzati all'Assistente Google ti consentono di aumentare la visibilità dell'Azione nel tuo sito web utilizzando assist.js. Gli utenti possono provare l'Azione e collegare il proprio Account Google al tuo servizio utilizzando il collegamento dell'account.
Quando un utente visita il tuo sito web, vede un pulsante "Prova con l'Assistente Google", che attiva il flusso di link Assistente Google avanzato.
L'attivazione del collegamento dell'account per l'Azione consente agli utenti di accedere all'Azione da qualsiasi dispositivo con l'assistente integrato. Inoltre, gli utenti possono collegare il loro account con il tuo servizio al loro Account Google, per un'esperienza più personalizzata.
Se utilizzati insieme al collegamento dell'account, i link Assistente avanzato utilizzano l'URL di autorizzazione, impostato nel tuo progetto nella console di Actions. Per saperne di più, consulta la documentazione sul collegamento dell'account.
Prerequisiti
Per utilizzare i link Assistente avanzato, devi disporre di:
- Progetto Actions.
- Link dell'assistente attivato per la tua Azione.
- (Facoltativo) Collegamento dell'account attivato per l'Azione.
Sviluppo locale
Per includere un link avanzato all'assistente sul tuo sito web, procedi nel seguente modo:
Includi la seguente libreria JavaScript nella pagina, sostituendo
<PROJECT_ID>
con l'ID progetto Actions:<script async src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true"> </script>
Aggiungi il seguente tag HTML in un punto della pagina. Viene caricato il pulsante "Prova con l'Assistente Google" incorporato:
<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>
Attivazione proattiva
Se vuoi che il flusso di link all'assistente avanzato venga avviato automaticamente quando gli utenti visitano la tua pagina per la prima volta, utilizza il tag <google-assistant-proactive-link>
. Quando applichi questo tag, il link si attiva senza utenti alla prima visita, senza che questi abbiano selezionato il pulsante incorporato.
Aggiungi un
id
al tag del gruppo di collegamenti dell'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>
Inserisci un tag
<google-assistant-proactive-action-link>
nella pagina web e imposta il relativo attributogroupId
suid
:<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>
Deployment
I link dell'Assistente avanzato funzionano solo per i domini di tua proprietà e che hai verificato con Google. Durante lo sviluppo a livello locale, questo requisito viene ignorato quando si dispone dell'accesso al progetto Actions, dell'accesso all'Account Google e dell'impostazione del parametro di query dev=true
nel tag script.
<script async
src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
</script>
Per eseguire il deployment dell'Azione con i link avanzati dell'Assistente:
- Registra il tuo dominio pubblico nella console di Actions in Deployment > Verifica del brand > Collega sito.
Rimuovi il parametro di ricerca
dev=true
dallo script:<script async src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}"> </script>
Limitazioni e best practice
Si applicano le seguenti restrizioni e best practice per consentire di distribuire e far riferimento all'URL del link all'assistente al di fuori della directory o di altri servizi Google:
- Continua a supportare tutti i tuoi link all'assistente. Se distribuisci un link all'assistente che si interrompe in un secondo momento, il tuo progetto di azioni potrebbe essere contrassegnato come non integro e rimosso.
Pubblicare un link significa supportare l'attivazione da fonti non attendibili. Per tutte le azioni collegate, devi confermare esplicitamente con l'utente prima di intraprendere qualsiasi azione reale. Ad esempio, un'azione che disattiva un'appliance per la smart home deve richiedere all'utente di dire "Vuoi disattivare
$applianceName
?".In questo contesto, un'azione reale è qualsiasi azione che influisca su servizi, dati, dispositivi, reti, computer o API dell'utente. Ad esempio, inviare un'email, eseguire una transazione, modificare lo stato di un elettrodomestico per la smart home, creare un abbonamento o aggiornare dei contenuti.