Importare gli eventi utente storici

Questa pagina descrive come importare in blocco i dati sugli eventi utente da eventi passati in Vertex AI Search for commerce. I dati sugli eventi utente sono necessari per l'addestramento dei modelli. Dopo aver configurato la registrazione degli eventi in tempo reale, potrebbe essere necessario un periodo di tempo considerevole per registrare dati sufficienti sugli eventi utente per addestrare i modelli. L'importazione dei dati storici può accelerare il processo.

Le procedure di importazione descritte in questa pagina si applicano sia ai consigli sia alla ricerca. Dopo l'importazione dei dati, entrambi i servizi sono in grado di utilizzare questi eventi, quindi non è necessario importare gli stessi dati due volte se utilizzi entrambi i servizi.

Puoi importare eventi da:

Cloud Storage.
BigQuery.
BigQuery per gli eventi Google Analytics 360.
BigQuery per gli eventi Google Analytics 4.
Eventi in linea utilizzando il metodo userEvents.import.

Prima di iniziare

Per evitare errori di importazione e verificare che siano presenti dati sufficienti per generare risultati validi, esamina le seguenti informazioni prima di importare gli eventi utente.

Consulta le best practice per la registrazione degli eventi utente.
La formattazione degli eventi utente varia a seconda del tipo di evento utente. Consulta Schema di tipi ed esempi di eventi utente per il formato da specificare durante la creazione delle tabelle per ogni tipo di evento.
I consigli e la ricerca hanno requisiti minimi dei dati diversi. Assicurati che gli eventi utente soddisfino i requisiti del servizio che intendi utilizzare:
- Consulta Requisiti ed best practice per gli eventi utente per i requisiti di ricerca e suggerimenti.
- Se utilizzi modelli per i suggerimenti, consulta anche Requisiti dei dati sugli eventi utente, che elenca requisiti aggiuntivi a seconda del tipo di modello per i suggerimenti e dell'obiettivo di ottimizzazione che prevedi di utilizzare.

Considerazioni sull'importazione degli eventi

Questa sezione descrive i metodi che possono essere utilizzati per l'importazione batch degli eventi utente storici, quando potresti utilizzare ciascun metodo e alcune delle relative limitazioni.

Origine dell'importazione	Descrizione	Quando utilizzarlo	Limitazioni
Cloud Storage	Importa dati JSON da file (≤ 2 GB, max 100) utilizzando la Google Cloud console o `curl`. Supporta gli attributi personalizzati.	Caricamenti di grandi volumi di dati in un unico passaggio.	I dati GA richiedono un'esportazione aggiuntiva in BigQuery prima di essere spostati in Cloud Storage.
BigQuery	Importa da una tabella BigQuery utilizzando lo schema Vertex AI Search for Commerce utilizzando la console Google Cloud o `curl`.	Preelaborazione o analisi dei dati sugli eventi prima dell'importazione.	Richiede la mappatura manuale dello schema; costo delle risorse più elevato per volumi elevati di eventi.
BigQuery + Google Analytics 360	Importazione diretta dei dati di Google Analytics 360 esistenti in Vertex AI Search for commerce.	Monitoraggio delle conversioni GA360 esistente; non è necessaria la mappatura manuale dello schema.	Sottoinsieme limitato di attributi disponibili; la ricerca richiede il monitoraggio delle impressioni GA.
BigQuery + Google Analytics 4	Importazione diretta dei dati Google Analytics 4 esistenti in Vertex AI Search for commerce.	Monitoraggio delle conversioni GA4 esistente; non è necessaria la mappatura manuale dello schema.	È disponibile un sottoinsieme limitato di attributi; la ricerca richiede chiavi del parametro evento `search_query`.
Importazione in linea	Importa utilizzando chiamate di metodi `userEvents.import` dirette.	Requisiti di autenticazione del backend con elevata privacy.	Implementazione più complessa rispetto alle importazioni standard basate sul web.

Limitazioni delle dimensioni

Esiste un limite totale di sistema di 40 miliardi di eventi utente. Di seguito sono riportati i limiti di dimensione per le importazioni di dati in base alla piattaforma di importazione:

