Retail è stato rinominato Vertex AI Search for Retail. Stiamo aggiornando i contenuti per riflettere il nuovo branding.

Questa pagina è stata tradotta dall'API Cloud Translation.

Registrare eventi utente in tempo reale

In questa pagina viene descritto come registrare gli eventi utente in tempo reale. Vertex AI Search per la vendita al dettaglio utilizza gli eventi utente in tempo reale per generare consigli e risultati di ricerca. Registrazione del maggior numero possibile di tipi di eventi utente con un prodotto valido informazioni migliora la qualità dei risultati.

Le procedure di registrazione in questa pagina si applicano sia a consigli e ricerche. Dopo la registrazione i dati, entrambi i servizi possono utilizzare questi eventi, quindi non è necessario caricarli gli stessi dati due volte se utilizzi entrambi i servizi.

Per maggiori dettagli sugli eventi utente, inclusi i tipi di eventi utente e JSON di esempio per tutti i tipi, consulta Informazioni sugli eventi utente.

Puoi registrare un evento utente in diversi modi:

Utilizzando un pixel JavaScript.
Inviando gli eventi direttamente all'API dal tuo server di backend.
Utilizzando un tag Tag Manager.

Puoi trovare esempi di registrazione di eventi utente di tipo detail-page-view per tutti i metodi indicati di seguito. Per altro tipi di eventi, consulta Informazioni sugli eventi utente.

Puoi anche importare eventi utente storici. Può richiedere una notevole quantità registrare dati sugli eventi utente sufficienti per addestrare i modelli. Puoi accelerare l'addestramento iniziale del modello importando i dati degli eventi utente dagli eventi passati in blocco. Consulta Importare gli eventi utente storici.

Se l'evento utente che stai registrando è la prima volta che un utente interagisce con un prodotto in base a consigli o risultati di ricerca forniti in precedenza, incluso un token di attribuzione, metriche sul rendimento. L'inclusione di un token di attribuzione è facoltativa ma vivamente consigliato. Per informazioni su come utilizzare l'attribuzione consulta Token di attribuzione.

Gli ID visitatore sono obbligatori per la registrazione degli eventi utente. Per informazioni sugli ID visitatore e sugli ID utente, consulta Informazioni sugli utenti.

Tutorial sulla scrittura di eventi utente

Questo tutorial mostra come registrare gli eventi utente utilizzando userEvents.write.

Per seguire una guida passo passo per questa attività direttamente nel Editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Prima di iniziare

Prima di registrare gli eventi utente, devi:

È stato creato un progetto Google Cloud con l'autenticazione configurata.
Una chiave API valida (per JavaScript Pixel o Tag Manager) oppure account di servizio con il ruolo Editor Retail assegnato se utilizzi l'API per scrivere strato Add.

Per ulteriori informazioni, vedi Prima di iniziare.

Best practice per la registrazione degli eventi utente

Vertex AI Search for Retail richiede dati di alta qualità per generare contenuti che consentono di analizzare i dati e visualizzare i risultati. Se i dati sono incompleti o errati, la qualità i risultati.

Quando registri gli eventi utente, assicurati di implementare le seguenti best practice pratiche:

Se registri gli eventi utente prima o durante l'importazione del catalogo, partecipare di nuovo a qualsiasi evento registrato prima dell'importazione del catalogo completata.

Puoi importare il catalogo prima, dopo o nello stesso momento in cui registri gli eventi utente. Svolgere queste attività in parallelo può far risparmiare tempo se il catalogo è grande e ci sono molti utenti eventi. Una volta completata l'importazione del catalogo, devi utilizzare l'API per partecipare di nuovo agli eventi caricati prima del completamento dell'importazione.

Vertex AI Search for Retail tenta di unire gli eventi utente registrati con dal catalogo dei prodotti al momento della creazione dell'evento utente. Solo eventi a cui partecipano correttamente vengono utilizzati per l'addestramento, quindi assicurati di rientrare eventi registrati prima dell'importazione completa del catalogo. Se un evento si riferisce a un articolo che non esiste nel catalogo, viene scartato o non associati ai prodotti corretti. Analogamente, se importi eventi utente del passato, il catalogo deve includere tutti i prodotti a cui fanno riferimento; puoi contrassegna i prodotti precedenti come OUT_OF_STOCK anziché rimuoverli dal catalogo.
Mantieni aggiornato il catalogo.

Quando registri eventi utente, il prodotto incluso nell'evento utente è collegata al tuo catalogo attuale. Se registri un evento per prodotto non presente nel catalogo corrente, non può essere usato per l'addestramento i tuoi modelli. Questo processo è chiamato "non unito" . Se hai registrato eventi prima del giorno il catalogo è stato importato, devi riunire eventi registrati durante l'importazione. Possedere alcuni sono previsti. Tuttavia, se la percentuale di eventi non uniti raggiunge il 5% o più del totale degli eventi utente, assicurati che il tuo catalogo data, riconnettere eventi registrati prima dell'aggiornamento completo del catalogo e scoprire il motivo per cui vengono creati gli eventi non uniti.

Puoi visualizzare gli eventi non uniti utilizzando i filtri eventi. Scopri di più.
Fornisci quante più informazioni possibile con gli eventi utente.

Ogni tipo di evento utente ha informazioni diverse richieste e accettato. Per saperne di più, consulta Informazioni sugli eventi utente.
Configura gli avvisi di Cloud Monitoring per sapere se le tue dei processi di registrazione degli eventi utente siano soggetti a interruzioni.
Per un'importazione collettiva di eventi utente, limita le dimensioni dei dati che stai importando.

