Registra gli eventi utente in tempo reale

Questa pagina descrive come registrare gli eventi utente in tempo reale. Vertex AI Search per il retail utilizza gli eventi utente in tempo reale per generare consigli e risultati di ricerca. Registrare quanti più tipi di evento utente con informazioni valide sui prodotti aumenta la qualità dei risultati.

Le procedure di registrazione in questa pagina si applicano sia ai consigli sia alla ricerca. Dopo aver registrato i dati, entrambi i servizi sono in grado di utilizzare questi eventi, quindi non è necessario caricare gli stessi dati due volte se utilizzi entrambi i servizi.

Per informazioni dettagliate sugli eventi utente, inclusi i tipi di eventi utente e il JSON di esempio per tutti i tipi, consulta Informazioni sugli eventi utente.

Puoi registrare un evento utente in diversi modi:

Di seguito puoi trovare esempi di registrazione di eventi utente di tipo detail-page-view per tutti questi metodi. Per altri tipi di eventi, consulta Informazioni sugli eventi utente.

Puoi anche importare gli eventi utente storici. Può essere necessario molto tempo per registrare dati sugli eventi utente sufficienti per addestrare i modelli. Puoi accelerare l'addestramento iniziale del modello importando collettivamente i dati sugli eventi utente da eventi passati. 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 un consiglio o ai risultati di ricerca forniti in precedenza, l'inclusione di un token di attribuzione attiva le metriche sul rendimento. L'inclusione di un token di attribuzione è obbligatoria per il funzionamento di Vertex AI Search per il retail. Per informazioni su come utilizzare i token di 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 sulle informazioni utente.

Registrare gli eventi utente con il tagging lato server

Il tagging lato server ti consente di implementare un singolo contenitore lato server con molti client a valle. In questo modo viene creata un'unica fonte attendibile lato client, con molti consumatori lato server. Questa architettura sposta il carico dal web al server, ed è quindi ideale per gli utenti che vogliono massimizzare il rendimento dei propri siti web.

L'altro vantaggio del tagging lato server è che un singolo tag lato server può supportare anche molti client a monte, ad esempio sia web che mobile. Scopri come configurare il tagging lato server.

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

Il tag lato server Cloud Retail richiede e accetta parametri simili al tag web Cloud Retail, ad esempio:

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

La differenza principale tra la versione server e la versione web del tag Cloud Retail è che non puoi definire l'origine dati. L'origine dati per i tag server è uno stream di dati inviato dal tag Google nello schema GA4.

Configurare il tag Cloud per la vendita al dettaglio

Tutorial sulla scrittura di eventi utente

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

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Prima di iniziare

Prima di registrare gli eventi utente, devi disporre di:

  • Un progetto Google Cloud creato con l'autenticazione configurata.

  • Una chiave API valida (per JavaScript Pixel o Tag Manager) o un account di servizio valido con il ruolo Editor di vendita assegnato se utilizzi l'API per scrivere direttamente.

    Per ulteriori informazioni, consulta Prima di iniziare.

Best practice per la registrazione degli eventi utente