Per l'importazione in blocco da Cloud Storage, ogni file deve avere dimensioni massime pari a 2 GB e puoi includere fino a 100 file in un'unica richiesta di importazione in blocco.
Per le importazioni BigQuery, il limite di dimensioni è 128 GB.
Per le importazioni inline, ti consigliamo un massimo di 10.000 eventi utente per richiesta.
Per il numero minimo di giorni per registrare eventi live o importare eventi utente storici per l'addestramento del modello e l'ottimizzazione della ricerca, esegui l'addestramento e l'ottimizzazione del modello. L'addestramento e l'ottimizzazione iniziali del modello possono richiedere da due a cinque giorni o, per set di dati più grandi, più tempo.

Collegare gli eventi di ricerca alle interazioni utente

Per attivare il ranking ottimizzato per le entrate (livello 3) e la personalizzazione (livello 4), il caricamento di eventi search generali non è sufficiente. I modelli Vertex AI Search richiedono un forte segnale di intenzione e soddisfazione dell'utente per capire quali prodotti hanno un buon rendimento per query specifiche. Questo indicatore viene fornito dalle interazioni utente attribuibili. Devi caricare gli eventi successivi, in particolare detail-page-view, add-to-cart e purchase-complete.

Perché le interazioni degli utenti sono importanti

Indicatori di pertinenza: un evento search indica al modello cosa voleva l'utente. Un detail-page-view (clic) indica al modello quale risultato era pertinente.
Indicatori di entrate: gli eventi add-to-cart e purchase-complete indicano al modello quali risultati generano un valore aziendale effettivo.

Soglie di qualità dei dati per l'ottimizzazione

Per attivare i modelli di ottimizzazione delle entrate, i tuoi dati devono soddisfare soglie specifiche di volume e qualità.

Sono obbligatorie le seguenti metriche:

Metrica	Requisito	Contesto
Volume di clic attribuibili	250.000 eventi `detail-page-view` negli ultimi 30 giorni	Questi devono avere un'interazione utente valida che li colleghi a un risultato di ricerca.
Volume degli eventi di ricerca	2.000.000 di eventi negli ultimi 90 giorni	Per stabilire la significatività statistica è necessaria una base di riferimento ampia del traffico di ricerca storico.
Densità dei clic	10 eventi `detail-page-view` in media per prodotto	Garantisce che il modello abbia una copertura del segnale sufficiente in tutto il catalogo (negli ultimi 30 giorni).
Segnale di conversione	0,5 eventi `add-to-cart` in media per prodotto	Consigliato per utilizzare appieno gli obiettivi di massimizzazione delle entrate.
Copertura dei prezzi	Il 95% dei prodotti cercati ha un prezzo	Il modello non può ottimizzare le entrate se non conosce il prezzo dei prodotti restituiti.

Per maggiori informazioni, consulta la pagina Qualità dei dati.

Importazione collettiva utilizzando BigQuery o Cloud Storage

L'utilizzo di BigQuery o Cloud Storage come area di gestione temporanea per i dati sugli eventi utente in Vertex AI Search per le offerte commerciali offre vantaggi distinti:

Resilienza avanzata: l'archiviazione degli eventi in BigQuery o Cloud Storage fornisce un meccanismo di backup affidabile, che consente l'eliminazione e il reingestione, se necessario. Questa resilienza protegge dalla perdita di dati e semplifica il recupero in caso di errori o incoerenze. Il metodo di importazione include anche una resilienza integrata, in cui gli eventi non importati vengono archiviati in bucket di errori insieme ai dettagli dell'errore.
Analisi personalizzata in loco: con gli eventi facilmente accessibili in BigQuery, l'analisi personalizzata può essere eseguita direttamente sui dati degli eventi utente senza la necessità di ulteriori processi di esportazione o trasferimento dei dati. Ciò consente di eseguire workflow di analisi e ottenere insight in tempo reale.
Utilizzo di eventi esistenti: le importazioni collettive possono utilizzare i dati sugli eventi utente esistenti raccolti in vari formati. Un semplice processo di estrazione, trasformazione e caricamento (ETL) può convertire questi dati nel formato di Vertex AI Search for Commerce, eliminando la necessità di modifiche estese al frontend o integrazioni complesse.