Il completamento di un'importazione collettiva di eventi utente può richiedere fino a 24 ore.

Le dimensioni di ogni file devono essere 2 GB o inferiore. Tu può includere al massimo 100 in una singola richiesta di importazione. Un approccio consiste nell'importare solo gli eventi utente per un giorno alla volta.
Dopo un'importazione collettiva, rivedi i report sugli errori per assicurarti che i dati sono stati importati correttamente.
Quando importi i dati sugli eventi utente, includi un timestamp preciso per ogni utente ed evitare di importare eventi utente sequenziali con timestamp identici.

Fornisci il timestamp nel eventTime nel specificato da RFC 3339.
Se hai importato eventi utente errati, contatta il tuo Contatto di Vertex AI Search for Retail per informazioni su come risolvere il problema.
Se possibile, mantieni continui i dati sugli eventi utente.

Le lacune nei dati sugli eventi utente possono ridurre la qualità del modello.
Utilizza un modulo sicuro di un identificatore univoco per mantenere gli utenti anonimi per Vertex AI Search for Retail e di proteggere le risorse dei tuoi utenti privacy. È tua responsabilità oscurare le PII (informazioni che consentono l'identificazione personale) quali indirizzi di casa o email, provenienti dai tuoi dati.

Registrare eventi utente con un pixel JavaScript

L'esempio seguente registra un detail-page-view UserEvent tramite JavaScript pixel.

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "attributionToken": "attribution-token",
  "experimentIds": "experiment-id",
  "productDetails": [
      {
        "product": {"id": "123"}
      }
  ]
};

var _gre = _gre || [];
// Credentials for project.
_gre.push(['apiKey', 'api-key']);
_gre.push(['logEvent', user_event]);
_gre.push(['projectId', 'project-id']);
_gre.push(['locationId', 'global']);
_gre.push(['catalogId', 'default_catalog']);

(function() {
  var gre = document.createElement('script'); gre.type = 'text/javascript'; gre.async = true;
  gre.src = 'https://www.gstatic.com/retail/v2_event.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gre, s);
})();

</script>

Se eventi utente importati con Google Analytics 360 imposta visitorID sull'ID cliente Google Analytics. Tieni presente che L'ID client di Google Analytics è solo una parte del cookie _ga completo (ad esempio, l'ID client 123456789.123456789 fa parte del cookie _ga GA1.3.123456789.123456789).

Per ulteriori informazioni su come ottenere l'ID client, consulta documentazione di Google Analytics.

Di seguito è riportato un esempio abbreviato che mostra il formato per l'impostazione l'ID client in un evento utente. Sostituisci "G-XXXXXX" con il tuo ID monitoraggio di Google Analytics.

<script type="text/javascript">
var tracker = ga.getByName('G-XXXXXX');
var user_event = {
      "visitorId": tracker.get('clientId')
};
</script>

Registra gli eventi utente con il metodo `userEvents.write`

Puoi utilizzare lo userEvents.write per inviare gli eventi utente direttamente all'API dal server di backend.

Per registrare gli eventi utente, invia una richiesta POST all' userEvents.write e fornisci il corpo della richiesta appropriato.

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'visitorId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'experimentIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'productDetails': [{
           'product': {
             'id': 'abc'
           }
          }],
         'userInfo': {
           'userId': 'abc',
           'ipAddress': '8.8.8.8',
           'userAgent': 'Mozilla/5.0',
           'directUserRequest': true
         },
         'uri': 'http://example',
         'referrerUri': 'http://example',
         'pageViewId': 'currentPageUri'
}" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:write"

Java

public static UserEvent writeUserEvents(UserEvent eventToWrite)
    throws IOException, InterruptedException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  WriteUserEventRequest request = WriteUserEventRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEvent(eventToWrite)
      .build();

  UserEvent writtenUserEvent = userEventsClient.writeUserEvent(request);

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return writtenUserEvent;
}

Registrare gli eventi utente con Google Analytics 4

Puoi registrare i dati sugli eventi utente di Google Analytics 4 per Vertex AI Search for Retail.

Controllare l'origine dati

Assicurati che i dati sugli eventi utente che vuoi importare siano corretti formattato.

Per una tabella dei campi di Google Analytics 4 che Vertex AI Search for Retail e i campi di Vertex AI Search for Retail a cui vengono associati, consulta i campi degli eventi utente di Google Analytics 4.

Per tutti i parametri evento di Google Analytics, consulta Documentazione di riferimento per gli Eventi Google Analytics.

Verifica quanto segue:

Se importi eventi di acquisto, alcuni dei pod di Vertex AI Search for Retail richiedono che i report sugli eventi includano i codici valuta. Controlla i parametri evento purchase nella documentazione di Google Analytics.
Se prevedi di importare search eventi, i report sugli eventi includono la ricerca query.

L'importazione di search eventi è supportata, ma search eventi non vengono mappati da Google Analytics 4 allo stesso modo degli altri tipi di eventi. perché Google Analytics 4 non supporta in modo nativo Tipo di evento search di Vertex AI Search for Retail. Durante l'importazione, search eventi vengono create da Google Analytics 4 combinando le informazioni dai parametri evento view_item_list e search_term.

Controlla i parametri evento search nella documentazione di Google Analytics.

Registrare gli eventi di Google Analytics 4

Registra un evento utente includendo i dati JSON non elaborati codificati nell'URL per l'evento nel tuo al metodo userEvents.collect.

