Importe eventos históricos do usuário

Nesta página, descrevemos como importar em massa os dados de eventos do usuário de eventos anteriores para a Vertex AI Search for Commerce. Os dados de eventos do usuário são necessários para treinar modelos. Depois de configurar a gravação de eventos em tempo real, pode levar um tempo considerável para registrar dados de evento do usuário suficientes para treinar seus modelos. A importação de dados históricos pode acelerar o processo.

Os procedimentos de importação nesta página se aplicam às recomendações e à pesquisa. Depois que você importa dados, os dois serviços podem usar esses eventos. Portanto, não é necessário importar os mesmos dados duas vezes se você usar os dois serviços.

É possível importar eventos de:

• Cloud Storage.
• BigQuery:
• BigQuery para eventos do Google Analytics 360.
• BigQuery para eventos do Google Analytics 4.
• Eventos in-line usando o método userEvents.import.

Dicas gerais para começar

• Verifique se os dados foram totalmente importados do Google Analytics 4 para o BigQuery.
• Verifique o status da importação no console e consulte os dados de depuração ou erro para solucionar problemas.
• Antes de importar dados históricos de eventos do usuário, consulte as práticas recomendadas para gravar eventos do usuário e a seção Antes de começar nesta página.
• A importação de dados históricos do catálogo pode aprimorar ainda mais os eventos do usuário e melhorar a precisão do modelo.

Tutoriais

Estes tutoriais mostram como importar eventos de usuário de várias fontes.

Importar eventos do Cloud Storage.

Neste tutorial, mostramos como importar eventos de usuário do Cloud Storage.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Importar eventos do BigQuery

Este tutorial mostra como importar eventos de usuário do BigQuery.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Importar eventos inline

Neste tutorial, mostramos como importar dados de eventos do usuário in-line.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Antes de começar

Para evitar erros de importação e verificar se há dados suficientes para gerar bons resultados, analise as seguintes informações antes de importar os eventos do usuário.

• Revise as práticas recomendadas para registrar eventos do usuário.

• A formatação de eventos do usuário varia de acordo com o tipo de evento. Consulte Tipos de eventos de usuários e esquema de exemplos para saber o formato a ser especificado ao criar tabelas para cada tipo de evento.

• As recomendações e a pesquisa têm requisitos mínimos de dados diferentes. Verifique se os eventos do usuário atendem aos requisitos do serviço que você pretende usar:

  • Consulte Requisitos e práticas recomendadas para eventos do usuário para requisitos de pesquisa e recomendações.

  • Se você usa modelos de recomendação, consulte também Requisitos de dados de eventos do usuário, que lista outros requisitos, dependendo do tipo de modelo de recomendação e do objetivo de otimização que você planeja usar.

Considerações sobre importação de eventos

Nesta seção, descrevemos os métodos que podem ser usados para importação em lote de eventos de usuário históricos, quando você pode usar cada método e algumas das limitações deles.

Importar eventos de usuário do Cloud Storage

Importe eventos de usuários do Cloud Storage usando o console Google Cloud ou o método userEvents.import.

Importar eventos de usuário do BigQuery

Importe eventos de usuários do BigQuery usando o console Google Cloud ou o método userEvents.import.

Configurar o acesso ao BigQuery

Siga as instruções em Como configurar o acesso ao conjunto de dados do BigQuery para conceder à conta de serviço da Pesquisa do Vertex AI para e-commerce o papel mínimo de Usuário do BigQuery necessário para que a importação seja concluída e o papel adicional de Editor de dados do BigQuery para seu conjunto de dados do BigQuery. O papel Proprietário de dados do BigQuery não é necessário.

Importar eventos de usuário do BigQuery

É possível importar eventos de usuário usando o console da Pesquisa para e-commerce ou o método userEvents.import.

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"
  }
}
}'

Importar eventos de usuário do Analytics 360 com o BigQuery

Você poderá importar eventos de usuário do Analytics 360 se tiver integrado o Analytics 360 ao BigQuery e usar o comércio eletrônico avançado.