Vertex AI Search per il retail richiede dati di alta qualità per generare risultati di alta qualità. Se i dati sono incompleti o errati, la qualità dei risultati peggiora.

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

  • Se registri gli eventi utente prima o durante l'importazione del catalogo, riassocia gli eventi registrati prima del completamento dell'importazione del catalogo.

    Puoi importare il catalogo prima, dopo o contemporaneamente alla registrazione degli eventi utente. Eseguire queste attività in parallelo può farti risparmiare tempo se il catalogo è di grandi dimensioni e ci sono molti eventi degli utenti. Una volta completata l'importazione del catalogo, devi utilizzare l'API per riunire gli eventi caricati prima del completamento dell'importazione.

    Vertex AI Search for Retail tenta di unire gli eventi utente registrati con i metadati del catalogo dei prodotti al momento della creazione dell'evento utente. Per l'addestramento vengono utilizzati solo gli eventi uniti correttamente, quindi assicurati di riunire tutti gli eventi registrati prima dell'importazione completa del catalogo. Se un evento fa riferimento a un articolo che non esiste nel catalogo, viene ignorato o non associato ai prodotti corretti. Analogamente, se importi eventi utente precedenti, il catalogo deve includere tutti i prodotti a cui fanno riferimento. Puoi contrassegnare i prodotti meno recenti come OUT_OF_STOCK anziché rimuoverli dal catalogo.

  • Mantieni aggiornato il catalogo.

    Quando registri gli eventi utente, il prodotto incluso nell'evento utente è collegato al tuo catalogo corrente. Se registri un evento per un prodotto che non è presente nel catalogo attuale, non può essere utilizzato per l'addestramento dei modelli. Questo tipo di evento è chiamato "senza unione". Se hai registrato eventi prima che il catalogo fosse completamente importato, devi riassociare gli eventi registrati durante l'importazione. È normale che siano presenti alcuni eventi non uniti. Tuttavia, se la percentuale di eventi non uniti raggiunge il 5% o più degli eventi utente totali, assicurati che il catalogo sia aggiornato, riunisci gli eventi registrati prima dell'aggiornamento completo del catalogo e scopri perché vengono creati gli eventi non uniti.

    Puoi visualizzare gli eventi non uniti utilizzando i filtri di eventi. Scopri di più.

  • Fornisci il maggior numero possibile di informazioni con gli eventi utente.

    Ogni tipo di evento utente ha informazioni diverse richieste e accettate. Per ulteriori informazioni, consulta Informazioni sugli eventi utente.

  • Configura gli avvisi di Cloud Monitoring per sapere se i processi di registrazione degli eventi utente presentano 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 inferiori o uguali a 2 GB. Puoi includere al massimo 100 file in una singola richiesta di importazione. Un approccio consiste nell'importare solo gli eventi utente un giorno alla volta.

  • Dopo un'importazione collettiva, esamina i report sugli errori per assicurarti che i dati siano stati importati correttamente.

  • Quando importi i dati sugli eventi utente, includi un timestamp preciso per ogni evento utente ed evita di importare eventi utente sequenziali con timestamp identici.

    Fornisci il timestamp nel campo eventTime nel formato specificato da RFC 3339.

  • Se hai importato eventi utente errati, rivolgiti al tuo contatto Vertex AI Search for Retail per sapere 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 una forma sicura di un identificatore univoco per mantenere anonimi gli utenti di Vertex AI Search for Retail e difendere la loro privacy. È tua responsabilità oscurare le PII (informazioni che consentono l'identificazione personale), ad esempio indirizzi email o di casa, dai tuoi dati.

Registrare gli eventi utente con un pixel JavaScript

Il seguente esempio registra un detail-page-view UserEvent utilizzando un pixel JavaScript.

<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 hai importato gli eventi utente con Google Analytics 360, imposta visitorID sull'ID client Google Analytics. Tieni presente che l'ID client Google Analytics fa parte solo del nome completo del cookie _ga (ad esempio, l'ID client 123456789.123456789 fa parte del cookie _gaGA1.3.123456789.123456789).

Di seguito è riportato un esempio abbreviato che mostra il formato per l'impostazione dell'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 il metodo userEvents.write per inviare gli eventi utente direttamente all'API dal tuo server di backend.

Per registrare gli eventi utente, invia una richiesta POST al metodo 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 in Vertex AI Search for Retail.

Controlla l'origine dati

Assicurati che i dati sugli eventi utente che vuoi importare siano formattati correttamente.

Per una tabella dei campi Google Analytics 4 utilizzati da Vertex AI Search per il retail e a quali campi di Vertex AI Search per il retail vengono mappati, consulta Campi evento utente di Google Analytics 4.

Per tutti i parametri evento di Google Analytics, consulta la documentazione di riferimento sugli eventi di Google Analytics.

Verifica che:

  1. Se importi eventi di acquisto, come richiesto da alcuni modelli di Vertex AI Search per la vendita al dettaglio, i report sugli eventi includono i codici valuta. Consulta i parametri evento purchase nella documentazione di Google Analytics.

  2. Se prevedi di importare eventi search, i report sugli eventi includono le query di ricerca.

    L'importazione degli eventi search è supportata, ma questi eventi non vengono mappati da Google Analytics 4 nello stesso modo in cui vengono mappati gli altri tipi di eventi, perché Google Analytics 4 non supporta in modo nativo il tipo di evento search di ricerca di Vertex AI per la vendita al dettaglio.search Durante l'importazione, gli eventi search vengono costruiti da Google Analytics 4 combinando le informazioni dei parametri evento view_item_list e search_term.

    Consulta i parametri evento search nella documentazione di Google Analytics.

Registra gli eventi Google Analytics 4

Registra un evento utente includendo i dati JSON non elaborati codificati in URL per l'evento nella chiamata al metodo userEvents.collect.

Per il parametro prebuilt_rule, utilizza il valore ga4_bq.

Per una maggiore leggibilità, il seguente esempio di utilizzo della chiamata userEvents.collect imposta prima GA4_EVENT come variabile contenente i dati JSON non elaborati di un evento di esempio. La chiamata userEvents.collect nell'esempio codifica poi i dati dell'evento utilizzando la variabile GA4_EVENT.

  1. Per semplificare la codifica URL in un secondo momento, puoi impostare GA4_EVENT come variabile contenente i 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"
}'

  2. Effettua una chiamata userEvents.collect che includa i dati JSON non elaborati codificati in 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 apportare molte modifiche al codice lato server del tuo sito.

Alcune decisioni prese durante la configurazione dipendono dal fatto che tu stia utilizzando Google Analytics e Google Analytics E-commerce. L'e-commerce di Google Analytics può essere implementato utilizzando Google Analytics 4 o E-commerce avanzato. Il tag Cloud per la vendita al dettaglio supporta entrambi.

Né Google Analytics né Google Analytics E-commerce sono obbligatori. Se non li utilizzi, puoi configurare Variabile - E-commerce durante la creazione del tag Cloud per la vendita al dettaglio oppure compilare manualmente il codice del livello dati del tuo sito dopo aver creato il tag.

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

Utilizza questa procedura una tantum per configurare un tag Cloud per la vendita al dettaglio in Tag Manager per registrare gli eventi utente.

Creare una variabile ID visitatore

Il valore visitorId è per il monitoraggio degli utenti. visitorId è in genere un ID sessione ed è obbligatorio per tutti gli eventi. Configura una variabile che imposti gli ID sessione come visitorId.

Se utilizzi Google Analytics, puoi utilizzare l'ID visitatore di Google Analytics. Per configurare questa opzione, utilizza la seguente procedura per sostituire il valore dell'ID visitatore per il tag Cloud Retail. In questo modo, il cookie proprietario "_ga" viene mappato a una variabile di Tag Manager denominata "GA visitorId". Puoi fare lo stesso per qualsiasi cookie ID sessione, che non deve necessariamente provenire da Google Analytics.

Questa procedura presuppone che tu stia utilizzando Google Analytics. In caso contrario, puoi utilizzare un altro cookie o un'altra variabile oppure recuperare l'ID visitatore dal livello dati cloud_retail.

Per impostare il valore visitorID su una variabile per il tag Cloud per la vendita al dettaglio:

  1. In Tag Manager, vai alla scheda Variabili e fai clic su Nuova per creare una nuova variabile definita dall'utente.

  2. Assegna un nome alla variabile nella parte superiore della finestra di dialogo, ad esempio "GA visitorId".

  3. Inserisci le impostazioni della variabile.

    Puoi utilizzare l'ID client o l'ID cookie da impostare come origine degli ID visitatore. Utilizza sempre un'origine ID visitatore coerente durante l'importazione di eventi utente storici e in tempo reale.

    ID client

    In Google Analytics 4, questa variabile viene mappata al campo user_pseudo_id nello schema di BigQuery Export di 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 il tuo ID monitoraggio, consulta la sezione Cosa è successo al mio ID monitoraggio?.

      function() {
 var tracker = ga.getByName('G-XXXXXX');
 return tracker.get('clientID');
}

    3. Fai clic su Salva per salvare la variabile.

    1. Scegli Cookie proprietario come tipo di variabile.

    2. Nel campo Nome cookie, inserisci _ga.

    3. Fai clic su Formato valore, seleziona Converti in valori non definiti e inserisci "" (una stringa vuota).

    4. Fai clic su Salva per salvare la variabile.

      Il cookie proprietario "_ga" viene mappato a una variabile Tag Manager chiamata "GA visitorId".

Poi, crea un tag Cloud per la vendita al dettaglio in Tag Manager. Questo tag utilizzerà la variabile ID visitatore che hai appena creato.

Creare un tag Google Tag Manager

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

  1. Accedi a Tag Manager e seleziona il contenitore del tuo sito.

  2. Vai alla scheda Tag e fai clic su Nuovo per aggiungere un nuovo tag.

  3. Assegna un nome al tag nella parte superiore del riquadro (il segnaposto è Variabile senza titolo), ad esempio "Vertex AI Search per la vendita al dettaglio".

  4. Fai clic su Configurazione tag e scegli il tag Cloud per la vendita al dettaglio per aprire il pannello di configurazione dei tag.

  5. Inserisci la tua chiave API.

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

    Le tue chiavi API sono disponibili nella pagina API e servizi > Credenziali della console Google Cloud.

  6. Inserisci il numero del progetto Google Cloud in cui è attivata Vertex AI Search per la vendita al dettaglio.

    Il numero di progetto è disponibile nella dashboard della console Google Cloud.

  7. Per il campo Origine dati eventi utente:

    • Livello dati (opzione consigliata): seleziona se la tua implementazione sarà una delle seguenti:

      • Hai implementato Google Analytics E-Commerce tramite Tag Manager. Riutilizza il livello dati come origine dati per gli eventi invece di crearne uno nuovo. Viene utilizzato lo schema di Google Analytics 4, se presente. In caso contrario, viene utilizzato E-commerce avanzato di UA. Con questa origine dati, puoi registrare solo gli eventi add-to-cart, purchase-complete, detail-page-view e search. Gli eventi search vengono registrati utilizzando le impressioni e-commerce combinate con le query di ricerca (consulta Creare una variabile di query di ricerca).

      • Utilizzi Google Analytics E-commerce e puoi compilare manualmente il codice del livello di dati. Consulta la Guida per gli sviluppatori di Tag Manager.

    • Variabile - Cloud Retail: seleziona questa opzione per compilare una variabile Tag Manager con i campi richiesti per Vertex AI Search per il retail. Puoi scegliere questa opzione se non utilizzi Google Analytics E-commerce o se Google Analytics E-commerce non dispone dei dati necessari per Vertex AI Search per la vendita al dettaglio. Se passi a questa origine dall'opzione precedente Livello dati - Cloud per la vendita al dettaglio, crea anche una variabile di livello dati con chiavecloud_retail e associala a questa opzione Variabile - Cloud per la vendita al dettaglio.

    • Variabile - E-commerce: seleziona questa opzione se non utilizzi E-commerce di Google Analytics nel livello dati e non puoi compilare manualmente il codice del livello dati.

      Nel campo Leggi i dati di e-commerce dalla variabile utente visualizzato, scegli una variabile. In questo modo, Vertex AI Search per la vendita al dettaglio può leggere i dati sugli eventi utente di e-commerce di Google Analytics da una variabile personalizzata che crei.

      La variabile deve corrispondere al formato descritto nella Guida per gli sviluppatori di GA4. Per creare una variabile nel formato corretto, puoi utilizzare lo strumento per la creazione di oggetti di e-commerce avanzati, un modello di variabile personalizzata della Galleria modelli della community di Tag Manager. I modelli della community non sono gestiti da Google. Per utilizzare questo modello, consulta la pagina della galleria di Object Builder di E-commerce avanzato per consultare la documentazione e altre risorse.

  8. Fai clic sul pulsante + Sovrascrivi un valore nel messaggio UserEvent.

  9. Per Selettore di campi, seleziona visitorId come campo e per Valore campo seleziona la nuova variabile ID visitatore che hai creato in Creare una variabile ID visitatore.

  10. Fai clic su Salva.

    Il tag Cloud Retail è stato creato.

Opzioni delle origini dati legacy

In precedenza, Livello dati - E-commerce e Livello dati - Cloud per la vendita al dettaglio erano disponibili come opzioni di origine dati. Queste opzioni legacy non sono disponibili nei nuovi tag. Se trasferisci un tag esistente a una nuova origine dati, visualizza l'anteprima con Tag Manager per verificarlo prima dell'implementazione. 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, viene utilizzato E-commerce avanzato di UA.

  • Se hai utilizzato Livello dati - Cloud per la vendita al dettaglio, passa all'opzione Variabile - Cloud per la vendita al dettaglio. Crea una variabile di livello dati con chiavecloud_retail e associala all'opzione Variabile - Cloud Retail.

Successivo:

Creare una variabile di query di ricerca

Se utilizzi la ricerca, puoi creare una variabile in Tag Manager per le query di ricerca e collegarla al tag Cloud per la vendita al dettaglio. In questo modo, Vertex AI Search for Retail può ricevere query di ricerca da Analytics.

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

  • Variabile - E-commerce o il livello dati con lo schema E-commerce di Google Analytics: crea una variabile URL o elemento DOM in Tag Manager e collegala al tag Cloud per la vendita al dettaglio. Inoltre, attiva l'opzione che consente al tag di utilizzare le impressioni e-commerce di Google Analytics per creare eventi di ricerca.
  • Variabile - Cloud Retail o un livello dati compilato manualmente: crea una variabile URL o elemento DOM in Tag Manager e collegala al tag Cloud Retail. Per determinare se il tipo di un evento utente è search, devi anche:
    • Crea una variabile di tipo costante per i tipi di eventi di ricerca e allegala al tag.
    • Imposta il tipo di evento di ricerca nel livello dati o nella variabile Cloud per la vendita al dettaglio.

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

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

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

Puoi creare una variabile di tipo URL, una variabile di tipo elemento DOM o una variabile JavaScript (pagina) personalizzata. La scelta e la configurazione dipendono dall'implementazione del tuo sito:

  • Una variabile URL recupera 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 dei suoi risultati di ricerca.
  • Una variabile Elemento DOM recupera le informazioni sulle query di ricerca dal Document Object Model (DOM) del tuo sito. Non è necessario modificare il DOM per utilizzare questa variabile. Tuttavia, devi essere in grado di leggere e comprendere il DOM per configurare correttamente questa variabile.
  • Una variabile JavaScript personalizzata restituisce i dati formattati da una funzione JavaScript. Questo è utile se hai dati esistenti che vuoi formattare nello schema Cloud per la vendita al dettaglio o nell'e-commerce.

Innanzitutto, crea una variabile Tag Manager di tipo URL, Elemento DOM o JavaScript personalizzato:

  1. In Tag Manager, vai alla scheda Variabili e fai clic su Nuova per creare una nuova variabile definita dall'utente.

  2. Assegna un nome alla variabile nella parte superiore della finestra di dialogo, ad esempio "search_variable".

  3. 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 chiave 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 elemento o il selettore elemento della query di ricerca.

      Questa impostazione dipende dal fatto che il tuo sito utilizzi un ID elemento o un 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 sarà value. In questo esempio, il valore della variabile viene impostato su shoes.

    Tipo di JavaScript personalizzato

    1. Imposta Tipo di variabile su JavaScript personalizzato.

    2. Sostituisci le variabili nel seguente codice e incollalo nel riquadro JavaScript personalizzato.

    3. Nel riquadro JavaScript personalizzato, aggiungi il codice JavaScript che restituisce un evento di ricerca nello schema di vendita al dettaglio.

      Il seguente codice campione trasforma i dati di una variabile Ecommerce Items esistente nell'array productDetails utilizzato dallo schema di Vertex AI Search per il retail e restituisce un evento completo. Per utilizzare questo codice, sostituire Ecommerce Items, Search Query e Search Filter con le variabili 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;
}

  4. Fai clic su Salva per salvare la variabile.