Per il parametro prebuilt_rule, utilizza il valore ga4_bq.

Per la leggibilità, il seguente esempio di utilizzo della chiamata userEvents.collect imposta prima GA4_EVENT come variabile contenente i dati JSON non elaborati per un esempio . La chiamata userEvents.collect nell'esempio esegue quindi la codifica URL dell'evento usando la variabile GA4_EVENT.

Per semplificare la codifica degli URL in un secondo momento, puoi impostare GA4_EVENT come variabile contenenti dati sugli eventi. Questo esempio mostra un evento add-to-cart.

GA4_EVENT='{
  "event_timestamp": 1622994083878241,
  "event_name": "add_to_cart",
  "user_pseudo_id": "352499268.1622993559",
  "items": [
    {
      "item_id": "11",
      "price": 29.99,
      "quantity": 3
    }
  ],
  "event_params": [
    {
      "key": "currency",
      "value": {
        "string_value": "CAD"
      }
    }
  ],
  "user_id": "Alice"
}'

Effettua una chiamata userEvents.collect che includa i dati JSON non elaborati codificati nell'URL di un evento utente:

curl \
-G \
--data-urlencode "raw_json=${GA4_EVENT}" \
-i \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:collect?key=EXAMPLEKEY1&prebuilt_rule=ga4_bq'"

Registrare gli eventi utente con Google Tag Manager

Tag Manager offre un modo per gestire e testare più tag senza dover modifiche al codice lato server del tuo sito.

Alcune decisioni che prendi durante la configurazione dipendono dall'uso o meno Google Analytics ed e-commerce di Google Analytics. L'e-commerce di Google Analytics può Essere implementata utilizzando Google Analytics 4 o l'E-commerce avanzato. Il tag Cloud Retail supporta entrambi.

Né Google Analytics né l'e-commerce di Google Analytics sono richiesti; se non utilizzarli, puoi configurare Variabile - E-commerce durante la creazione il tag Cloud Retail o completare manualmente il codice del livello dati del sito dopo la creazione del tag.

L'e-commerce di Google Analytics è una configurazione aggiuntiva Google Analytics che trasmette titoli, ID, prezzi e transazioni dei prodotti. e altri dati strutturati di e-commerce a Google Analytics. Vertex AI Search for Retail può utilizzare automaticamente l'e-commerce di Google Analytics livello dati. Se lo hai già impostato, la configurazione può essere più semplice. Se non hai configurato l'e-commerce di Google Analytics per ma vuoi utilizzarlo, visualizza ulteriori dettagli e configurazione istruzioni nella guida per gli sviluppatori GA4 o nelle Guida per gli sviluppatori sull'E-commerce avanzato.

Utilizza questa procedura una tantum per configurare un tag Cloud Retail in Tag Manager per la registrazione di eventi utente.

Creare una variabile ID visitatore

Il valore visitorId serve per il monitoraggio degli utenti. visitorId è in genere un ID sessione ed è obbligatorio per tutti gli eventi. Imposta un che imposta gli ID sessione su visitorId.

Se utilizzi Google Analytics, puoi utilizzare lo ID visitatore di Google Analytics. Per configurare questa funzionalità, utilizza quanto segue per sostituire il valore dell'ID visitatore per il tag Cloud Retail. Questa mappa il cookie proprietario "_ga" a una variabile di Tag Manager denominata "ID visitatore GA". Puoi fare lo stesso per qualsiasi cookie di ID sessione. non ha provenienti da Google Analytics.

Questa procedura presuppone l'utilizzo di Google Analytics. In caso contrario, puoi utilizzare un altro cookie o un'altra variabile oppure ottenere l'ID visitatore dalla Livello dati cloud_retail.

Per impostare il valore visitorID su una variabile per il tag Cloud Retail:

In Tag Manager, vai alla scheda Variabili e fai clic su Nuova per creare una nuova .
Assegna un nome alla variabile nella parte superiore della finestra di dialogo, ad esempio "GA advertiserId".
Inserisci le impostazioni della variabile.

Puoi utilizzare l'ID client o l'ID cookie per impostare come origine del visitatore ID. Utilizza sempre un'origine ID visitatore coerente quando importi dati storici e di eventi utente in tempo reale.
ID client
In BigQuery di Google Analytics 360, è mappata al campo clientID nella Schema di esportazione BigQuery per Universal Analytics. In Google Analytics 4, questa variabile viene mappata Campo user_pseudo_id nel Schema di esportazione BigQuery per Google Analytics 4.
1. Imposta Tipo di variabile su JavaScript personalizzato.
2. Inserisci il seguente script nel campo JavaScript personalizzato.
  
  Sostituisci "G-XXXXXX" con il tuo ID monitoraggio di Google Analytics. Per trovare ID monitoraggio, consulta la sezione Che cosa è successo al mio ID monitoraggio? Per ulteriori informazioni su come ottenere l'ID client, consulta documentazione di Google Analytics.
```
function() {
 var tracker = ga.getByName('G-XXXXXX');
 return tracker.get('clientID');
}
```
3. Fai clic su Salva per salvare la variabile.
ID cookie
1. Scegli Cookie proprietario come tipo di variabile.
2. Nel campo Nome cookie, inserisci _ga.
3. Fai clic su Valore formato, seleziona Converti in... e inserisci "" (una stringa vuota).
4. Fai clic su Salva per salvare la variabile.
  
  Viene mappato il cookie originale "_ga" a una variabile Tag Manager chiamato "GA advertiserId".

