Le azioni di conversazione sono state ritirate il 13 giugno 2023. Per ulteriori informazioni, vedi Ritiro di Azioni di conversazione.

Questa pagina è stata tradotta dall'API Cloud Translation.

Link all'assistente

Puoi generare un URL che rimandi direttamente a uno specifico intento dell'Azione. Gli utenti che fanno clic su un link all'assistente (precedentemente chiamati link di azione) in un browser web o mobile vengono indirizzati a Assistente sul suo dispositivo, dove interagiscono direttamente con l'azione.

I link all'assistente sono diversi dai link web a directory, che inviano un utente alla pagina dell'Azione nella directory dell'assistente.

Ecco alcune situazioni in cui i link all'assistente possono essere utili:

Collegamento degli utenti a istruzioni vocali da un sito web di istruzioni.
Collegare gli utenti a un'esperienza di assistenza clienti da una pagina di assistenza.
Collegare gli utenti a un intent di aggiornamento per consentire l'attivazione per gli aggiornamenti futuri.

Genera un link all'assistente

Puoi generare link all'assistente all'interno del tuo progetto nella console di Actions. I link all'assistente sono disponibili in tutti i canali di implementazione (alpha, beta, e produzione). Ad esempio, se il link all'assistente è attivo nella versione alpha dell'Azione, il link è disponibile per i tester alpha.

Per generare un URL per un'azione:

Nella console Actions, vai a Deployment > Link all'assistente.
In Intent, seleziona l'intent per il quale vuoi generare un link.
Attiva l'opzione Vuoi attivare il collegamento per intent_name?.
(Facoltativo) Nella sezione Parametri campagna, inserisci le informazioni che desideri anche acquisire il link come parametri URL.
(Facoltativo) Inserisci un Titolo link. Utilizza questo titolo per descrivere l'azione. Per Ad esempio, se l'Azione porta l'utente attraverso un flusso di transazione per acquistare i biglietti di un concerto, il titolo del link potrebbe essere "acquistare i biglietti di un concerto".

Dopo aver inserito i dati, puoi visualizzare e copiare l'URL generato oppure snippet di codice generato per il link all'assistente. Usa il link dell'assistente ovunque indirizzare gli utenti a questa specifica Azione.

Prova i link all'assistente

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

Per testare il link all'assistente su un dispositivo, svolgi i seguenti passaggi:

Genera il link all'assistente nella console di Actions.
Invia il link all'assistente sotto forma di URL in un'email, in un messaggio di chat o in 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 l'Azione per rendere il link disponibile agli utenti.

Parametri link all'assistente

I link dell'assistente possono facoltativamente contenere un intent e dei parametri nell'URL. Utilizza la Sezione Parametri campagna per aggiungere i parametri della campagna.

Quando un link all'assistente non contiene parametri aggiuntivi, l'Assistente Google si collega a l'intent MAIN (actions.intent.MAIN) dell'Azione con quanto segue comportamento:

Se non hai attivato esplicitamente l'intent MAIN nel link dell'assistente, L'assistente corrisponde all'intent principale senza parametri, in modo simile all'intent comportamento per "Parla con app_name".
Se hai attivato esplicitamente l'intent MAIN, l'assistente trasmette 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 dell'assistente

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 dell'utente.
`$param`	Nome completo di un parametro di intent specificato nel pacchetto Azioni.
`$value`	Valore codificato nell'URL del tipo dichiarato per `$param` nel Pacchetto di azioni.
`$utm_param`	Elenco di uno o più tipi di parametri UTM. I valori validi sono: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term` e `utm_content`.
`$utm_value`	Valore stringa del parametro UTM.

URL dei link dell'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 qualsiasi intent integrato dell'URL e li trasmette all'Azione. Qualsiasi parametro che L'assistente non comprende quando i parametri di intent integrati vengono rimossi.

Per le azioni conversazionali, l'assistente invia questi parametri al tuo fulfillment nel messaggio AppRequest.

L'esempio seguente mostra come specificare un URL del link all'assistente che Includa 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

URL dei link dell'assistente con intent dell'utente

Per gli intent degli utenti, l'Assistente Google estrae solo i parametri che sono definita dall'Azione come parte dell'intent e scarta eventuali altri parametri.

L'esempio seguente mostra come specificare un URL del link all'assistente che include l'intento di un utente:

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

Per l'URL di esempio riportato sopra, in AppRequest, l'assistente aggiunge un oggetto JSON come che segue:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

URL dei link dell'assistente con parametri UTM

I parametri UTM sono stringhe che l'Assistente Google invia al tuo Azione quando gli utenti fanno clic su un link dell'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 un URL del link all'assistente che include i 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 nella AppRequest messaggio:

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 avanzati all'assistente

I link avanzati all'Assistente ti consentono di aumentare la visibilità dell'Azione tramite sul tuo sito web, utilizzando assist.js. Gli utenti possono provare l'azione e collegare i propri un Account Google al servizio tramite il collegamento dell'account.

Quando un utente visita il tuo sito web, vede il messaggio "Prova con l'Assistente Google" che attiva il flusso di link all'Assistente avanzato.

Se attivi il collegamento dell'account per l'Azione consenti agli utenti di accedere all'azione su qualsiasi dispositivo con l'assistente integrato. Inoltre, gli utenti possono collegare il proprio account al tuo servizio al loro Account Google per offrire un'esperienza più personalizzata.

Se utilizzati con il collegamento degli account, i link all'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 usare i link all'Assistente avanzato, devi disporre di quanto segue:

Progetto Actions.
Link all'assistente attivato per l'azione.
(Facoltativo) Collegamento dell'account attivato per l'Azione.

Sviluppo locale

Per includere un link all'assistente avanzato sul tuo sito web, svolgi i seguenti passaggi:

Includi la seguente libreria JavaScript nella pagina, sostituendo <PROJECT_ID> con l'ID progetto di 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 riquadro incorporato "Prova con l'Assistente Google" Pulsante:
```
<google-assistant-link-group>
  
  <google-assistant-link href="{ASSISTANT_LINK_1}">
  </google-assistant-link>
  <google-assistant-link href="{ASSISTANT_LINK_2}">
  </google-assistant-link>
</google-assistant-link-group>
```
Nota: se un utente dell'assistente non ha eseguito l'accesso, viene attivato il primo link dell'assistente. l'assistente o reindirizza l'utente alla pagina della directory dell'assistente Azione.

Attivazione proattiva

Se vuoi che il flusso del link avanzato all'assistente 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 che gli utenti debbano selezionare il pulsante in linea alla loro prima visita.

Aggiungi un id al tag del gruppo di link 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 tua 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 avanzati all'Assistente Google funzionano solo per i domini di tua proprietà e verificati con Google. Durante lo sviluppo in locale, questo requisito viene ignorato perché devi accedere al progetto Actions, accedere al tuo Account Google e impostare il parametro di query dev=true nel tag di script.

  <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
  </script>

Per implementare l'Azione con i link avanzati all'assistente:

Registra il tuo dominio pubblico nella console Actions in Deploy > Verifica del brand > Collega sito.

Rimuovi il parametro di query 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 limitazioni e best practice affinché l'URL del link all'assistente possono essere distribuiti e referenziati all'esterno della directory o di altri servizi Google Google Cloud:

Continua a supportare tutti i tuoi link all'assistente. Se distribuisci un link all'assistente che si interrompe in seguito. Il tuo progetto Actions potrebbe essere contrassegnato come non integro e rimosso.
La pubblicazione di un link implica il supporto dell'attivazione da fonti non attendibili. Per qualsiasi Azioni collegate, devi confermare esplicitamente all'utente prima di eseguire qualsiasi azione di azione nel mondo reale. Ad esempio, un'azione che disattiva una smart home. deve chiedere all'utente di confermare "Vuoi disattivare $applianceName?"

In questo contesto, per azione reale si intende qualsiasi azione che influisce sulla servizi, dati, dispositivi, reti, computer o API. Ad esempio, l'invio di un email, eseguire una transazione, modificare lo stato di una smart home di Google Cloud, creare un abbonamento o aggiornare dei contenuti.