Para os procedimentos a seguir, consideramos que você esteja familiarizado com o uso do BigQuery e do Analytics 360.

Antes de começar

Antes de iniciar as próximas etapas, verifique se:

• Você está usando o e-commerce avançado.
• Você tem o BigQuery vinculado ao Google Analytics 360.

Verificar a fonte de dados

1. Verifique se os dados de eventos de usuário que você vai importar estão formatados corretamente em uma tabela do BigQuery a que você tem acesso.

   Verifique se a tabela se chama project_id:ga360_export_dataset.ga_sessions_YYYYMMDD.

   Consulte a documentação do Google Analytics para mais informações sobre o formato e a nomenclatura da tabela.

2. No console do BigQuery Google Cloud , selecione a tabela no painel do Explorer para visualizar a tabela.

   Verifique se:

   1. A coluna clientId tem um valor válido, por exemplo, 123456789.123456789.

      Esse valor é diferente do valor completo do cookie "_ga" (que tem um formato como GA1.3.123456789.123456789).

   2. A coluna hits.transaction.currencyCode tem um código de moeda válido.

   3. Se você pretende importar eventos search, verifique se há uma coluna hits.page.searchKeyword ou hits.customVariable.searchQuery.

      A Pesquisa da Vertex AI para e-commerce exige searchQuery e productDetails para retornar uma lista de resultados da pesquisa, mas o Analytics 360 não armazena consultas de pesquisa e impressões de produtos em um único evento. Para que a Vertex AI para Pesquisa para Commerce funcione, você precisa criar uma tag na camada de dados ou um pixel JavaScript para importar os dois tipos de eventos do usuário das fontes do Google Analytics:

      • searchQuery, que é lido do parâmetro search_term ou de eventos view_search_results, é derivado de hits.page.searchKeyword ou de hits.customVariables.customVarValue se hits.customVariables.customVarName for searchQuery.
      • productDetails, a impressão do produto que é lida do parâmetro items do evento view_item_list, é extraída de hits.product se hits.product.isImpressions for TRUE.

3. Verifique a consistência dos IDs dos itens entre o catálogo enviado e a tabela de eventos do usuário do Analytics 360.

   Usando qualquer ID do produto da coluna hits.product.productSKU na visualização da tabela do BigQuery, use o método product.get para garantir que o mesmo produto esteja no seu catálogo enviado.

   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"

Importar eventos do Analytics 360

É possível importar eventos do Google Analytics 360 usando o console de pesquisa para comércio ou o método userEvents.import.

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"
    }
  }
}'

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;
}

Importar visualizações da página inicial do Analytics 360 com o BigQuery

No Analytics 360, os eventos de visualização da página inicial não são diferenciados de outros eventos de visualização de página. Isso significa que os eventos de visualização da página inicial não são importados como eventos com os outros tipos de eventos (como visualização da página de detalhes) em Importar eventos do Google Analytics 360.

O procedimento a seguir explica como extrair eventos de visualização da página inicial dos dados do Analytics 360 e importá-los para a Pesquisa da Vertex AI para e-commerce. Em resumo, isso é feito extraindo as visualizações da página inicial dos usuários (identificadas pelo caminho da página inicial) para uma nova tabela do BigQuery e importando os dados dessa nova tabela para a Pesquisa da Vertex AI para e-commerce.

Para importar eventos de visualização da página inicial do Analytics 360 para a Pesquisa da Vertex AI para comércio:

1. Crie um conjunto de dados do BigQuery ou verifique se você tem um disponível para adicionar uma tabela.

   Esse conjunto de dados pode estar no seu projeto da Vertex AI para Pesquisa de comércio ou no projeto em que você tem os dados do Analytics 360. É o conjunto de dados de destino em que você vai copiar os eventos de visualização da página inicial do Analytics 360.