Poi, crea un tag Cloud Retail in Tag Manager. Questo tag utilizza la variabile ID visitatore appena creata.

Creare un tag di Google Tag Manager

Impostare un tag in Tag Manager per inviare informazioni sugli eventi utente a Vertex AI Search for Retail.

Accedi a Tag Manager. e seleziona il contenitore per il tuo sito.
Vai alla scheda Tag e fai clic su Nuovo per aggiungere un nuovo tag.
Assegna un nome al tag nella parte superiore del riquadro (il segnaposto è Variabile senza titolo), ad esempio "Vertex AI Search for Retail".
Fai clic su Configurazione tag e scegli il tag Cloud Retail per apri il riquadro di configurazione dei tag.
Inserisci la chiave API.

Utilizza la chiave che hai creato durante la configurazione di Vertex AI Search for Retail.

Le chiavi API sono disponibili nel sito web delle API e Servizi > Credenziali nella console Google Cloud.
Inserisci il numero del progetto Google Cloud in cui Vertex AI Search for Retail è abilitato.

Il numero del progetto è disponibile nella dashboard della console Google Cloud.
Per il campo Origine dati evento utente:
- Livello dati (consigliato): seleziona se la tua implementazione deve essere uno di le seguenti:
  - Hai implementato l'e-commerce di Google Analytics tramite Tag Manager. Riutilizzare il livello dati come origine dati degli eventi anziché compilarne uno nuovo. che utilizza la piattaforma Google Analytics 4, se presente. In caso contrario, utilizza l'E-commerce avanzato di UA. Con questa origine dati, puoi registrare solo add-to-cart, purchase-complete, detail-page-view e search eventi. search eventi vengono registrati utilizzando Impressioni e-commerce combinate con query di ricerca (vedi Crea una variabile query di ricerca).
  - Utilizzi l'e-commerce di Google Analytics e puoi completare manualmente i dati il codice livello. Consulta le Guida per gli sviluppatori di Tag Manager.
- Variabile - Cloud Retail: seleziona questa opzione per compilare un Tag Manager con i campi obbligatori per Vertex AI Search for Retail. Potresti scegli questa opzione se non utilizzi l'e-commerce di Google Analytics oppure se L'e-commerce di Google Analytics non dispone dei dati necessari per Vertex AI Search for Retail. Se stai passando a questa origine dal livello dati precedente: Cloud Retail, crea anche una variabile di livello dati con chiave cloud_retail e associalo a questa variabile - Cloud Retail. .
- Variabile - E-commerce: seleziona questa opzione se non utilizzi l'e-commerce di Google Analytics nel livello dati e non puoi farlo per compilare il codice del livello dati.
  
  Nel campo Leggi i dati di e-commerce dalla variabile utente che viene visualizzato, scegli una variabile. Ciò consente a Vertex AI Search for Retail di leggere Dati sugli eventi utente di e-commerce di Google Analytics da una variabile personalizzata che crei.
  
  La variabile deve corrispondere al formato documentato nei Guida per gli sviluppatori di GA4 o la Guida per gli sviluppatori sull'e-commerce avanzato. Per creare una variabile nel formato corretto, puoi utilizzare Strumento per la creazione di oggetti di e-commerce avanzato un modello di variabili personalizzate Galleria modelli della community di Tag Manager. I modelli della community non vengono gestiti da Google. Per usare questo modello, consulta la pagina della galleria del generatore di oggetti di e-commerce avanzato per la documentazione e altre risorse.
Fai clic sul pulsante + Sovrascrivi un valore nel messaggio UserEvent.
Per Selettore di campi, seleziona visitorId come campo e per Valore campo, seleziona la nuova variabile ID visitatore che hai creato in Crea una variabile ID visitatore.
Fai clic su Salva.

Viene creato il tag Cloud Retail.

Opzioni dell'origine dati precedente

In precedenza, Livello dati - E-commerce e Livello dati - Cloud Retail erano disponibili come opzioni di origine dati. Queste opzioni precedenti non sono disponibili nelle nuove i tag. Se trasferisci un tag esistente a una nuova origine dati, visualizza l'anteprima con Tag Manager per verificarlo prima e deployment continuo. Quando esegui il passaggio:

Se hai utilizzato Livello dati - E-commerce, puoi passare a Livello dati. Viene utilizzato lo schema di Google Analytics 4, se presente. In caso contrario, utilizza l'E-commerce avanzato di UA.
Se hai utilizzato Livello dati - Cloud Retail, passa all'opzione Variabile - Cloud Retail. Crea una variabile di livello dati con la chiave cloud_retail e associalo all'opzione Variabile - Cloud Retail.

A seguire:

Se utilizzi la ricerca, creare una variabile per le query di ricerca e collegarla al nuovo del tag.
Crea attivatori di eventi per il tag.

Creare una variabile di query di ricerca

Se utilizzi la ricerca, puoi creare una variabile in Tag Manager per le query di ricerca e collegalo al tag Cloud Retail. Ciò consente a Vertex AI Search for Retail di ottenere query di ricerca da Analisi.

I tipi di variabili che crei dipendono dall'origine dati sugli eventi utente.

Variabile - E-commerce o livello dati con lo schema E-commerce di Google Analytics: Crea una variabile URL o elemento DOM in Tag Manager e al tag Cloud Retail. Inoltre, abilita l'opzione per i tuoi per utilizzare le impressioni e-commerce di Google Analytics al fine di creare eventi di ricerca.
Variabile - Cloud Retail o un livello dati completato manualmente: Crea una variabile URL o elemento DOM in Tag Manager e al tag Cloud Retail. Per determinare se il tipo di evento utente è search, devi anche:
- Crea una variabile di tipo costante per l'evento di ricerca e allegarlo al tag.
- Imposta il tipo di evento di ricerca nel livello dati o nella variabile Cloud Retail.