I potenziali svantaggi dell'importazione collettiva sono:

Personalizzazione in tempo reale limitata: le funzionalità di personalizzazione in tempo reale sono limitate dalla frequenza delle importazioni collettive. Il ritardo tra la generazione e l'importazione degli eventi può influire sulla reattività dei risultati di ricerca personalizzati.
Misurazione dei KPI e segnalazione degli errori più lente: rispetto allo streaming in tempo reale, le importazioni collettive introducono ritardi nella misurazione dei KPI e nella segnalazione degli errori a causa della natura orientata ai batch del processo. Ciò può ostacolare le risposte immediate a tendenze o problemi emergenti.
Infrastruttura della pipeline ETL: rispetto allo streaming in tempo reale, le pipeline ETL devono essere create e monitorate per rilevare eventuali errori. Deve essere implementato anche un meccanismo per ritentare le importazioni per gli eventi non riusciti (dopo la correzione). L'implementazione potrebbe richiedere alcuni sforzi di sviluppo iniziali.

Comprendere questi compromessi può aiutarti a selezionare l'approccio di importazione degli eventi utente più adatto ai tuoi casi d'uso e alle tue priorità specifici in Vertex AI Search for commerce.

Importa eventi utente da Cloud Storage

Importa gli eventi utente da Cloud Storage utilizzando la console Google Cloud o il metodo userEvents.import.

Console

Vai alla pagina Dati nella console Search for commerce.

Vai alla pagina Dati
Fai clic su Importa per aprire il riquadro Importa dati.
Scegli Eventi utente.
Seleziona Google Cloud Storage come origine dati.
Scegli Schema eventi utente retail come schema.
Inserisci la posizione Cloud Storage dei tuoi dati.
Fai clic su Importa.

curl

Utilizza il metodo userEvents.import per importare gli eventi utente.

Crea un file di dati per i parametri di input per l'importazione. Utilizza l'oggetto GcsSource per indirizzare il bucket Cloud Storage.

Puoi fornire più file o solo uno.
- INPUT_FILE: uno o più file in Cloud Storage contenenti i dati degli eventi utente. Consulta la sezione Informazioni sugli eventi utente per esempi di ciascun formato del tipo di evento utente. Assicurati che ogni evento utente si trovi su una singola riga, senza interruzioni di riga.
- ERROR_DIRECTORY: una directory Cloud Storage per le informazioni sugli errori relativi all'importazione.
I campi del file di input devono essere nel formato gs://<bucket>/<path-to-file>/. La directory degli errori deve essere nel formato gs://<bucket>/<folder>/. Se la directory degli errori non esiste, Vertex AI Search for commerce la crea. Il bucket deve esistere già.
```
{
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  },
  "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}
```

Importa le informazioni del catalogo inviando una richiesta POST al metodo REST userEvents:import, fornendo il nome del file di dati.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl -X POST \
     -v \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     --data @./DATA_FILE.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"
  }
}'

Importare eventi utente da BigQuery

Importa gli eventi utente da BigQuery utilizzando la Google Cloud console o il metodo userEvents.import.

Configurare l'accesso a BigQuery

Segui le istruzioni riportate in Configurazione dell'accesso al set di dati BigQuery per concedere al tuo account di servizio Vertex AI Search for commerce il ruolo Utente BigQuery minimo richiesto per l'importazione e il ruolo aggiuntivo Editor dati BigQuery per il tuo set di dati BigQuery. Il ruolo Proprietario dati BigQuery non è necessario.

Importare gli eventi utente da BigQuery

Puoi importare gli eventi utente utilizzando la console Search for commerce o il metodo userEvents.import.

Console

Vai alla pagina Dati nella console Search for commerce.