Quindi, collega la variabile al tag Cloud Retail:

  1. Nella pagina Tag Manager, Tag, fai clic sul tag Cloud per la vendita al dettaglio per modificarlo.

  2. Se l'origine dati degli eventi utente del tag è Variabile - E-commerce o se utilizzi il livello dati con lo schema di e-commerce di Google Analytics, seleziona la casella di controllo Utilizza le impressioni di e-commerce avanzato per creare eventi di ricerca.

    In questo modo, Vertex AI Search for Retail può determinare se il tipo di un evento utente è search in base ai dati di ricerca che riceve da questo tag.

  3. Nella sezione Dati sugli eventi utente, fai clic sul pulsante + Sovrascrivi un valore nel messaggio UserEvent.

  4. Seleziona searchQuery in Selettore di campi e imposta la variabile della query di ricerca come Valore campo.

  5. Salva il tag.

Successivo:

Crea e collega una variabile costante

Puoi utilizzare questa procedura se hai scelto Variabile - Cloud per la vendita al dettaglio o un livello dati compilato manualmente come origine evento utente per il tag Cloud per la vendita al dettaglio.

La creazione di una variabile di tipo costante per gli eventi di ricerca e la sua impostazione come sostituzione dell'evento utente nel tag Cloud per la vendita al dettaglio consente a Vertex AI Search per la vendita al dettaglio di determinare se il tipo di un evento utente è search.