Creare e collegare una variabile di Tag Manager per le query di ricerca

Se utilizzi la ricerca, puoi creare un URL, un elemento DOM o un variabile JavaScript che verrà compilata con le query di ricerca inserite nella tua sito.

In alternativa a questa procedura, puoi configurare il livello dati per fornire le informazioni sulle query di ricerca. Tuttavia, puoi scegliere di utilizzare Tag Manager variabili se non hai accesso al livello dati o preferisci non configurare il livello dati.

Puoi creare una variabile di tipo URL, una variabile di tipo di elemento DOM o una variabile variabile JavaScript (pagina). Il tipo di rete che crei e come lo configuri, dipende dall'implementazione del sito:

Una variabile URL ottiene le query di ricerca dagli URL dei risultati di ricerca del tuo sito. Utilizza questa variabile se il tuo sito include la stringa di query nell'URL del suo sito risultati di ricerca.
Una variabile elemento DOM ottiene le informazioni sulle query di ricerca dagli Document Object Model (DOM). Non è necessario modificare il DOM per utilizzare questo . Tuttavia, dovresti essere in grado di leggere e comprendere il DOM per configura correttamente la variabile.
Una variabile JavaScript personalizzato restituisce dati formattati tramite un linguaggio JavaScript. personalizzata. È utile se hai dei dati esistenti che vuoi formattare in lo schema Cloud per la vendita al dettaglio o l'e-commerce.

Innanzitutto, crea una variabile Tag Manager di tipo URL, elemento DOM o Personalizzata JavaScript:

In Tag Manager, vai alla scheda Variabili e fai clic su Nuova per creare una nuova .
Assegna un nome alla variabile nella parte superiore della finestra di dialogo, ad esempio "variabile_ricerca".
Inserisci le impostazioni della variabile:
Tipo di URL
1. Imposta Tipo di variabile su URL.
2. Imposta Tipo di componente su Query.
3. Se specifichi una chiave di query, impostala sulla chiave che precede la query di ricerca nell'URL.
  
  Ad esempio, se l'URL è http://example.com/?q=shoes, la query è q. In questo esempio, il valore della variabile viene impostato su shoes.
Tipo di elemento DOM
1. Imposta Tipo di variabile su Elemento DOM.
2. Imposta Metodo di selezione e inserisci l'ID o l'ID elemento della query di ricerca. selettore elementi.
  
  Questa impostazione dipende dall'utilizzo o meno di un ID elemento o di un valore aggiunto nel sito selettore CSS per identificare la query di ricerca.
3. Se specifichi un attributo, impostalo sull'attributo che contiene il termine della query di ricerca.
  
  Ad esempio, se la query di ricerca nel DOM è <id="search" value="shoes">, l'attributo è value. Nel in questo esempio, il valore della variabile verrebbe impostato su shoes.
Tipo JavaScript personalizzato
1. Imposta Tipo di variabile su JavaScript personalizzato.
2. Sostituisci le variabili nel codice seguente e incollale nella Riquadro JavaScript personalizzato.
3. Nel riquadro JavaScript personalizzato, aggiungi un codice JavaScript che restituisca un in uno schema Retail.
  
  Il seguente codice campione trasforma i dati in una variabile Ecommerce Items esistente nell'array productDetails utilizzato dallo schema di Vertex AI Search for Retail e restituisce un evento completo. Per usare questo codice, sostituisci Ecommerce Items, Search Query e Search Filter con nell'implementazione di Tag Manager.
```
function () {

  var retail;
  var items = [];

  for (var i = 0; i < {{Ecommerce Items}}.length; i++) {
    var item = {'product':
                {
                  'id': {{Ecommerce Items}}[i].item_id
                }
               };

    items.push(item);
  }

  retail = {
    'eventType': 'search',
    'searchQuery': '{{Search Query}}',
    'filter': '{{Search Filter}}',
    'productDetails': items
  }

  return retail;
}
```
Fai clic su Salva per salvare la variabile.

Quindi, collega la variabile al tag Cloud Retail:

Il giorno Tag Manager Tag, fai clic sul tag Cloud Retail per modificarlo.
Se l'origine dati sugli eventi utente del tuo tag è Variabile - E-commerce o utilizzi Il livello dati con lo schema di e-commerce di Google Analytics, seleziona la casella di controllo Utilizza le impressioni dell'e-commerce avanzato per creare gli eventi di ricerca.

In questo modo Vertex AI Search for Retail può determinare se il tipo di evento utente è search in base ai dati di ricerca che riceve da questo tag.
Nella sezione Dati eventi utente, fai clic sull'icona + Sovrascrivi un valore nel messaggio UserEvent.
Seleziona searchQuery nel selettore di campi e imposta la query di ricerca come Valore campo.
Salva il tag.

A seguire:

Se hai scelto di utilizzare una variabile Cloud Retail o un dato compilato manualmente come origine dell'evento utente per il tag Cloud Retail, consulta Crea e collega una variabile costante.
Crea attivatori di eventi per il tag.

Crea e collega una variabile costante

Puoi utilizzare questa procedura se scegli Variabile - Cloud Retail o livello dati completato manualmente come origine evento utente per Cloud Retail del tag.