Vai alla pagina Dati
Fai clic su Importa per aprire il riquadro Importa dati.
Scegli Eventi utente.
Seleziona BigQuery come origine dati.
Seleziona lo schema dei dati.
- Google Analytics 4: utilizza questo tipo di evento per gli eventi Google Analytics 4.
- Google Analytics 360: utilizza per gli eventi di Google Analytics 360, a meno che tu non importi solo le visualizzazioni di home page da Google Analytics 360 (in questo caso, utilizza lo schema degli eventi utente retail).
- Schema degli eventi utente retail: utilizzalo per importare eventi da origini diverse da Google Analytics e per importare solo le visualizzazioni della home page da Google Analytics 360.
Inserisci la tabella BigQuery in cui si trovano i dati.
(Facoltativo) Inserisci la posizione di un bucket Cloud Storage nel tuo progetto come posizione temporanea per i dati.
Se non specificata, viene utilizzata una posizione predefinita. Se specificati, il bucket BigQuery e Cloud Storage devono trovarsi nella stessa regione.
(Facoltativo) In Mostra opzioni avanzate, inserisci la posizione di un bucket Cloud Storage nel tuo progetto come posizione temporanea per i tuoi dati.

Se non specificata, viene utilizzata una posizione predefinita. Se specificati, BigQuery e il bucket Cloud Storage devono trovarsi nella stessa regione.
Fai clic su Importa.

curl

Importa gli eventi utente includendo i dati degli eventi nella chiamata al metodo userEvents.import. Consulta il riferimento API userEvents.import.

Il valore specificato per dataSchema dipende da ciò che stai importando:

user_event_ga4: da utilizzare per gli eventi Google Analytics 4.
user_event_ga360: utilizza per gli eventi Google Analytics 360, a meno che tu non importi solo le visualizzazioni della home page da Google Analytics 360 (in questo caso, utilizza user_event).
user_event: utilizza questo tipo di proprietà per importare eventi da origini diverse da Google Analytics e per importare solo visualizzazioni di pagine iniziali da Google Analytics 360.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
-v \
-X POST \
-H "Content-Type: application/json; charset=utf-8" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \
--data '{
  "inputConfig": {
    "bigQuerySource": {
      "datasetId": "DATASET_ID",
      "tableId": "TABLE_ID",
      "dataSchema": "SCHEMA_TYPE"
  }
}
}'

Importare eventi utente di Analytics 360 con BigQuery

Le seguenti procedure presuppongono che tu abbia familiarità con l'utilizzo di BigQuery e Analytics 360.

Prima di iniziare

Prima di procedere con i passaggi successivi, assicurati che:

Stai utilizzando l'E-commerce avanzato.
Hai BigQuery collegato ad Analytics 360.

Controllare l'origine dati

Assicurati che i dati sugli eventi utente che importerai siano formattati correttamente in una tabella BigQuery a cui hai accesso.

Assicurati che la tabella si chiami project_id:ga360_export_dataset.ga_sessions_YYYYMMDD.

Per saperne di più sul formato e sulla denominazione delle tabelle, consulta la documentazione di Google Analytics.
Nella console BigQuery Google Cloud , seleziona la tabella dal riquadro Explorer per visualizzarne l'anteprima.

Verifica che:
1. La colonna clientId ha un valore valido, ad esempio 123456789.123456789.
  
  Tieni presente che questo valore è diverso dal valore completo del cookie _ga (che ha un formato come GA1.3.123456789.123456789).
2. La colonna hits.transaction.currencyCode ha un codice valuta valido.
  
  Nota :il tipo di evento purchase-complete Vertex AI Search for Commerce richiede un codice valuta. Se importi eventi di acquisto, che alcuni modelli di Vertex AI Search for Commerce richiedono, aggiorna i report E-commerce avanzato in modo da includere il codice valuta.
3. Se prevedi di importare eventi search, verifica che sia presente una colonna hits.page.searchKeyword o hits.customVariable.searchQuery.
  
  Mentre Vertex AI Search for Commerce richiede sia searchQuery sia productDetails per restituire un elenco di risultati di ricerca, Analytics 360 non memorizza le query di ricerca e le impressioni dei prodotti in un unico evento. Affinché Vertex AI Search for Commerce funzioni, devi creare un tag nel livello dati o un pixel JavaScript per poter importare entrambi i tipi di eventi utente dalle origini Google Analytics:
  - searchQuery, che viene letto dal parametro search_term o dagli eventi view_search_results, deriva da hits.page.searchKeyword o da hits.customVariables.customVarValue se hits.customVariables.customVarName è searchQuery.
  - productDetails, l'impressione del prodotto letta dal parametro items dell'evento view_item_list, viene presa da hits.product se hits.product.isImpressions è TRUE.