In alternativa a questa procedura, puoi specificare il searchtipo di evento utente tramite il livello dati o la variabile Cloud per la vendita al dettaglio che utilizzi come origine evento del tag. In caso contrario, segui i passaggi riportati di seguito per impostare il tipo di evento.

Innanzitutto, crea una variabile di tipo costante:

  1. In Tag Manager, vai alla scheda Variabili e fai clic su Nuova per creare una nuova variabile definita dall'utente.

  2. Assegna un nome alla variabile nella parte superiore della finestra di dialogo, ad esempio "search_constant".

  3. Imposta Tipo di variabile su Costante.

  4. Inserisci search nel campo Valore

  5. Fai clic su Salva per salvare la variabile.

Quindi, collega la variabile al tag Cloud Retail:

  1. Nella pagina Tag Manager,Tag, fai clic sul tag Cloud per la vendita al dettaglio per modificarlo.

  2. Nella sezione Dati sugli eventi utente, fai clic sul pulsante + Sovrascrivi un valore nel messaggio UserEvent.

  3. Seleziona eventType in Selettore di campi e imposta la variabile della query di ricerca come Valore campo.

  4. Salva il tag.

Poi, crea gli attivatori evento per il tag.

Creare attivatori di eventi per il tag Tag Manager

Crea gli attivatori per tutti i tipi di eventi utente che verranno utilizzati dai modelli di Vertex AI Search per il retail.