Creare una variabile di tipo costante per gli eventi di ricerca e impostarla come utente sul tuo tag Cloud Retail consente a Vertex AI Search for Retail di determina se un tipo di evento utente è search.

In alternativa a questa procedura, puoi specificare l'evento utente search il tipo tramite il livello dati o la variabile Cloud Retail che usi come origine evento del tag. In caso contrario, segui questi passaggi per impostare il tipo di evento.

Innanzitutto, crea una variabile di tipo costante:

In Tag Manager, vai alla scheda Variabili e fai clic su Nuova per creare una nuova .
Assegna un nome alla variabile nella parte superiore della finestra di dialogo, ad esempio "constante_ricerca".
Imposta Tipo di variabile su Costante.
Inserisci search nel campo Valore
Fai clic su Salva per salvare la variabile.

Quindi, collega la variabile al tag Cloud Retail:

Il giorno Tag Manager Tag, fai clic sul tag Cloud Retail per modificarlo.
Nella sezione Dati eventi utente, fai clic sull'icona + Sovrascrivi un valore nel messaggio UserEvent.
Seleziona eventType nel selettore di campi e imposta la query di ricerca come Valore campo.
Salva il tag.

Poi, crea gli attivatori di eventi per il tag.

Creare attivatori di eventi per il tag Tag Manager

Creare trigger per tutti i tipi di eventi utente per i modelli di Vertex AI Search for Retail .

I tag di Tag Manager devono avere attivatori che controllano quando il tag deve essere "licenziato" sul sito. I trigger restano in ascolto del momento in cui si verificano eventi (ad esempio, un utente visualizza la home page o aggiunge un articolo al carrello) e richiede il tag a le informazioni sugli eventi utente a Vertex AI Search for Retail.

Tag Manager fornisce alcuni attivatori standard. Ad esempio: Finestra caricata è un trigger per gli eventi detail-page-view. Per maggiori dettagli su ciascun tipo, consulta la sezione Tipi di attivatore in Tag Manager documentazione.

In genere imposti il tag in modo che si attivi quando un utente visualizza qualsiasi pagina contenente il eventi necessari per Vertex AI Search for Retail (come la home page, il dettaglio del prodotto pagine del carrello, pagine del carrello o pagina di pagamento completata). In questi casi, il tag deve si attivano dopo il caricamento della pagina, in modo che i cookie siano disponibili e tutti i livelli dati vengono compilate. A questo scopo, imposta gli attivatori in modo che si attivino su Finestra caricata o Pronto per DOM.

Potrebbe essere necessario attivare il tag quando viene eseguita un'azione anziché in caricamento pagina (ad esempio, se un utente che aggiunge un articolo a un carrello non ne forza la ricarica). In questi casi, puoi configurare l'azione di clic sul tuo sito per invia contemporaneamente gli aggiornamenti al livello dati e associa l'attivatore a quell'azione.

Ad esempio, se hai creato un trigger per gli eventi add-to-cart, puoi scegliere il tipo di attivatore Click - Just Links e impostarlo in modo che si attivi in base all'ID clic. (in questo esempio, addtocart). Devi quindi configurare il collegamento addtocart su tuo sito per aggiornare anche il livello dati con nuovi valori quando fai clic su:

  <a id="addtocart" href="javascript:void(0);"
         onclick="dataLayer.push({
                  'cloud_retail': {
                  'eventType': 'add-to-cart',
                  'visitorId': '456',
                  'cartId': 'mobile',
                  'productDetails': [{
                  'product': {
                  'id': '54321'
                  },
                  'quantity': 1
                  }]}});">Add to Cart</a>

Per alcuni eventi utente, devi creare un trigger personalizzato. In genere, crei un attivatore personalizzato in Tag Manager utilizzando il nome evento utente. Se non puoi modificare il codice front-end, puoi creare un trigger personalizzato utilizzando JavaScript . Per ulteriori informazioni sugli attivatori personalizzati, consulta Trigger di eventi personalizzati.

Per creare attivatori in Tag Manager:

Se non hai configurato trigger esistenti: Creare nuovi attivatori per il tag Tag Manager
Se hai già configurato gli attivatori e-commerce di Google Analytics: puoi riutilizzare gli attivatori configurati per l'e-commerce di Google Analytics anziché per crearne di nuovi. Consulta Riutilizzare gli attivatori E-commerce di Google Analytics.

Creare nuovi attivatori per il tag Tag Manager

Se non utilizzi l'e-commerce di Google Analytics, crea nuovi attivatori di evento per qualsiasi gli eventi utente richiesti dai modelli di Vertex AI Search for Retail. Quindi, associa il nuovo con il tag Cloud Retail che hai creato in Tag Manager.

Prima di iniziare con i passaggi seguenti, assicurati di aver creato un account Cloud Retail in Tag Manager. Consulta Creare un tag di Tag Manager.

Innanzitutto, crea i trigger. Ripeti questa procedura per tutti gli eventi utente I modelli di Vertex AI Search for Retail richiedono:

In Tag Manager, Nella pagina Trigger, fai clic su Nuovo > Configurazione attivatore.
Scegli il tipo di attivatore applicabile l'evento utente per cui stai creando un trigger.
Salva il trigger.

Successivamente, associa i nuovi trigger al tag Cloud Retail. Questo è procedura una tantum:

Il giorno Tag Manager Tag, fai clic sul tag Cloud Retail per modificarlo.
Fai clic su Attivazione, seleziona i nuovi attivatori e fai clic su Aggiungi.
Salva il tag.

