Registra gli 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 usa gli eventi utente in tempo reale per generare consigli e risultati di ricerca. Registrare il maggior numero possibile di tipi di eventi utente con informazioni valide sul prodotto aumenta la qualità dei risultati.

Le procedure di registrazione in questa pagina si applicano sia ai consigli che alla ricerca. Dopo aver registrato i dati, entrambi i servizi possono utilizzare questi eventi, quindi non è necessario caricare due volte gli stessi dati 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:

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 la cronologia degli eventi utente. La registrazione di dati sugli eventi utente sufficienti per l'addestramento dei modelli può richiedere molto tempo. Puoi accelerare l'addestramento iniziale del modello importando in blocco i dati degli eventi utente dagli 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 suggerimento o a risultati di ricerca forniti in precedenza, un token di attribuzione attiva le metriche sul rendimento. L'inclusione di un token di attribuzione è facoltativo, ma vivamente consigliato. 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 su ID visitatore e ID utente, consulta Informazioni sugli utenti.

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 Aiuto:

Guidami

Prima di iniziare

Prima di registrare gli eventi utente, devi avere:

  • È stato creato un progetto Google Cloud con l'autenticazione configurata.

  • Una chiave API valida (per Pixel JavaScript o Tag Manager) oppure un account di servizio valido con il ruolo Editor Retail 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 la vendita al dettaglio richiede dati di alta qualità per generare risultati di alta qualità. Se i dati sono incompleti o errati, la qualità dei risultati ne risenti.

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

  • Se registri eventi utente prima o durante l'importazione del catalogo, ripartecipa a eventuali eventi registrati prima del completamento dell'importazione del catalogo.

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

    Vertex AI Search per il retail tenta di unire gli eventi utente registrati con i metadati del catalogo dei prodotti quando viene creato l'evento utente. Per l'addestramento vengono utilizzati solo gli eventi uniti correttamente, quindi assicurati di partecipare di nuovo a tutti gli eventi registrati prima del completamento dell'importazione del catalogo. Se un evento fa riferimento a un articolo che non esiste nel catalogo, viene eliminato o non associato ai prodotti corretti. Analogamente, se importi eventi utente dal passato, il catalogo deve includere tutti i prodotti a cui fa riferimento. Puoi contrassegnare 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 viene collegato al tuo catalogo attuale. Se registri un evento per un prodotto che non è nel catalogo attuale, non può essere utilizzato per l'addestramento dei modelli. Questo è chiamato evento "non unito". Se hai registrato eventi prima che il catalogo fosse completamente importato, devi rientrare negli eventi registrati durante l'importazione. Sono previsti 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 del completamento dell'aggiornamento del catalogo e verifica il motivo della creazione degli eventi non uniti.

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

  • Fornisci il maggior numero possibile di informazioni sugli 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 in modo da sapere se i processi di registrazione degli eventi utente subiscono interruzioni.

  • Per l'importazione collettiva di eventi utente, limita le dimensioni dei dati che stai importando.

    Il completamento dell'importazione collettiva degli eventi utente può richiedere fino a 24 ore.

    Le dimensioni di ogni file non devono superare i 2 GB. Puoi includere al massimo 100 file in una singola richiesta di importazione. Uno degli approcci consiste nel importare solo gli eventi utente per un giorno alla volta.

  • Dopo un'importazione collettiva, esamina la segnalazione degli 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 non corretti, rivolgiti al tuo contatto di Vertex AI Search per il 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 identificatore univoco in formato sicuro per mantenere anonimi gli utenti per Vertex AI Search per la vendita al dettaglio e proteggere la privacy degli utenti. È tua responsabilità oscurare nei dati le PII (informazioni che consentono l'identificazione personale), ad esempio email o indirizzi di casa.

Registrare gli eventi utente con un pixel JavaScript

L'esempio seguente registra un UserEvent detail-page-view 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 eventi utente con Google Analytics 360, imposta visitorID sull'ID client di Google Analytics. Tieni presente che l'ID cliente di Google Analytics è solo una parte del nome completo del cookie _ga (ad esempio, l'ID client 123456789.123456789 fa parte del cookie _ga GA1.3.123456789.123456789).

Per saperne di più su come ottenere l'ID client, consulta la documentazione di Google Analytics.

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

<script type="text/javascript">
var tracker = ga.getByName('UA-XXXXXX-N');
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 eventi utente direttamente all'API dal tuo server di backend.

Per registrare 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 per la vendita al dettaglio.

Controllare l'origine dati

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