I tag di Tag Manager devono avere attivatori che controllano quando il tag deve essere "attivato" sul sito. Gli attivatori rilevano quando si verificano eventi (ad esempio quando un utente visualizza la home page o aggiunge un articolo al carrello) e chiedono al tag di inviare le informazioni sugli eventi utente a Vertex AI Search for Retail.

Tag Manager fornisce alcuni attivatori standard. Ad esempio, Window Loaded è un trigger per gli eventi detail-page-view. Per informazioni dettagliate su ciascun tipo, consulta Tipi di attivatore nella documentazione di Tag Manager.

In genere, il tag viene attivato quando un utente visualizza una pagina contenente gli eventi necessari per Vertex AI Search for Retail (ad esempio la home page, le pagine dei dettagli dei prodotti, le pagine del carrello o la pagina di completamento del pagamento). In questi casi, il tag deve essere attivato dopo il caricamento della pagina, in modo che i cookie siano disponibili e tutte le variabili del livello di dati siano compilate. Per farlo, imposta gli attivatori in modo che vengano attivati su Window Loaded o DOM Ready.

Potresti dover attivare il tag quando viene eseguita un'azione anziché al caricamento della pagina (ad esempio se un utente che aggiunge un articolo a un carrello non forza il ricaricamento di una pagina). In questi casi, puoi configurare l'azione di clic sul tuo sito in modo da inviare contemporaneamente gli aggiornamenti al livello dati e associare l'attivatore a quell'azione.

