Link all'assistente

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.

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:

  1. Nella console di Actions, vai a Esegui il deployment > Link all'assistente.
  2. Per Intent, seleziona l'intent per cui vuoi generare un link.
  3. Attiva l'opzione Vuoi attivare il collegamento per intent_name?.
  4. (Facoltativo) Nella sezione Parametri campagna, inserisci le informazioni da acquisire in aggiunta al link come parametri URL.
  5. (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.

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:

  1. Genera il link all'assistente nella console di Actions.
  2. Invia il link dell'assistente come URL a te stesso in un'email, un messaggio di chat o un altro formato.
  3. Su un dispositivo con l'assistente integrato, accedi all'assistente con lo stesso account utilizzato per creare il progetto Actions.
  4. 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.

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

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'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.

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&param.name=%22ExampleGame%22

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&param.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',
}

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',
}

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:

Sviluppo locale

Per includere un link avanzato all'assistente sul tuo sito web, procedi nel seguente modo:

  1. 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>
    
  2. 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.

  1. 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>
    
  2. Inserisci un tag <google-assistant-proactive-action-link> nella pagina web e imposta il relativo attributo groupId su 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>
    

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:

  1. Registra il tuo dominio pubblico nella console di Actions in Deployment > Verifica del brand > Collega sito.
  2. 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.