2. Crie uma tabela do BigQuery no conjunto de dados da seguinte maneira:

   1. Substitua as variáveis no código SQL a seguir da seguinte maneira.

      • target_project_id::o projeto em que o conjunto de dados da etapa 1 está localizado.

      • target_dataset::o nome do conjunto de dados da etapa 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. Copie o exemplo de código SQL.

   3. Abra a página do BigQuery no console do Google Cloud .

      Acessar a página do BigQuery

   4. Se ele ainda não estiver selecionado, selecione o projeto de destino.

   5. No painel Editor, cole o exemplo de código SQL.

   6. Clique em play_circle Executar e aguarde a conclusão da consulta.

   A execução desse código cria uma tabela no formato target_project_id:target_dataset.ga_homepage_YYYYMMDD, por exemplo, my-project:view_events.ga_homepage_20230115.

3. Copie os eventos de visualização da página inicial do Analytics 360 da tabela de dados do Analytics 360 para a tabela criada na etapa 2 anterior.

   1. Substitua as variáveis no exemplo de código SQL a seguir:

      • source_project_id::o ID do projeto que contém os dados do Analytics 360 em uma tabela do BigQuery.

      • source_dataset::o conjunto de dados no projeto de origem que contém os dados do Analytics 360 em uma tabela do BigQuery.

      • source_table::a tabela no projeto de origem que contém os dados do Analytics 360.

      • target_project_id::o mesmo ID do projeto de destino da etapa 2 anterior.

      • target_dataset::o mesmo conjunto de dados de destino da etapa 2 anterior.

      • path:é o caminho para a página inicial. Normalmente, isso é /. Por exemplo, se a página inicial for example.com/. No entanto, se a página inicial for como examplepetstore.com/index.html, o caminho será /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. Copie o exemplo de código SQL.

   3. Abra a página do BigQuery no console do Google Cloud .

      Acessar a página do BigQuery

   4. Se ele ainda não estiver selecionado, selecione o projeto de destino.

   5. No painel Editor, cole o exemplo de código SQL.

   6. Clique em play_circle Executar e aguarde a conclusão da consulta.

4. Siga as instruções em Importar eventos de usuário do BigQuery para importar os eventos de visualização da página inicial da tabela de destino. Durante a seleção do esquema, se você importar usando o console, selecione Esquema de eventos do usuário de varejo. Se você importar usando userEvents.import, especifique user_event para o valor de dataSchema.

5. Exclua a tabela e o conjunto de dados que você criou nas etapas 1 e 2.

Importar eventos do usuário do Google Analytics 4 com o BigQuery

Você poderá importar eventos de usuário do Google Analytics 4 se tiver integrado o Google Analytics 4 ao BigQuery e usar o e-commerce do Google Analytics.

Para os procedimentos a seguir, consideramos que você esteja familiarizado com o uso do BigQuery e do Google Analytics 4.

Antes de começar

Antes de iniciar as próximas etapas, verifique se:

• Você está usando o e-commerce do Google Analytics.
• Você tem o BigQuery vinculado ao Google Analytics 4.

Verificar a fonte de dados

Para garantir que os dados de eventos do usuário estejam preparados para importação, siga estas etapas.

Para conferir uma tabela dos campos do Google Analytics 4 usados pela Vertex AI Search para comércio e os campos correspondentes da Vertex AI Search para comércio, consulte Campos de eventos do usuário do Google Analytics 4.

Para todos os parâmetros de evento do Google Analytics, consulte a documentação de referência de eventos do Google Analytics.

1. Verifique se os dados de eventos de usuário que você vai importar estão formatados corretamente em uma tabela do BigQuery a que você tem acesso.

   • O conjunto de dados precisa ser nomeado como analytics_PROPERTY_ID.
   • O nome da tabela precisa ser events_YYYYMMDD.

   Para informações sobre os nomes e o formato das tabelas, consulte a documentação do Google Analytics.