Controlla la coerenza degli ID articolo tra il catalogo caricato e la tabella degli eventi utente di Analytics 360.

Utilizzando qualsiasi ID prodotto della colonna hits.product.productSKU nell'anteprima della tabella BigQuery, utilizza il metodo product.get per assicurarti che lo stesso prodotto sia presente nel catalogo caricato.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

   curl \
     -v \
     -X GET \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

Puoi importare gli eventi Google Analytics 360 utilizzando il metodo Cerca nella console per il commercio o userEvents.import.

Console

Vai alla pagina Dati nella console Search for commerce.

Vai alla pagina Dati
Fai clic su Importa per aprire il riquadro Importa dati.
Scegli Eventi utente.
Seleziona BigQuery come origine dati.
Seleziona lo schema dei dati.
- Google Analytics 4: utilizza questo tipo di evento per gli eventi Google Analytics 4.
- Google Analytics 360: utilizza per gli eventi di Google Analytics 360, a meno che tu non importi solo le visualizzazioni di home page da Google Analytics 360 (in questo caso, utilizza lo schema degli eventi utente retail).
- Schema degli eventi utente retail: utilizzalo per importare eventi da origini diverse da Google Analytics e per importare solo le visualizzazioni della home page da Google Analytics 360.
Inserisci la tabella BigQuery in cui si trovano i dati.
(Facoltativo) Inserisci la posizione di un bucket Cloud Storage nel tuo progetto come posizione temporanea per i dati.
Se non specificata, viene utilizzata una posizione predefinita. Se specificati, il bucket BigQuery e Cloud Storage devono trovarsi nella stessa regione.
(Facoltativo) In Mostra opzioni avanzate, inserisci la posizione di un bucket Cloud Storage nel tuo progetto come posizione temporanea per i tuoi dati.

Se non specificata, viene utilizzata una posizione predefinita. Se specificati, BigQuery e il bucket Cloud Storage devono trovarsi nella stessa regione.
Fai clic su Importa.

REST

Importa gli eventi utente includendo i dati degli eventi nella chiamata al metodo userEvents.import.

Per dataSchema, utilizza il valore user_event_ga360.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl \\
  -v \\
  -X POST \\
  -H "Content-Type: application/json; charset=utf-8" \\
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "some_ga360_export_dataset",
        "tableId": "ga_sessions_YYYYMMDD",
        "dataSchema": "user_event_ga360"
    }
  }
}'

Java

public static String importUserEventsFromBigQuerySource()
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  BigQuerySource bigQuerySource = BigQuerySource.newBuilder()
      .setProjectId(PROJECT_ID)
      .setDatasetId(DATASET_ID)
      .setTableId(TABLE_ID)
      .setDataSchema("user_event")
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setBigQuerySource(bigQuerySource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

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

  return operationName;
}

Puoi importare gli eventi utente di Analytics 360 se hai integrato Analytics 360 con BigQuery e utilizzi E-commerce avanzato.

Importare le visualizzazioni della home page di Analytics 360 con BigQuery

In Analytics 360, gli eventi di visualizzazione della home page non si distinguono dagli altri eventi di visualizzazione di pagina. Ciò significa che gli eventi home-page-view non vengono importati come eventi con gli altri tipi di eventi (ad esempio detail-page-view) in Importa gli eventi di Analytics 360.

La seguente procedura spiega come estrarre gli eventi di visualizzazione della home page dai dati di Analytics 360 e importarli in Vertex AI Search for commerce. In breve, questa operazione viene eseguita estraendo le visualizzazioni della home page degli utenti (identificate dal percorso della home page) in una nuova tabella BigQuery e poi importando i dati da questa nuova tabella in Vertex AI Search for commerce.

Per importare gli eventi di visualizzazione della home page da Analytics 360 in Vertex AI Search for commerce:

Crea un set di dati BigQuery o assicurati di averne uno disponibile a cui puoi aggiungere una tabella.

Questo set di dati può trovarsi nel tuo progetto Vertex AI Search for commerce o nel progetto in cui sono presenti i tuoi dati di Analytics 360. È il set di dati di destinazione in cui copierai gli eventi di visualizzazione della home page di Analytics 360.
Crea una tabella BigQuery nel set di dati nel seguente modo:
1. Sostituisci le variabili nel seguente codice SQL come indicato di seguito.
  - target_project_id: il progetto in cui si trova il set di dati del passaggio 1.
  - target_dataset: il nome del set di dati del passaggio 1.
```
CREATE TABLE TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage (
 eventType STRING NOT NULL,
 visitorId STRING NOT NULL,
 userId STRING,
 eventTime STRING NOT NULL
);
```
2. Copia l'esempio di codice SQL.
3. Apri la pagina BigQuery nella console Google Cloud .
  
  Vai alla pagina BigQuery
4. Se non è già selezionato, seleziona il progetto di destinazione.
5. Nel riquadro Editor, incolla il codice SQL di esempio.
6. Fai clic su Esegui e attendi il completamento dell'esecuzione della query.
L'esecuzione di questo codice crea una tabella nel formato target_project_id:target_dataset.ga_homepage_YYYYMMDD, ad esempio my-project:view_events.ga_homepage_20230115.
Copia gli eventi di visualizzazione della home page di Analytics 360 dalla tabella dei dati di Analytics 360 nella tabella creata nel precedente passaggio 2.
1. Sostituisci le variabili nel seguente codice di esempio SQL come segue:
  - source_project_id: l'ID del progetto che contiene i dati di Analytics 360 in una tabella BigQuery.
  - source_dataset: il set di dati nel progetto di origine che contiene i dati di Analytics 360 in una tabella BigQuery.
  - source_table: la tabella nel progetto di origine che contiene i dati di Analytics 360.
  - target_project_id: lo stesso ID progetto di destinazione del precedente passaggio 2.
  - target_dataset: lo stesso set di dati di destinazione del passaggio precedente.
  - Percorso: è il percorso della home page. Di solito è /, ad esempio se la home page è example.com/. Tuttavia, se la home page è come examplepetstore.com/index.html, il percorso è /index.html.
```
INSERT INTO `TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage(eventType,visitorId,userID,eventTime)`

SELECT
  "home-page-view" as eventType,
  clientId as visitorId,
  userId,
  CAST(FORMAT_TIMESTAMP("%Y-%m-%dT%H:%M:%SZ",TIMESTAMP_SECONDS(visitStartTime)) as STRING) AS eventTime

FROM
  `SOURCE_PROJECT_ID.SOURCE_DATASET.SOURCE_TABLE`, UNNEST(hits) as hits

WHERE hits.page.pagePath = "PATH" AND visitorId is NOT NULL;
```
2. Copia l'esempio di codice SQL.
3. Apri la pagina BigQuery nella console Google Cloud .
  
  Vai alla pagina BigQuery
4. Se non è già selezionato, seleziona il progetto di destinazione.
5. Nel riquadro Editor, incolla il codice SQL di esempio.
6. Fai clic su Esegui e attendi il completamento dell'esecuzione della query.
Segui le istruzioni riportate in Importa eventi utente da BigQuery per importare gli eventi di visualizzazione della home page dalla tabella di destinazione. Durante la selezione dello schema, se importi utilizzando la console, seleziona Schema eventi utente retail; se importi utilizzando userEvents.import, specifica user_event per il valore dataSchema.
Elimina la tabella e il set di dati che hai creato nei passaggi 1 e 2.

Importare eventi utente di Google Analytics 4 con BigQuery

Puoi importare gli eventi utente di Google Analytics 4 se hai integrato Google Analytics 4 con BigQuery e utilizzi l'e-commerce di Google Analytics.

Le seguenti procedure presuppongono che tu abbia familiarità con l'utilizzo di BigQuery e Google Analytics 4.

Prima di iniziare