Per una tabella dei campi di Google Analytics 4 utilizzati da Vertex AI Search per la vendita al dettaglio e a quali campi di Vertex AI Search sono mappati, consulta Campi degli eventi utente di Google Analytics 4.

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

Controlla quanto segue:

  1. Se importi eventi di acquisto, richiesti da alcuni modelli di Vertex AI Search per la vendita al dettaglio, i report sugli eventi includono 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 gli eventi search non vengono mappati da Google Analytics 4 come altri tipi di eventi, perché Google Analytics 4 non supporta in modo nativo il tipo di evento search di Vertex AI Search per la vendita al dettaglio. Durante l'importazione, gli eventi search vengono creati 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.

Registrare gli eventi di Google Analytics 4

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

Per il parametro prebuilt_rule, utilizza il valore ga4_bq.

Per quanto riguarda la leggibilità, nel seguente esempio di utilizzo della chiamata userEvents.collect imposta GA4_EVENT come variabile contenente i dati JSON non elaborati per un evento di esempio. La chiamata userEvents.collect nell'esempio esegue la codifica URL dei dati dell'evento utilizzando la variabile GA4_EVENT.

  1. Per semplificare la codifica degli URL in un secondo momento, puoi impostare GA4_EVENT come una variabile contenente 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 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 consente di gestire e testare più tag senza dover apportare molte modifiche al codice lato server sul tuo sito.

Alcune decisioni che prendi durante la configurazione dipendono dall'utilizzo o meno di Google Analytics o dell'e-commerce di Google Analytics. L'e-commerce di Google Analytics può essere implementato utilizzando Google Analytics 4 o E-commerce avanzato. Il tag Cloud Retail supporta entrambi.

Non è richiesto né Google Analytics né l'e-commerce di Google Analytics. Se non li utilizzi, puoi configurare Variabile - E-commerce durante la creazione del tag Cloud per la vendita al dettaglio oppure inserire manualmente il codice del livello dati del tuo sito dopo aver creato il tag.

L'e-commerce di Google Analytics è una configurazione aggiuntiva per Google Analytics che trasmette titoli, ID, prezzi, dettagli delle transazioni e altri dati di e-commerce strutturati a Google Analytics. Vertex AI Search per la vendita al dettaglio può utilizzare automaticamente il livello dati per l'e-commerce di Google Analytics. Se non hai configurato l'E-commerce di Google Analytics per Google Analytics, ma vuoi utilizzarlo, consulta ulteriori dettagli e le istruzioni di configurazione nella guida per gli sviluppatori di GA4 o nella guida per gli sviluppatori sull'E-commerce avanzato.

Utilizza questa procedura una tantum per configurare un tag Cloud Retail in Tag Manager per registrare gli 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. Configura una variabile che imposta gli ID sessione come visitorId.

Se usi Google Analytics, puoi usare l'ID visitatore di Google Analytics. Per configurarlo, 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 "ID visitatore GA". Puoi eseguire la stessa operazione per qualsiasi cookie dell'ID sessione, non deve necessariamente provenire da Google Analytics.

Questa procedura presuppone che tu utilizzi Google Analytics. In caso contrario, puoi utilizzare un altro cookie o una variabile oppure ottenere 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 variabile definita dall'utente.

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

  3. Inserisci le impostazioni della variabile.

    Puoi utilizzare l'ID client o l'ID cookie per impostare l'origine degli ID visitatore. Utilizza sempre un'origine di ID visitatore coerente quando importi eventi utente storici e in tempo reale.

    ID client

    In BigQuery di Google Analytics 360, questa variabile viene mappata al campo clientID nello schema di esportazione di Universal Analytics BigQuery. In Google Analytics 4, questa variabile è mappata al campo user_pseudo_id nello schema di esportazione BigQuery di Google Analytics 4.

    1. Imposta Tipo di variabile su JavaScript personalizzato.

    2. Inserisci lo script seguente nel campo JavaScript personalizzato.

      Sostituisci "UA-XXXXXX-N" con il tuo ID monitoraggio di Google Analytics. Per trovare l'ID monitoraggio, consulta la sezione Che cosa è successo al mio ID monitoraggio? Per saperne di più su come ottenere l'ID client, consulta la documentazione di Google Analytics.

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

    3. Fai clic su Salva per salvare la variabile.

    1. Scegli Cookie proprietari come tipo di variabile.

    2. Nel campo Nome cookie, inserisci _ga.

    3. Fai clic su Valore formato, seleziona Converti undefined in.. e inserisci "" (una stringa vuota).

    4. Fai clic su Salva per salvare la variabile.

      In questo modo, il cookie proprietario "_ga" viene mappato a una variabile di Tag Manager denominata "ID visitatore GA".

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