A questo punto, visualizza l'anteprima del tag e configurare il monitoraggio degli errori di registrazione degli eventi e di altri problemi per per assicurarti che i dati continuino a essere ricevuti correttamente.

Se utilizzi il livello dati cloud_retail come origine degli eventi utente, assicurati per configurare il livello dati.

Riutilizzare gli attivatori E-commerce di Google Analytics

Se hai implementato l'e-commerce di Google Analytics tramite Tag Manager, Riutilizza gli attivatori evento dell'e-commerce di Google Analytics per Vertex AI Search for Retail.

Con questa origine dati, puoi registrare solo add-to-cart, purchase-complete, detail-page-view e search eventi. search eventi vengono registrati utilizzando Impressioni e-commerce combinate con query di ricerca (vedi Crea una variabile query di ricerca).

La seguente tabella mostra il modo in cui Google Analytics e-commerce e Gli eventi di E-commerce avanzato vengono mappati agli eventi di Vertex AI Search for Retail.

Google Analytics 4	E-commerce avanzato	Vertex AI Search per il retail
`add_to_cart`	`add`	`add-to-cart`
`purchase`	`purchase`	`purchase-complete`
`view_item`	`detail`	`detail-page-view`
`view_item_list` o `view_search_results`	`impressions`	`search` (se combinata con il campo `searchQuery`)

Prima di iniziare questa procedura, assicurati di avere:

Impostazione di un tag in Tag Manager di tipo Google Analytics - Universal Analytics o Google Analytics - Evento GA4 e attivato E-commerce avanzato o GA4. Consulta la documentazione di Tag Manager e i Guida per gli sviluppatori di GA4 o la Guida per gli sviluppatori sull'e-commerce avanzato per maggiori dettagli.
Configurare il tag di E-commerce avanzato o GA4 in Tag Manager per attivare gli eventi utente che prevedi di registrare per Vertex AI Search for Retail.
Hai creato un tag Cloud Retail in Tag Manager, con Livello dati o "Variabile - E-commerce" come origine dati sugli eventi utente (vedi Crea un tag Tag Manager.

Per riutilizzare gli attivatori E-commerce di Google Analytics:

Il giorno Tag Manager Tag, fai clic sul tag e-commerce di Google Analytics. (tipo di tag Google Analytics - Universal Analytics o Google Analytics - evento GA4) per modificarlo.
In Impostazioni avanzate > Sequenza tag, seleziona Attiva un tag dopo <Nome tag di e-commerce avanzato o GA4> incendi.
Seleziona il tag Cloud Retail come Tag di pulizia.

Seleziona Non attivare <Nome tag Cloud Retail> if <Nome tag di E-commerce avanzato o GA4> non funziona o è in pausa.
Salva il tag.

Se utilizzi il livello dati cloud_retail come origine degli eventi utente, assicurati per configurare il livello dati.

Utilizzare il livello dati `cloud_retail` con Tag Manager

Se hai creato il tag Cloud Retail in Tag Manager per utilizzare il parametro Livello dati cloud_retail come origine dell'evento utente, configura il dataLayer nel codice HTML sorgente, come descritto nella sezione Guida per gli sviluppatori di Tag Manager.

Informazioni sul livello dati

La maggior parte dei tag di Tag Manager richiede dati che cambiano in base all'utente o della pagina (come ID utente o ID prodotto). Per il tag Cloud Retail, i dati devono essere esposti in modo strutturato tramite un livello dati, di modo che Tag Manager possono utilizzarlo.

Il livello dati è un oggetto JavaScript che in genere viene aggiunto a una pagina utilizzando tramite codice lato server o front-end tramite HTML o modello. Se una pagina è configurata con il livello dati, conterrà codice simile al seguente:

dataLayer = dataLayer || [];
dataLayer.push({
  'cloud_retail': {
    'eventType': 'home-page-view',
    'visitorId': 'visitor_a',

    'userInfo': {
      'userId': '789'
    },
  }
});

Questo codice crea un oggetto dataLayer e assegna la struttura cloud_retail come elemento array.

Campi obbligatori nel livello dati `cloud_retail`

Nella sezione Informazioni sugli eventi utente sono elencati tutti i campi obbligatori e tutti gli esempi per tipi di eventi che devono essere passati al livello dati cloud_retail.

Il codice o i modelli lato server devono avere i tag di script corretti su ogni pagina da cui vuoi inviare gli eventi. Dopo che l'oggetto dataLayer viene compilate correttamente su ogni pagina, dovresti essere in grado di testare Cloud Retail del tag.

Alcuni campi come visitorId sono obbligatori per UserEvent ma potrebbero non essere disponibili durante la compilazione del livello dati. Ad esempio: visitorId può derivare dal cookie dell'utente o experimentIds dal il framework della sperimentazione A/B. In questo caso, utilizza una variabile per sovrascrivere nel tag di Tag Manager.

Puoi sovrascrivere i seguenti campi:

visitorId
userInfo.userId
attributionToken
experimentIds

Per informazioni su come sovrascrivere un campo UserEvent in Tag Manager, consulta Impostazione del campo visitorID in Tag Manager, che definisce sovrascrivendo il valore del campo visitorId con un valore definito dall'utente .

L'esempio seguente mostra il livello dati da includere nel pagina per un detail-page-view UserEvent utilizzando Tag Manager:

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'cloud_retail': {
      'eventType' : 'detail-page-view',
      'visitorId': 'visitor_a',
      'userInfo': {
          // The user and visitor ID fields can typically be
          // be populated from a client-side JavaScript
          // variable such as a cookie. If you set the user
          // and/or visitor ID values from the server,
          // populate the `userID`.
          'userId': 'user_a'
      },
      'attributionToken': 'attribution-token',
      // In most cases, the experiment ID field is populated from a
      // client side JavaScript variable as defined by the experiment
      // manager.
      // If you set the experiment ID value from the server,
      // populate the `experimentIds` field here.
      'productDetails': [
            {
              'product': {'id': '123'}
            }
      ],
    // You can use the 'cloud_retail' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

Visualizzare l'anteprima del tag di Tag Manager

La modalità di anteprima di Tag Manager ti consente di testare i nuovi tag prima della pubblicazione al tuo sito pubblicato.

Per ulteriori dettagli sulla modalità di anteprima, consulta la documentazione di Tag Manager per la modalità Anteprima.

Per verificare la corretta attivazione del tag, procedi nel seguente modo.

Nella pagina Panoramica di Tag Manager, fai clic su Anteprima.

La modalità di anteprima di Tag Manager si apre in una nuova scheda del browser.
Inserisci le informazioni sul sito e fai clic su Avvia per avviare Tag Assistant.

Nella scheda del browser corrente, si avvia Tag Assistant e il sito si apre in una nuova scheda.
Sul tuo sito, visita le pagine in cui deve essere attivato il tag Cloud Retail.
Verifica che Tag Assistant elenca il tag Cloud Retail nella sezione Tag. nella sezione Tag attivati.
In Tag Assistant, vai alla scheda Livello dati e verifica che sia vengono visualizzati i valori del livello dati di cloud_retail o di e-commerce.

Verifica la presenza di errori nei tag

Se alcuni campi non sono corretti o mancano quando visualizzi l'anteprima del tag, il tag in genere restituisce anche un errore, a meno che non si attivi affatto.

Puoi consultare la pagina Monitoring nella Cerca la console Retail per trovare errori. Questa pagina registra la maggior parte degli errori, tranne per gli errori di sintassi, che in genere compaiono solo nei risultati della richiesta.

Puoi seguire questi passaggi per utilizzare Chrome DevTools al fine di verificare la presenza di eventuali errori generati, inclusi gli errori di sintassi.

Attivare la modalità di anteprima in Tag Manager per il tuo sito in un browser Chrome e visita le pagine in cui deve essere attivato il tag Cloud Retail.
Con la modalità di anteprima aperta, apri DevTools e fai clic sulla scheda Rete.
Ricarica la pagina.
In DevTools, cerca userEvent.

La scheda Rete mostra l'evento userEvent:collect e il relativo codice di stato.
- Una risposta 200 indica che il tag è in buono stato.
- Altre risposte, come un errore 400 e l'evidenziazione dell'evento in rosso, indicano che è necessario eseguire il debug.
Fai doppio clic sul nome dell'evento per eseguire la richiesta e mostrare una risposta completa con altre informazioni sull'errore.

Ad esempio, potresti visualizzare un errore 400 contenente il messaggio "'visitorId" è obbligatorio e non può essere vuoto", a indicare che il valore visitorId non è stato impostato in modo corretto.
Se non viene attivato alcun userEvent, controlla la sintassi nella scheda Console di DevTools. nel livello dati.

Registrare gli eventi utente con il tagging lato server

Il tagging lato server ti consente di eseguire il deployment di un singolo container lato server con molti client downstream. Questo crea un'unica fonte attendibile sul client con molti consumatori lato server. Questa architettura sposta il carico sul web e nel server, rendendolo desiderabile per gli utenti che vogliono ottimizzare il rendimento dei loro siti web.

L'altro vantaggio del tagging lato server è che un singolo tag lato server e supporta anche molti client upstream, ad esempio sia web che mobile. Scopri come configurare il tagging lato server.

Vertex AI Search for Retail fornisce il suo tag lato server nativo.

Il tag lato server di Cloud Retail richiede e accetta parametri simili a quelli il tag web Cloud Retail, ad esempio:

Numero progetto
Chiave API (per l'autenticazione)
Override per campi chiave come visitorId e searchQuery

La principale differenza tra la versione server e la versione web dell'ambiente Il tag retail è che non puoi definire l'origine dati. L'origine dati per tag server è uno stream di dati inviato dal tag Google nello schema GA4.

Configura il tag Cloud Retail

Monitora l'integrità dell'importazione

La registrazione corretta degli eventi utente è importante per ottenere una qualità elevata che consentono di analizzare i dati e visualizzare i risultati. Devi monitorare i tassi di errore della registrazione degli eventi e adottare un'azione, se necessario. Per ulteriori informazioni, vedi Configura avvisi per i problemi di caricamento dei dati.

Visualizzare gli eventi registrati

Visualizza le metriche di integrazione degli eventi nella scheda Eventi della console di Search for Retail Dati. In questa pagina sono mostrati tutti gli eventi scritti o importati nell'ultimo anno. Le metriche possono richiedere fino a un'ora prima di apparire nella console dopo una corretta importazione dati.

Vai alla pagina Dati

Passaggi successivi

Scopri di più sugli eventi utente.
Riunire gli eventi se sono stati registrati prima del completamento dell'importazione del catalogo.
Scopri di più sull'importazione e sulla gestione degli eventi utente.
Inizia a ricevere previsioni.
Monitorare e risolvere i problemi relativi al caricamento dei dati i processi di machine learning.
Scopri di più su Tag Manager.