Prima di procedere con i passaggi successivi, assicurati che:

Utilizzi Google Analytics Ecommerce.
Hai BigQuery collegato a Google Analytics 4.

Controllare l'origine dati

Per assicurarti che i dati sugli eventi utente siano preparati per l'importazione, segui questi passaggi.

Per una tabella dei campi Google Analytics 4 utilizzati da Vertex AI Search for commerce e dei campi Vertex AI Search for commerce a cui vengono 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.

Assicurati che i dati sugli eventi utente che importerai siano formattati correttamente in una tabella BigQuery a cui hai accesso.
- Il set di dati deve essere denominato analytics_PROPERTY_ID.
- La tabella deve essere denominata events_YYYYMMDD.
Per informazioni sui nomi e sul formato delle tabelle, consulta la documentazione di Google Analytics.
Nella console BigQuery Google Cloud , seleziona il set di dati dal riquadro Explorer e trova la tabella degli eventi utente che prevedi di importare.

Verifica che:
1. La colonna event_params.key ha una chiave currency e il valore stringa associato è un codice valuta valido.
  
  Nota :il tipo di evento purchase-complete Vertex AI Search for Commerce richiede un codice valuta. Se importi eventi di acquisto, che alcuni modelli di Vertex AI Search for Commerce richiedono, aggiorna i report sugli eventi in modo da includere i codici valuta.
2. Se prevedi di importare eventi search, controlla che la colonna event.event_params.key abbia una chiave search_term e un valore associato.
  
  Mentre Vertex AI Search for Commerce richiede sia searchQuery sia productDetails per restituire un elenco di risultati di ricerca, Google Analytics 4 non memorizza le query di ricerca e le impressioni dei prodotti in un unico evento. Affinché Vertex AI Search for Commerce funzioni, devi creare un tag nel livello dati o da un pixel JavaScript per poter importare entrambi i tipi di eventi utente dalle origini Google Analytics:
  - searchQuery, che viene letto dal parametro search_term o dagli eventi view_search_results.
  - productDetails, l'impressione del prodotto letta dal parametro items dell'evento view_item_list.
  Per informazioni su search in Google Analytics 4, consulta search nella documentazione di Google Analytics.
Verifica la coerenza degli ID articolo tra il catalogo caricato e la tabella degli eventi utente di Google Analytics 4.

Per assicurarti che un prodotto nella tabella degli utenti di Google Analytics 4 sia presente anche nel catalogo caricato, copia un ID prodotto dalla colonna event.items.item_id nell'anteprima della tabella BigQuery e utilizza il metodo product.get per verificare se l'ID prodotto è presente nel catalogo caricato.
```
export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

   curl \
     -v \
     -X GET \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"
```

Importare gli eventi Google Analytics 4

Puoi importare gli eventi Google Analytics 4 utilizzando il metodo Cerca nella console per il commercio o userEvents.import.

Utilizza la console

Vai alla pagina Dati nella console Search for commerce.

Vai alla pagina Dati
Fai clic su Importa per aprire il riquadro Importa dati.
Scegli Eventi utente.
Seleziona BigQuery come origine dati.
Seleziona lo schema dei dati.
- Google Analytics 4: utilizza questo tipo di evento per gli eventi Google Analytics 4.
- Google Analytics 360: utilizza per gli eventi di Google Analytics 360, a meno che tu non importi solo le visualizzazioni di home page da Google Analytics 360 (in questo caso, utilizza lo schema degli eventi utente retail).
- Schema degli eventi utente retail: utilizzalo per importare eventi da origini diverse da Google Analytics e per importare solo le visualizzazioni della home page da Google Analytics 360.
Inserisci la tabella BigQuery in cui si trovano i dati.
(Facoltativo) Inserisci la posizione di un bucket Cloud Storage nel tuo progetto come posizione temporanea per i dati.
Se non specificata, viene utilizzata una posizione predefinita. Se specificati, il bucket BigQuery e Cloud Storage devono trovarsi nella stessa regione.
(Facoltativo) In Mostra opzioni avanzate, inserisci la posizione di un bucket Cloud Storage nel tuo progetto come posizione temporanea per i tuoi dati.