Creare un tag di Google Tag Manager

Configura un tag in Tag Manager per inviare informazioni sugli eventi utente a Vertex AI Search per la vendita al dettaglio.

  1. Accedi a Tag Manager e seleziona il contenitore per il 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 riquadro di configurazione dei tag.

  5. Inserisci la chiave API.

    Utilizza la chiave che hai creato durante la configurazione di Vertex AI Search per il retail.

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

  6. Inserisci il numero del progetto Google Cloud in cui Vertex AI Search per il retail è abilitato.

    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 l'implementazione sarà una delle seguenti:

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

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

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

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

      Scegli una variabile nel campo Leggi i dati di e-commerce da una variabile utente visualizzato. In questo modo Vertex AI Search per la vendita al dettaglio può leggere i dati sugli eventi utente dell'e-commerce di Google Analytics da una variabile personalizzata creata da te.

      La variabile deve corrispondere al formato indicato 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 di creazione di oggetti di e-commerce avanzato, un modello di variabili personalizzate dalla Galleria modelli della community di Tag Manager. I modelli delle community non sono gestiti da Google. Per utilizzare questo modello, consulta la pagina della galleria di Advanced Ecommerce Object Builder per la documentazione e altre risorse.

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

  9. Per Selettore campo, seleziona visitorId come campo e per Valore campo, seleziona la nuova variabile ID visitatore creata in Creare una variabile ID visitatore.

  10. Fai clic su Salva.

    Il tag Cloud per la vendita al dettaglio è stato creato.

Opzioni dell'origine dati legacy

In precedenza, le opzioni Livello dati - E-commerce e Livello dati - Cloud Retail erano disponibili come opzioni di origine dati. Queste opzioni precedenti non sono disponibili nei nuovi tag. Se passi da un tag esistente a una nuova origine dati, visualizza l'anteprima con Tag Manager per verificarlo prima dell'implementazione. Quando effettui il passaggio:

  • Se hai utilizzato Livello dati - E-commerce, puoi passare al 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 associala all'opzione Variabile - Cloud Retail.

A seguire:

Creare una variabile della query di ricerca

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

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

  • Variabile - E-commerce o livello dati con lo schema di e-commerce di Google Analytics: Crea una variabile di elemento URL o DOM in Tag Manager e associala al tag Cloud Retail. Inoltre, abilita l'opzione che consente al tag di utilizzare le impressioni e-commerce di Google Analytics per creare eventi di ricerca.
  • Variabile - Cloud per la vendita al dettaglio o un livello dati completato manualmente: crea una variabile di elemento URL o DOM in Tag Manager e associala al tag Cloud Retail. Per determinare se il tipo di evento di un utente è search, devi anche:
    • Crea una variabile di tipo costante per i tipi di eventi di ricerca e collegala 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 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 configurare il livello dati.

Puoi creare una variabile di tipo URL, una variabile di tipo di elemento DOM o una variabile JavaScript (pagina) personalizzata. La creazione e la configurazione variano a seconda dell'implementazione del sito:

  • Una variabile URL acquisisce 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 risultati di ricerca.
  • Una variabile elemento DOM riceve le informazioni delle query di ricerca dal Document Object Model (DOM) del tuo sito. Non è necessario modificare il DOM per utilizzare questa variabile. Tuttavia, dovresti essere in grado di leggere e comprendere il DOM per configurare correttamente questa variabile.
  • Una variabile JavaScript personalizzata restituisce dati formattati da una funzione JavaScript. Questo è utile se hai dati esistenti che vuoi formattare nello schema di Cloud Retail o 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 "ricerca_variabile".

  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 di 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 elementi della query di ricerca.

      Questa impostazione varia a seconda che il 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 codice seguente e incollale nel riquadro JavaScript personalizzato.

    3. Nel riquadro JavaScript personalizzato, aggiungi il codice JavaScript che restituisca un evento di ricerca in 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 per la vendita al dettaglio e restituisce un evento completo. Per utilizzare questo codice, sostituisci 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.

A questo punto, 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 sugli eventi utente del tag è Variabile - E-commerce o se utilizzi il livello dati con lo schema E-commerce di Google Analytics, seleziona la casella di controllo Utilizza le impressioni di e-commerce avanzato per creare eventi di ricerca.

    Ciò consente a Vertex AI Search per la vendita al dettaglio di determinare se il tipo di evento di un utente è search in base ai dati di ricerca che riceve da questo tag.

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

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

  5. Salva il tag.