Ad esempio, se hai creato un attivatore per gli eventi add-to-cart, puoi scegliere come tipo di attivatore Clic - Solo link e impostarlo in modo che venga attivato in base all'ID clic (in questo esempio, addtocart). Dovresti quindi configurare il link addtocart sul tuo sito in modo che aggiorni anche il livello dati con nuovi valori quando viene fatto clic:

  <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 attivatore personalizzato. In genere, crei un attivatore personalizzato in Tag Manager utilizzando il nome dell'evento utente. Se non puoi modificare il codice frontend, puoi creare un attivatore personalizzato utilizzando le macro JavaScript. Per saperne di più sugli attivatori personalizzati, consulta Attivatire eventi personalizzati.

Per creare gli attivatori in Tag Manager, segui le procedure riportate di seguito:

Creare nuovi attivatori per il tag Tag Manager

Se non utilizzi Google Analytics Ecommerce, crea nuovi attivatori di eventi per tutti gli eventi utente di cui hanno bisogno i modelli di Vertex AI Search per la vendita al dettaglio. Associa poi i nuovi attivatori al tag Cloud per la vendita al dettaglio che hai creato in Tag Manager.

Prima di iniziare i passaggi che seguono, assicurati di aver creato un tag Cloud Retail in Tag Manager. Consulta Creare un tag Tag Manager.