2. No console do BigQuery Google Cloud , selecione o conjunto de dados no painel Explorer e encontre a tabela de eventos do usuário que você planeja importar.

   Verifique se:

   1. A coluna event_params.key tem uma chave currency e o valor de string associado é um código de moeda válido.

   2. Se você pretende importar eventos search, verifique se a coluna event.event_params.key tem uma chave search_term e um valor associado.

      Embora a Vertex AI para Pesquisa de comércio exija searchQuery e productDetails para retornar uma lista de resultados da pesquisa, o Google Analytics 4 não armazena consultas de pesquisa e impressões de produtos em um único evento. Para que a Vertex AI para Pesquisa para Commerce funcione, você precisa criar uma tag na camada de dados ou em um pixel JavaScript para importar os dois tipos de eventos do usuário das fontes do Google Analytics:

      • searchQuery, que é lido do parâmetro search_term ou dos eventos view_search_results.
      • productDetails, a impressão do produto que é lida do parâmetro items do evento view_item_list.

      Para saber mais sobre search no Google Analytics 4, consulte search na documentação do Google Analytics.

3. Verifique a consistência dos IDs dos itens entre o catálogo enviado e a tabela de eventos do usuário do Google Analytics 4.

   Para garantir que um produto na tabela de usuários do Google Analytics 4 também esteja no catálogo enviado, copie um ID da coluna event.items.item_id na visualização da tabela do BigQuery e use o método product.get para verificar se esse ID está no catálogo enviado.

   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"

Importar eventos do Google Analytics 4

É possível importar eventos do Google Analytics 4 usando o console de pesquisa para comércio ou o método userEvents.import.

Use o console.

1. Acesse a página Dados no console da Pesquisa para e-commerce.
   
   Acessar a página "Dados"
2. Clique em Importar para abrir o painel Importar dados.
3. Escolha Eventos do usuário.
4. Selecione BigQuery como a fonte de dados.

5. Selecione o esquema de dados.

   • Google Analytics 4: use para eventos do Google Analytics 4.
   • Google Analytics 360: use para eventos do Google Analytics 360, a menos que você esteja importando apenas visualizações de página inicial do Google Analytics 360. Nesse caso, use o esquema de eventos do usuário de varejo.
   • Esquema de eventos do usuário de varejo: use para importar eventos de fontes que não sejam o Google Analytics e para importar apenas visualizações da página inicial do Google Analytics 360.
6. Insira a tabela do BigQuery em que seus dados estão localizados.
7. Opcional: insira o local de um bucket do Cloud Storage no projeto como um local temporário para seus dados.
   Se não for especificado, um local padrão será usado. Caso seja especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.
8. Opcional: em Mostrar opções avançadas, insira o local de um bucket do Cloud Storage no projeto como um local temporário para seus dados.
   
   Se não for especificado, um local padrão será usado. Caso seja especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.
9. Clique em Importar.

Usar a API

Importe os eventos do usuário incluindo os dados dos eventos na chamada para o método userEvents.import. Consulte a referência da API userEvents.import.

Para dataSchema, use o valor 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"
    }
  }
}'

Importar eventos de usuários in-line

Importe os eventos do usuário in-line incluindo os dados dos eventos na chamada para o método userEvents.import.

A maneira mais fácil de fazer isso é colocar os dados de evento do usuário em um arquivo JSON e fornecer o arquivo para curl.

Para saber os formatos dos tipos de evento do usuário, consulte Sobre eventos do usuário.

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;
}

Dados históricos do catálogo

Também é possível importar os dados do catálogo que aparecem nos eventos históricos do usuário. Esses dados podem ser úteis porque informações anteriores do produto podem ser usadas para enriquecer a captura de eventos do usuário, o que pode melhorar a precisão do modelo.

Para mais detalhes, consulte Importar dados do catálogo histórico.

Ver eventos importados

Confira as métricas de integração de eventos na guia Eventos da página Dados do console do Search para e-commerce. Esta página mostra todos os eventos gravados ou importados no último ano. As métricas podem levar até 24 horas para aparecer após a ingestão de dados.

Acessar a página "Dados"

A seguir

• Comece a gravar eventos de usuários.
• Gerencie seus eventos de usuários.