Se non specificata, viene utilizzata una posizione predefinita. Se specificati, BigQuery e il bucket Cloud Storage devono trovarsi nella stessa regione.
Fai clic su Importa.

Utilizzare l'API

Importa gli eventi utente includendo i dati degli eventi nella chiamata al metodo userEvents.import. Consulta il riferimento API userEvents.import.

Per dataSchema, utilizza il valore user_event_ga4.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl \\
  -v \\
  -X POST \\
  -H "Content-Type: application/json; charset=utf-8" \\
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "projectId": "PROJECT_ID",
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event_ga4"
    }
  }
}'

Importare eventi utente in linea

Puoi importare gli eventi utente in linea includendo i dati degli eventi nella chiamata al metodo userEvents.import.

Il modo più semplice per farlo è inserire i dati degli eventi utente in un file JSON e fornire il file a curl.

Per i formati dei tipi di eventi utente, consulta Informazioni sugli eventi utente.

curl

Crea il file JSON:

{
  "inputConfig": {
    "userEventInlineSource": {
      "userEvents": [
        \{
          "<userEvent1>"
        \},
        \{
          "<userEvent2>"
        \},
        \....
      \]
    \}
  }
}

Chiama il metodo POST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data @./data.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"

Java

public static String importUserEventsFromInlineSource(
    List<UserEvent> userEventsToImport)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  UserEventInlineSource inlineSource = UserEventInlineSource.newBuilder()
      .addAllUserEvents(userEventsToImport)
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setUserEventInlineSource(inlineSource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

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

  return operationName;
}

Dati storici del catalogo

Puoi anche importare i dati del catalogo visualizzati negli eventi utente storici. Questi dati del catalogo possono essere utili perché le informazioni sui prodotti passati possono essere utilizzate per arricchire l'acquisizione degli eventi utente, il che a sua volta può migliorare l'accuratezza del modello.

Per maggiori dettagli, vedi Importare i dati storici del catalogo.

Visualizzare gli eventi importati

Visualizza le metriche di integrazione degli eventi nella scheda Eventi della pagina Dati della console Search for commerce. 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

Valutazione del test A/B

A seconda dell'obiettivo del test, si applicano i seguenti parametri per il test A/B:

Per un obiettivo di tasso di click-through (CTR), sono necessari almeno 21 giorni di eventi utente o volumi di eventi specifici. Ad esempio, più di 2 milioni di eventi di ricerca e più di 500.000 clic sulla ricerca.
Per un obiettivo di tasso di conversione (CVR) o entrate, sono necessari almeno 28 giorni di eventi utente o volumi di eventi specifici. Ad esempio, oltre 4 milioni di eventi di ricerca, oltre 1 milione di clic sulla ricerca, oltre 0,5 eventi di acquisto per prodotto ricercabile.

Per saperne di più sui test A/B e sulle best practice, consulta la pagina Test A/B.

Passaggi successivi

Inizia a registrare gli eventi utente.
Gestisci gli eventi utente.

Importare gli eventi utente storici Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Considerazioni sull'importazione degli eventi

Limitazioni delle dimensioni

Collegare gli eventi di ricerca alle interazioni utente

Perché le interazioni degli utenti sono importanti

Soglie di qualità dei dati per l'ottimizzazione

Importazione collettiva utilizzando BigQuery o Cloud Storage

Importa eventi utente da Cloud Storage

Console

curl

Importare eventi utente da BigQuery

Configurare l'accesso a BigQuery

Importare gli eventi utente da BigQuery

Console

curl

Importare eventi utente di Analytics 360 con BigQuery

Prima di iniziare

Controllare l'origine dati

Console

REST

Java

Importare le visualizzazioni della home page di Analytics 360 con BigQuery

Importare eventi utente di Google Analytics 4 con BigQuery

Prima di iniziare

Controllare l'origine dati

Importare gli eventi Google Analytics 4

Utilizza la console

Utilizzare l'API

Importare eventi utente in linea

curl

Java

Dati storici del catalogo

Visualizzare gli eventi importati

Valutazione del test A/B

Passaggi successivi

Importare gli eventi utente storici