Innanzitutto, crea gli attivatori. Ripeti questa procedura per tutti gli eventi utente richiesti dai modelli di Vertex AI Search for Retail:

  1. Nella pagina Tag Manager, Trigger, fai clic su Nuovo > Configurazione attivatore.

  2. Scegli il tipo di attivatore da applicare all'evento utente per cui stai creando un attivatore.

  3. Salva l'attivatore.

Associa quindi i nuovi attivatori al tag Cloud Retail. Si tratta di una procedura da eseguire una sola volta:

  1. Nella pagina Tag Manager, Tag, fai clic sul tag Cloud per la vendita al dettaglio per modificarlo.

  2. Fai clic su Attivazione, seleziona i nuovi attivatori e fai clic su Aggiungi.

  3. Salva il tag.

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

Se utilizzi il livello dati cloud_retail come origine evento utente, assicurati anche di configurare il livello dati.

Riutilizzare gli attivatori di e-commerce di Google Analytics

Se hai implementato E-commerce di Google Analytics tramite Tag Manager, riutilizza gli attivatori di eventi di E-commerce di Google Analytics per la ricerca di Vertex AI per la vendita al dettaglio.

Con questa origine dati, puoi registrare solo gli eventi add-to-cart, purchase-complete, detail-page-view e search. Gli eventi search vengono registrati utilizzando le impressioni e-commerce combinate con le query di ricerca (consulta Creare una variabile di query di ricerca).

La tabella seguente mostra come gli eventi di e-commerce e di e-commerce avanzato di Google Analytics vengono mappati agli eventi di Vertex AI Search per il 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 combinato con il campo searchQuery)

Prima di iniziare questi passaggi, assicurati di aver prima:

  • Configura un tag in Tag Manager di tipo Google Analytics - Evento GA4 e attiva E-commerce avanzato o GA4. Per ulteriori informazioni, consulta la documentazione di Tag Manager e la Guida per gli sviluppatori di GA4.
  • Hai configurato il tag e-commerce avanzato o GA4 in Tag Manager per attivarlo in base agli eventi utente che prevedi di registrare per Vertex AI Search for Retail.
  • Hai creato un tag Cloud per la vendita al dettaglio in Tag Manager con "Livello dati" o "Variabile - E-commerce" come origine dati degli eventi utente (consulta Creare un tag Tag Manager).

Per riutilizzare gli attivatori di e-commerce di Google Analytics:

  1. Nella pagina Tag Manager, Tag, fai clic sul tag e-commerce di Google Analytics (tipo Google Analytics - Evento GA4) per modificarlo.

  2. In Impostazioni avanzate > Sequenza tag, seleziona Attiva un tag dopo l'attivazione di <nome del tag e-commerce avanzato o GA4>.

  3. Seleziona il tag Cloud Retail come Tag di pulizia.

    Seleziona Non attivare <nome tag Cloud Retail> se <nome tag E-commerce avanzato o GA4> non riesce o è in pausa.

  4. Salva il tag.

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

Se utilizzi il livello dati cloud_retail come origine evento utente, assicurati anche di configurarlo.

Utilizzare il livello dati cloud_retail con Tag Manager

Se hai creato il tag Cloud Retail in Tag Manager per utilizzare il livello dati cloud_retail come origine evento utente, configura la variabile dataLayer nel codice HTML di origine come descritto nella Guida per gli sviluppatori di Tag Manager.

Informazioni sul livello dati

La maggior parte dei tag di Tag Manager richiede dati che cambiano a seconda dell'utente o della pagina (ad esempio ID utente o ID prodotto). Per il tag Cloud Retail, questi dati devono essere esposti in modo strutturato tramite un livello dati affinché Tag Manager possa utilizzarli.

Il livello dati è un oggetto JavaScript che in genere viene aggiunto a una pagina utilizzando il codice lato server o nel front-end utilizzando HTML o un modello. Se una pagina è configurata con il livello dati, conterrà del codice come il 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 dell'array.

Campi obbligatori nel livello dati cloud_retail