A seguire:

Creare e collegare una variabile costante

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

La creazione di una variabile di tipo costante per gli eventi di ricerca e l'impostazione come override di un evento utente nel tag Cloud Retail 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 tipo di evento utente search tramite il livello dati o la variabile Cloud Retail che stai utilizzando 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 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.

A questo punto, 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 degli eventi utente, fai clic sul pulsante + Sovrascrivi un valore nel messaggio UserEvent.

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

  4. Salva il tag.

Poi, crea gli attivatori di evento per il tag.

Creare attivatori di eventi per il tag Tag Manager

Crea attivatori per tutti i tipi di eventi utente che verranno utilizzati dai modelli di Vertex AI Search per la vendita al dettaglio.

I tag Tag Manager devono disporre di attivatori che controllano quando il tag deve essere "attivato" sul sito. Gli attivatori restano in ascolto dei momenti in cui si verificano gli 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 per la vendita al dettaglio.

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

In genere, devi impostare il tag in modo che si attivi quando un utente visualizza una pagina che contiene gli eventi necessari per Vertex AI Search per la vendita al dettaglio (come la home page, le pagine dei dettagli del prodotto, le pagine del carrello o la pagina di pagamento completa). In questi casi, il tag dovrebbe attivarsi dopo il caricamento della pagina, in modo che i cookie siano disponibili e tutte le variabili del livello dati vengano compilate. A questo scopo, imposta gli attivatori in modo che si attivino su Finestra caricata o Pronta per DOM.

Potrebbe essere necessario attivare il tag quando viene eseguita un'azione anziché al caricamento della pagina (ad esempio se un utente aggiunge un articolo a un carrello non ne forza il ricaricamento). 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 questa azione.

Ad esempio, se hai creato un attivatore per gli eventi add-to-cart, puoi scegliere Click - Just Links come tipo di attivatore e impostarlo in modo che si attivi in base all'ID clic (in questo esempio addtocart). Configura quindi il link addtocart sul tuo sito per aggiornare anche il livello dati con i nuovi valori quando l'utente fa 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, si crea un attivatore personalizzato in Tag Manager utilizzando il nome dell'evento utente. Se non riesci a modificare il codice front-end, puoi creare un trigger personalizzato utilizzando le macro JavaScript. Per maggiori informazioni sugli attivatori personalizzati, consulta Attivatore di eventi personalizzati.

Per creare attivatori in Tag Manager, utilizza le seguenti procedure:

Creare nuovi attivatori per il tag Tag Manager

Se non utilizzi l'e-commerce di Google Analytics, crea nuovi attivatori di eventi per tutti gli eventi utente necessari per i modelli di Vertex AI Search per la vendita al dettaglio. Poi, associa i nuovi attivatori al tag Cloud Retail che hai creato in Tag Manager.

Prima di iniziare a seguire i passaggi riportati di seguito, assicurati di aver creato un tag Cloud per la vendita al dettaglio in Tag Manager. Consulta Creare un tag Tag Manager.

Per prima cosa, crea gli attivatori. Ripeti questa procedura per tutti gli eventi utente richiesti da Vertex AI Search per i modelli di vendita al dettaglio:

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

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

  3. Salva l'attivatore.

Successivamente, associa i nuovi attivatori al tag Cloud Retail. Questa è una 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.

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 di configurare anche 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 di eventi dall'E-commerce di Google Analytics per Vertex AI Search per la vendita al dettaglio.

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

