Link alle tue azioni (Dialogflow)

Puoi generare un URL che rimandi direttamente all'Azione specifica. Gli utenti che fanno clic sul link all'assistente (precedentemente chiamato link Azioni) in un browser web o mobile verranno indirizzati all'assistente sul loro dispositivo, dove interagiranno direttamente con l'Azione corrispondente.

Ecco alcuni esempi di link utili all'assistente:

  • Indirizzare gli utenti a istruzioni vocali da un sito web di istruzioni.
  • Collegamento degli utenti a un'esperienza con l'assistenza clienti da una pagina "Assistenza".
  • Collegare gli utenti a un intent di aggiornamento in modo che possano attivare i tuoi aggiornamenti futuri.

Per generare un URL per un'azione:

  1. Nella console di Actions, vai a Sviluppo > Azioni.
  2. Fai clic sull'azione per la quale desideri generare un link.
  3. Nella sezione Link, attiva Vuoi attivare un URL per questa azione.
  4. Inserisci un Titolo collegamento. Questo titolo deve includere un verbo descrittivo di ciò che farà l'Azione. Ad esempio, se l'Azione indirizza l'utente in un flusso di transazioni per acquistare i biglietti di un concerto, un link utile potrebbe essere "acquista biglietti per concerti".
  5. Fai clic su Salva.

Puoi copiare l'URL fornito e farvi riferimento dove vuoi indirizzare gli utenti a questa specifica Azione.

I link all'assistente possono facoltativamente contenere un intent e parametri nell'URL. Google gestisce i parametri in base al tipo di intent specificato nell'URL.

La sintassi generale dell'URL di un link all'assistente è la seguente:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$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 intent integrato o personalizzato.
$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.

Se il link all'assistente contiene un intent integrato (l'intent inizia con actions.intent.*), Google tenterà di estrarre eventuali parametri di intent integrati nell'URL e di trasmetterli all'Azione. Vengono eliminati tutti i parametri che Google non comprende come parametri degli intent integrati.

Per le azioni conversazionali, Google 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.GET_HOROSCOPE&param.astrologySign=%22cancer%22

Per gli intent personalizzati, Google estrae solo i parametri definiti dall'Azione come parte dell'intent ed elimina eventuali altri parametri.

L'esempio seguente mostra come specificare l'URL del link all'assistente che include un intent personalizzato:

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

Per l'URL di esempio sopra riportato, nel campo AppRequest, Google aggiunge un oggetto JSON come segue:

argument {
  name: ‘topic’,
  raw_text: ‘sports’,
  text_value: ‘sports’,
}

Se non specifichi un intent nel link all'assistente, Google si collega all'intent MAIN (actions.intent.MAIN) dell'Azione per impostazione predefinita con il seguente comportamento:

  • Se non hai attivato esplicitamente l'intent MAIN nel link all'assistente, Google attiva l'intent principale senza alcun parametro, in modo simile al comportamento di "Parla con app_name".
  • Se hai attivato esplicitamente l'intent MAIN, Google passa i parametri alle tue azioni.

L'esempio seguente mostra come specificare l'URL del link dell'assistente senza alcun intent:

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

I parametri UTM sono stringhe che Google invia all'Azione quando gli utenti fanno clic su un link all'assistente, che puoi utilizzare in un secondo momento per l'analisi.

I parametri UTM che Google 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 all'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, Google 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’,
}

Puoi testare i link all'assistente per qualsiasi intent (principale o personalizzato, con o senza parametri) tramite il simulatore o un dispositivo.

Per testare il tuo link all'assistente:

  1. Attiva il link all'assistente nella console.
  2. Accedi all'assistente con lo stesso account che hai utilizzato per creare il tuo progetto Actions on Google.
  3. Crea una versione cliccabile del link all'assistente (in email, chat, documenti e così via).
  4. Su un dispositivo con l'assistente integrato, fai clic sul link creato nel passaggio precedente.

Dopo aver verificato che il link all'assistente funzioni come previsto, dovrai eseguire nuovamente il deployment dell'Azione per rendere il link disponibile ai tuoi utenti.

Limitazioni e best practice

Poiché ora l'URL del link all'assistente può essere distribuito e fatto riferimento al di fuori della directory o di altri servizi Google, tieni presente che si applicano le seguenti restrizioni e best practice:

  • Assicurati di continuare 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 Actions 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 elettrodomestico per la smart home dovrebbe mostrare all'utente il messaggio "Vuoi spegnere $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'appliance smart home, creare un abbonamento o aggiornare contenuti.