Registra gli eventi utente in tempo reale

Questa pagina descrive 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 suggerimenti 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 a consigli e ricerche. 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ò 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 è obbligatorio per Vertex AI Search for Retail al lavoro. 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 sull'utente.

Tutorial sulla scrittura di eventi utente

Questo tutorial mostra come registrare gli eventi utente utilizzando 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:

  • È stato creato un progetto Google Cloud 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, vedi 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, 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 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. 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 fa riferimento a un articolo che non esiste nel catalogo, viene ignorato o non associato 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 gli eventi utente, il prodotto incluso nell'evento utente è collegato al tuo catalogo corrente. Se registri un evento per prodotto non presente nell'attuale catalogo, non può essere usato per l'addestramento i tuoi modelli. Questo processo è chiamato "non unito" . 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 e riunisci gli eventi registrati prima dell'aggiornamento completo del catalogo. Inoltre, indaga sul motivo per cui 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 saperne di più, 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 2 GB o inferiore. Puoi includere al massimo 100 file in una singola richiesta di importazione. Un approccio consiste nell'importare solo gli eventi utente per 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 un formato 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 hai importato gli eventi utente 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 scoprire di più su come ottenere l'ID cliente, consulta la 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 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.

Controllare 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 quanto segue:

  1. Se importi eventi di acquisto, alcuni dei pod di Vertex AI Search for Retail richiesti dai modelli, 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. 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 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 una maggiore leggibilità, il seguente esempio di utilizzo della chiamata userEvents.collect imposta prima GA4_EVENT come variabile contenente i dati JSON non elaborati per un evento di esempio. La chiamata userEvents.collect nell'esempio esegue quindi la codifica URL dell'evento usando 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 dover modifiche al codice lato server del 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 Retail 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 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 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 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. 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 di ID sessione. non ha provenienti 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 Retail:

  1. In Tag Manager, vai alla scheda Variabili e fai clic su Nuova per creare una nuova .

  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 quando importi dati storici e di eventi utente in tempo reale.

    ID client

    In BigQuery di Google Analytics 360, questa variabile viene mappata al campo clientID nello schema di BigQuery Export di 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.

    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 proprietario "_ga" a una variabile Tag Manager chiamato "GA LookerId" (ID visitatore GA).

Poi, crea un tag Cloud per la vendita al dettaglio in Tag Manager. Questo tag utilizza la variabile ID visitatore appena creata.

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 Retail per apri il riquadro di configurazione dei tag.

  5. Inserisci la 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 Vertex AI Search for Retail è abilitato.

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

  7. Per il campo Origine dati eventi utente:

    • Livello dati (consigliato): seleziona se la tua implementazione deve essere uno di le seguenti:

      • Hai implementato Google Analytics E-Commerce 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, viene utilizzato E-commerce avanzato 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 l'e-commerce di Google Analytics e puoi completare manualmente i dati il codice livello. Consulta la 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 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 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 descritto nella Guida per gli sviluppatori di GA4 o nella Guida per gli sviluppatori di e-commerce avanzato. 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 usare questo modello, consulta la pagina della galleria del generatore di oggetti di e-commerce avanzato per 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 Crea una variabile ID visitatore.

  10. 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 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, utilizza l'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 collegalo al tag Cloud Retail. 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 sugli 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 per consentire al tag di utilizzare le impressioni e-commerce di Google Analytics per 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:

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 preferisci non configurarlo.

Puoi creare una variabile di tipo URL, una variabile di tipo di elemento DOM o una variabile variabile JavaScript (pagina). La scelta e la configurazione dipendono dall'implementazione del tuo 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 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. È 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:

  1. In Tag Manager, vai alla scheda Variabili e fai clic su Nuova per creare una nuova .

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

  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 o l'ID elemento della query di ricerca. selettore elementi.

      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 è value. Nella in questo esempio, il valore della variabile verrebbe impostato su shoes.

    Tipo di 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 il codice JavaScript che restituisce un evento di ricerca nello schema di vendita al dettaglio.

      Il seguente codice di esempio 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. Il giorno Tag Manager Tag, fai clic sul tag Cloud Retail 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 evento utente è search in base ai dati di ricerca che riceve da questo tag.

  3. Nella sezione Dati eventi utente, fai clic sull'icona + 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 scegli Variabile - Cloud Retail o livello dati completato manualmente come origine evento utente per Cloud Retail del tag.

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 questi passaggi 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 .

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

  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. Il giorno Tag Manager Tag, fai clic sul tag Cloud Retail per modificarlo.

  2. Nella sezione Dati eventi utente, fai clic sull'icona + Sovrascrivi un valore nel messaggio UserEvent.

  3. Seleziona eventType nel selettore di campi e imposta la 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

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 "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: Finestra caricata è 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 imposti il tag in modo che si attivi quando un utente visualizza qualsiasi pagina contenente 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.

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 evento utente. Se non puoi modificare il codice front-end, puoi creare un trigger personalizzato utilizzando 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 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 i passaggi che seguono, assicurati di aver creato un tag Cloud Retail in Tag Manager. Consulta Creare un tag di 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 applicabile l'evento utente per cui stai creando un trigger.

  3. Salva l'attivatore.

Associa poi i nuovi attivatori al tag Cloud Retail. Questo è procedura una tantum:

  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 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 gli eventi add-to-cart, purchase-complete, detail-page-view e search. search eventi vengono registrati utilizzando Impressioni e-commerce combinate con query di ricerca (vedi Crea una variabile 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 combinata con il campo searchQuery)

Prima di iniziare questi passaggi, assicurati di aver prima:

Per riutilizzare gli attivatori E-commerce di Google Analytics:

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

  2. In Impostazioni avanzate > Sequenza tag, seleziona Attiva un tag dopo <Nome tag di e-commerce avanzato o GA4> incendi.

  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.

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 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, 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à 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 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 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 il messaggio UserEvent, ma potrebbero non essere disponibili durante la compilazione del livello dati. Ad esempio,visitorId potrebbe essere derivato dal cookie dell'utente o experimentIds dal strumento sperimentale 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 che deve essere incluso nella pagina per un evento utente 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 di Tag Manager

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

Per ulteriori dettagli sulla modalità di anteprima, consulta la documentazione di Tag Manager per la modalità 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 elenca il tag Cloud Retail nella sezione 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 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 controllare la pagina Monitoraggio nella console Search for Retail per verificare la presenza di 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.

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

  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, come 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 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", 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.

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

Configurare il tag Cloud per la vendita al dettaglio

Monitorare lo stato di 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 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 console di Search for Retail Dati. In questa pagina sono mostrati tutti gli eventi scritti o importati nell'ultimo anno. Le metriche possono richiedere a 24 ore prima che venga visualizzata una volta completata l'importazione dati.

Vai alla pagina Dati

Passaggi successivi