La tabella seguente mostra come gli eventi di e-commerce ed e-commerce avanzato di Google Analytics vengono mappati a Vertex AI Search per gli eventi di vendita al dettaglio.

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 avere:

  • Imposta un tag in Tag Manager di tipo Google Analytics - Universal Analytics o Google Analytics - Evento GA4 e attiva l'E-commerce avanzato o GA4 per il tag. Per informazioni dettagliate, consulta la documentazione di Tag Manager e la guida per gli sviluppatori di GA4 o la guida per gli sviluppatori sull'e-commerce avanzato.
  • Configurato il tag E-commerce avanzato o GA4 in Tag Manager in modo che si attivino sugli eventi utente che prevedi di registrare per Vertex AI Search per la vendita al dettaglio.
  • È stato creato un tag Cloud per la vendita al dettaglio in Tag Manager, con "Livello dati" o "Variabile - E-commerce" come origine dati sugli eventi utente (consulta Creare un tag Tag Manager.

Per riutilizzare gli attivatori E-commerce di Google Analytics:

  1. Nella pagina 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 l'attivazione di un tag dopo l'attivazione di <Nome tag e-commerce avanzato o GA4>.

  3. Seleziona il tag Cloud per la vendita al dettaglio come Tag di pulizia.

    Seleziona Non attivare <nome tag Cloud per la vendita al dettaglio> se <Nome tag e-commerce avanzato o GA4> non funziona 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 di configurare anche il livello dati.

Utilizza il livello dati cloud_retail con Tag Manager

Se hai creato il tag Cloud per la vendita al dettaglio in Tag Manager per utilizzare il livello dati cloud_retail come origine dell'evento utente, imposta 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 in base all'utente o alla pagina (come gli ID utente o gli ID prodotto). Per il tag Cloud per la vendita al dettaglio, i 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 tramite codice lato server oppure nel front-end mediante 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 a cui assegna la struttura cloud_retail come elemento array.

Campi obbligatori nel livello dati cloud_retail

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

Il codice o i modelli lato server devono avere i tag script corretti su ogni pagina da cui vuoi inviare gli eventi. Dopo che l'oggetto dataLayer sarà completato correttamente in 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 la compilazione del livello dati. Ad esempio, visitorId potrebbe derivare dal cookie dell'utente o experimentIds dal framework di sperimentazione 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 Impostare il campo visitorID in Tag Manager, che illustra come sovrascrivere il 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 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 nuovi tag prima di pubblicarli sul tuo sito attivo.

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

Per verificare che il tag sia attivato correttamente, procedi nel seguente modo.

  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 del sito e fai clic su Avvia per avviare Tag Assistant.

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

  3. Sul tuo sito, visita qualsiasi pagina in cui deve essere attivato il tag Cloud per la vendita al dettaglio.

  4. Verifica che Tag Assistant elenchi il tag Cloud per la vendita al dettaglio nella scheda Tag della sezione Tag attivati.

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

Verifica la presenza di errori relativi ai tag

Se alcuni campi sono errati o mancanti quando visualizzi l'anteprima del tag, generalmente quest'ultimo restituisce anche un errore, a meno che non venga attivato.

Puoi controllare la pagina Monitoring nella console di Search for Retail per verificare la presenza di errori. In questa pagina vengono registrati la maggior parte degli errori, ad eccezione di quelli di sintassi, che in genere vengono visualizzati solo nei risultati delle richieste.

Per utilizzare Chrome DevTools per verificare la presenza di eventuali errori generati, inclusi errori di sintassi, puoi procedere nel seguente modo.

  1. Attiva la modalità di anteprima in Tag Manager per il tuo sito nel browser Chrome e visita qualsiasi pagina 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.

    Nella scheda Rete vengono visualizzati l'evento userEvent:collect e il relativo codice di stato.

    • Una risposta 200 indica che il tag è in uno stato buono.
    • Altre risposte, come un errore 400 ed evidenziando l'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 con il messaggio "L'ID visitatore è obbligatorio e non può essere vuoto", a indicare che visitorId non è stato impostato correttamente.

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

Registrare gli eventi utente con il tagging lato server

Il tagging lato server consente di eseguire il deployment di un singolo contenitore lato server con molti client downstream. Questo crea un'unica fonte attendibile sul lato client, con molti consumatori lato server. Questa architettura sposta il carico dal web al server, rendendolo ideale per gli utenti che vogliono massimizzare le prestazioni dei loro siti web.

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

Vertex AI Search per la vendita al dettaglio fornisce il proprio tag lato server nativo.

Il tag lato server di Cloud per la vendita al dettaglio richiede e accetta parametri simili a quelli del tag web Cloud per la vendita al dettaglio, ad esempio:

  • Numero progetto
  • Chiave API (per l'autenticazione)
  • Override dei 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 Retail

Monitora l'integrità dell'importazione

La registrazione corretta degli eventi utente è importante per ottenere risultati di alta qualità. Dovresti monitorare le percentuali di errori della registrazione degli eventi e prendere provvedimenti, se necessario. Per maggiori informazioni, consulta Configurare avvisi per problemi di caricamento dei dati.

Visualizzare gli eventi registrati

Visualizza le metriche di integrazione degli eventi nella scheda Eventi della pagina Dati della console Search for Retail. In questa pagina sono visualizzati tutti gli eventi scritti o importati nell'ultimo anno. La visualizzazione delle metriche nella console può richiedere fino a un'ora dopo l'importazione dati.

Vai alla pagina Dati

Passaggi successivi