Informazioni sugli eventi utente elenca tutti i campi obbligatori e gli esempi per i tipi di eventi che devono essere trasmessi al livello dati cloud_retail.

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

Alcuni campi, come visitorId, sono obbligatori per il messaggio UserEvent, ma potrebbero non essere disponibili durante il completamento del livello dati. Ad esempio, visitorId potrebbe essere derivato dal cookie dell'utente o experimentIds dal framework per le sperimentazioni A/B. In questo caso, utilizza una variabile per sovrascrivere il campo nel tag Tag Manager.

Puoi sovrascrivere i seguenti campi:

  • visitorId
  • userInfo.userId
  • attributionToken
  • experimentIds

Per scoprire come sovrascrivere un campo UserEvent in Tag Manager, consulta Impostazione del campo visitorID in Tag Manager, che illustra la procedura per la sovrascrittura del valore del campo visitorId con una variabile definita dall'utente.

L'esempio seguente mostra il livello dati che deve essere incluso nella pagina per un UserEvent detail-page-view 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 Tag Manager

La modalità di anteprima di Tag Manager ti consente di testare i nuovi tag prima di pubblicarli sul tuo sito.

Per maggiori dettagli sulla modalità di anteprima, consulta la documentazione di Tag Manager relativa alla modalità di anteprima.

Utilizza la procedura seguente per verificare che il tag venga attivato correttamente.

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

  2. Inserisci le informazioni sul tuo sito e fai clic su Inizia per avviare Tag Assistant.

    Nella scheda del browser corrente, si avvia Tag Assistant e il sito si apre in una nuova scheda.

  3. Sul tuo sito, visita una pagina in cui deve essere attivato il tag Cloud Retail.

  4. Verifica che Tag Assistant elenchi il tag Cloud Retail nella scheda Tag nella sezione Tag attivati.

  5. In Tag Assistant, vai alla scheda Livello dati e controlla che vengano visualizzati i valori corretti del livello dati cloud_retail o e-commerce.

Verificare la presenza di errori nei tag

Se alcuni campi sono errati o mancanti quando viene visualizzata l'anteprima del tag, in genere il tag restituisce anche un errore, a meno che non venga attivato.

Puoi controllare la pagina Monitoraggio nella console Search for Retail per verificare la presenza di errori. Questa pagina registra la maggior parte degli errori, tranne quelli di sintassi, che in genere vengono visualizzati solo nei risultati della richiesta.

Per utilizzare Chrome DevTools per verificare la presenza di eventuali errori generati, inclusi gli errori di sintassi, puoi seguire i passaggi che seguono.

  1. Attiva la modalità di anteprima in Tag Manager per il tuo sito in un browser Chrome e visita qualsiasi pagina in cui deve essere attivato il tag Cloud per la vendita al dettaglio.

  2. Con la modalità di anteprima aperta, apri DevTools e fai clic sulla scheda Rete.

  3. Ricarica la pagina.

  4. 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, ad esempio un errore 400 e l'evidenziazione dell'evento in rosso, indicano che è necessario eseguire il debug.

  5. Fai doppio clic sul nome dell'evento per eseguire la richiesta e visualizzare una risposta completa con ulteriori informazioni sull'errore.

    Ad esempio, potresti visualizzare un errore 400 contenente il messaggio "'visitorId' è obbligatorio e non può essere vuoto", che indica che visitorId non è stato impostato correttamente.

  6. Se non viene attivato alcun userEvent, controlla la scheda Console di DevTools per verificare la presenza di errori di sintassi nel livello dati.

Monitorare lo stato di integrità dell'importazione

La registrazione degli eventi utente è importante per ottenere risultati di alta qualità. Devi monitorare le percentuali di errore di registrazione degli eventi e intervenire se necessario. Per ulteriori informazioni, consulta Configurare gli avvisi per i problemi di caricamento dei dati.

Visualizzare gli eventi registrati

Visualizza le metriche di integrazione degli eventi nella scheda Eventi della pagina Dati della console Ricerca per la vendita al dettaglio. Questa pagina mostra tutti gli eventi scritti o importati nell'ultimo anno. Potrebbero essere necessarie fino a 24 ore prima che le metriche vengano visualizzate dopo l'importazione dati.

Vai alla pagina Dati

Passaggi successivi