사용자 이벤트 구성

이 페이지에서는 잠재적인 사용자 이벤트 유형 목록을 포함한 사용자 이벤트 객체를 설명하고 모든 사용자 이벤트 유형의 샘플 데이터를 제공합니다.

사용자 이벤트를 구성하려면 다음 단계를 따르세요.

  1. 이전 사용자 이벤트를 가져옵니다.

  2. 실시간 사용자 이벤트를 기록합니다.

  3. 항목으로 사용자 이벤트에 태그를 지정합니다.

  4. 기여 분석 토큰으로 사용자 이벤트를 신고합니다.

소매업용 Vertex AI Search는 실시간 사용자 이벤트를 사용하여 추천 및 검색결과를 생성합니다. 데이터를 업로드하면 추천 및 검색 모두에서 해당 데이터를 사용할 수 있으므로 두 서비스를 모두 사용할 경우 동일한 이벤트를 두 번 업로드하지 않아도 됩니다.

사용자 이벤트 기록과 관련된 도움말은 실시간 사용자 이벤트 기록을 참조하세요.

사용자 이벤트 유형

사용자가 소매업 사이트를 둘러볼 때 기록할 수 있는 사용자 이벤트 유형은 다음과 같습니다.

사용자 이벤트 이름 사용자 작업
add-to-cart 장바구니에 제품 추가
category-page-view 판매 또는 프로모션 페이지와 같은 특별한 페이지 조회
detail-page-view 제품 세부정보 페이지 보기
home-page-view 홈페이지 조회
purchase-complete 결제 완료
search 카탈로그 검색
shopping-cart-page-view 장바구니 조회

UserEvent 객체에 대한 상세 설명은 UserEvent를 참조하세요.

이벤트 유형 우선순위

최고 품질의 결과를 받으려면 모든 이벤트 유형의 사용자 이벤트를 기록하는 것이 좋습니다. 다음 표에서는 여러 사용자 이벤트 유형의 우선순위를 설명합니다. 데이터 모델 품질을 확보하려면 우선순위가 가장 높은 사용자 이벤트를 로깅해야 합니다.

우선순위 사용자 이벤트
초기 실시간 실험에 필수

add-to-cart

detail-page-view

purchase-complete

home-page-view(추천용)

search(검색용)

시간 경과에 따른 추천 모델 품질 개선에 중요

category-page-view

search

shopping-cart-page-view

사용자 이벤트 요구사항 및 권장사항

다음 표에는 추천과 검색에서 사용하는 사용자 이벤트 유형의 요구사항과 권장사항이 나와 있습니다. 소매업용 Vertex AI Search가 품질 결과를 생성할 수 있도록 사용자 이벤트가 이러한 요구사항을 충족하는지 확인합니다.

이 섹션에는 다음이 나와 있습니다.

추천 모델을 사용하는 경우 사용하려는 추천 모델 유형과 최적화 목표에 따라 추가 요구사항이 나열된 모델 유형 데이터 요구사항도 참조하세요.

Search for Retail 콘솔의 데이터 품질 페이지에서 검색의 데이터 품질 측정항목을 볼 수 있습니다. 이 측정항목은 데이터 품질 권장 수준을 충족하는 제품 및 사용자 이벤트의 비율을 보여줍니다. 검색 데이터 품질을 보는 방법에 대한 자세한 내용은 검색 성능 등급 잠금 해제를 참조하세요.

사용자 이벤트 요구사항

소매업용 Vertex AI Search가 고품질 결과를 생성할 수 있도록 사용자 이벤트가 다음 요구사항을 충족하는지 확인합니다. 이러한 권장사항은 추천과 검색 모두에 적용됩니다.

이벤트 유형 요구사항 영향
모든 이벤트

합성 데이터나 중복 이벤트를 포함하지 마세요.

합성 또는 중복 이벤트는 모델 품질에 부정적인 영향을 미치며 성공적인 모델 학습을 방해하는 경우가 많습니다. 중복 이벤트로 인해 측정항목 값이 잘못될 수 있습니다.

수집된 각 이벤트 유형에 순 방문자 ID를 100개 이상 포함합니다.

이렇게 하면 소매업용 Vertex AI Search가 고품질 결과를 생성할 만큼 충분한 데이터를 확보할 수 있습니다.

방문자 ID는 이벤트 가져오기 또는 이벤트 기록과 API 요청에서 정확히 동일한 형식이어야 합니다.

방문자 ID에 일관된 형식을 사용하면 방문자 패턴을 올바르게 식별하고 사용자 행동을 기준으로 더 나은 품질 결과를 제공할 수 있습니다.

이벤트에 포함된 제품은 제품 카탈로그에 있어야 합니다.

조인되지 않은 이벤트 비율을 최대한 낮게 유지해야 합니다. 비율이 높으면 추천이나 검색결과의 품질이 부정적인 영향을 받을 수 있습니다.

조인되지 않은 이벤트 데이터는 모델을 학습시키는 데 사용되지 않습니다. 하지만 조인되지 않은 이벤트는 나중에 관련 제품이 수집된 후 조인될 수 있습니다. 자세한 내용은 사용자 이벤트 다시 조인을 참조하세요.

일부 사용자 이벤트의 방문자 ID는 동일해야 합니다.

유효한 동작 시퀀스 기록을 구성하려면 소매업용 Vertex AI Search는 동일한 방문자 ID로 여러 이벤트를 볼 수 있어야 합니다.

예를 들어 visitor123은 5개의 제품 세부정보 페이지를 보고 장바구니에 3개의 제품을 추가한 다음 원래 5개의 제품 중 2개를 구매했습니다. 이러한 이벤트가 모두 동일한 형식의 방문자 ID를 제공하는 경우 소매업용 Vertex AI Search는 모델에서 이 동작 시퀀스를 고려할 수 있습니다.

detail-page-view

이벤트당 정확하게 제품 하나를 포함합니다.

제품이 없으면 이벤트를 사용할 수 없습니다. 여러 제품이 포함된 경우 이벤트 형식이 잘못되어 사용할 수 없습니다.

add-to-cart

이벤트당 정확하게 제품 하나를 포함합니다.

여러 제품이 포함된 경우 이벤트 형식이 잘못되어 사용할 수 없습니다.

purchase-complete

purchase_transaction.revenue를 포함합니다.

revenue 필드가 누락된 purchase-complete 이벤트는 모델을 학습하는 데 사용되지 않습니다.

모든 구매 이벤트에 정확히 하나의 purchase_transaction.currency_code를 포함합니다.

기본 통화 코드는 없습니다. 코드를 제공해야 합니다.

이 필드가 없는 구매 이벤트로 인해 잘못된 수익 측정항목이 발생합니다.

일부 구매 이벤트에 여러 제품이 포함되어 있는지 확인합니다.

여러 제품이 포함된 일부 구매 이벤트가 있으면 모델이 공동 구매 패턴을 학습하는 데 도움이 됩니다.

추천 관련 요구사항

추천을 사용하는 경우 사용자 이벤트가 다음 요구사항을 충족하는지 확인합니다.

추천 모델을 사용하는 경우 사용하려는 추천 모델 유형과 최적화 목표에 따라 추가 요구사항이 나열된 모델 유형 데이터 요구사항도 참조하세요.

이벤트 유형 요구사항 영향
purchase-complete

여러 품목의 바구니를 여러 구매 이벤트로 평면화하지 마세요. 여러 제품이 포함된 단일 구매 이벤트로 유지되어야 합니다.

이렇게 하면 유효한 공동 구매 패턴이 생성됩니다.

검색 요구사항

검색을 사용하는 경우 사용자 이벤트가 결과를 얻기 위해서는 다음 최소 요구사항을 충족해야 합니다.

이벤트 유형 요구사항 영향
search

검색 이벤트에는 searchQuery가 있어야 하며 검색 이벤트에는 pageCategories가 있어야 합니다.

이 필드가 포함되지 않으면 검색결과 품질과 측정항목이 부정적인 영향을 받을 수 있습니다.

검색 요청의 방문자 ID는 해당 검색 요청과 관련된 이벤트에서 전송된 방문자 ID와 일치해야 합니다.

일치하지 않을 경우 이벤트 형식이 잘못되고 측정항목이 부정확할 수 있습니다.

검색 이벤트의 제품 ID 목록은 사용자에게 표시되는 전체 제품 목록과 일치해야 합니다.

일치하지 않으면 검색결과 품질이 부정적인 영향을 받을 수 있으며 측정항목이 부정확해집니다.

검색에서 필터를 사용하는 경우 filter가 존재하고 올바르게 파싱되어야 합니다.

이 필드가 없으면 소매업용 Vertex AI Search가 데이터의 필터 부분을 사용할 수 없어 검색 결과 품질이 부정적인 영향을 받을 수 있습니다.

다른 이벤트를 검색 이벤트에 다시 연결하려면 attribution_token 필드를 포함합니다.

기여 분석 토큰이 포함되지 않으면 소매업을 위한 Search에서 오류가 발생하고 검색 품질과 측정항목 정확성에 심각한 부정적인 영향이 발생합니다.

검색 최적화 요구사항

검색이 전체 사용자 트렌드를 기반으로 검색 환경을 자동으로 최적화하도록 하려면 다음 데이터를 업로드합니다.

이벤트를 24시간 이내에 매일 업로드해야 합니다.

이벤트 측정항목 이벤트 볼륨/빈도 설명
search 이벤트 볼륨 지난 90일 동안 250,000개

수집된 이벤트를 기반으로 검색 환경을 최적화하려면 지난 90일 동안 이벤트를 최소 250,000개 이상 수집해야 합니다.

우수한 데이터 품질을 유지하려면 이벤트를 최소한 매일 업로드하는 것이 좋습니다. 이전 이벤트를 가져오는 동안에 데이터 분포에서 최근 타임스탬프로 편향되는지 확인합니다. 마지막 타임스탬프 날짜의 이벤트 수는 평균 일일 이벤트 수와 같거나 더 많아야 합니다.

search 이벤트에 기인하는 detail-page-view의 볼륨 지난 30일 동안 500,000개 사용자 이벤트를 사용하여 검색결과를 최적화하려면 이벤트가 최소 500,000개 이상 필요합니다.
제품당 search 이벤트에 기인하는 평균 detail-page-view 이벤트 지난 30일 동안 10개 지난 21일 동안의 이벤트가 업로드되지 않는 한 수집된 이벤트를 사용하여 검색결과를 최적화하는 데 필요합니다.
파싱 가능한 필터가 있는 search 이벤트의 비율 지난 30일 동안 0.1개 검색 응답의 동적 패싯 순서를 최적화하는 데 권장됩니다.
검색 제품의 가격 비율 지난 30일 동안 0.95개 수집된 이벤트를 사용하여 검색결과를 최적화하는 데 필요합니다.
가격 책정된 제품당 search 이벤트에 기인하는 평균 add-to-cart 이벤트 지난 30일 동안 0.5개 검색결과가 최적화된 수익에 권장됩니다.
검색 가능한 가격 책정 제품당 search 이벤트에 기인하는 평균 purchase-complete 이벤트 지난 30일 동안 0.5개 검색결과가 최적화된 수익에 권장됩니다.

검색 맞춤설정 요구사항

검색에서는 활동을 기반으로 텍스트 검색을 맞춤설정하고 사용자의 검색결과를 탐색하기 위해 다음 데이터를 필요로 합니다.

다음 데이터를 업로드하면 검색이 결과를 자동으로 맞춤설정할 수 있습니다.

이벤트 측정항목 이벤트 볼륨/빈도 설명
검색에서 제공하는 search 이벤트 볼륨 지난 30일 동안 100,000개

맞춤설정을 제공하려면 지난 30일 동안 검색에서 제공한 이벤트가 100,000개 이상 필요합니다.

검색 결과는 캐시되지 않음 최근 사용자 이벤트 100,000개 중 1% 미만

맞춤설정을 사용하려면 텍스트 검색 또는 검색결과 탐색에 대해 검색 결과를 캐시하지 마세요. 방문자 간에 동일한 결과를 재사용하면 검색에서 지정된 사용자에게 적절한 개인화된 결과를 제공할 수 없으며 사용자의 비공개 데이터가 노출될 위험이 있습니다. 캐싱이 감지되면 검색은 자동으로 맞춤설정을 사용 중지합니다.

검색결과만 캐시하는 경우 검색은 계속 탐색 결과를 맞춤설정할 수 있습니다. 반대로 탐색 결과만 캐시하는 경우 검색은 텍스트 쿼리 검색결과를 맞춤설정할 수 있습니다.

방문자 ID가 SearchRequests와 사용자 이벤트 간에 일치합니다. 최근 사용자 이벤트 100,000개에 대해 10% 이상 일치합니다. 방문자 ID 간격과 서식이 SearchRequests 및 사용자 이벤트 간에 일치하는지 확인합니다. 일관된 방문자 ID 서식을 사용하면 검색이 사용자 활동을 올바르게 식별할 수 있습니다.

사용자 이벤트 유형 예시 및 스키마

이 섹션에서는 지원되는 각 이벤트 유형의 데이터 형식을 제공합니다.

JavaScript Pixel 및 태그 관리자의 예시가 제공됩니다. BigQuery에는 각 유형의 전체 테이블 스키마가 제공됩니다.

모든 사용자 이벤트 유형에서 userId는 선택사항입니다. 제품 정보 필드(priceInfoavailability)는 선택사항입니다.

다음 사항을 참고하세요.

  • experimentIds 필드는 A/B 실험을 실행하는 경우에만 필수입니다.
  • attributionToken 필드는 소매업을 위한 Vertex AI Search에만 필요합니다. 실적을 측정하는 데 사용됩니다. 클릭에서 생성된 predict, search, detail-page-view 이벤트에는 이벤트를 생성한 검색 또는 추천에 다시 연결하려면 기여 분석 토큰이 있어야 합니다.
  • 모든 이벤트는 단일 통화를 사용해야 합니다(특히 Google Cloud 콘솔을 사용해 수익 측정항목을 확인하려는 경우). 소매업용 Vertex AI Search API는 카탈로그당 여러 통화의 사용을 지원하지 않습니다.

사용자 이벤트 객체에 대한 자세한 내용은 UserEvent API 참고 문서를 확인하세요.

장바구니에 추가

다음은 add-to-cart 사용자 이벤트 형식을 보여줍니다.

최소 필수 add-to-cart 객체

다음 예시는 add-to-cart 사용자 이벤트 형식의 필수 입력란만 보여줍니다.

이벤트를 가져올 때는 eventTime 필드에 RFC 3339로 지정된 형식으로 타임스탬프를 제공해야 합니다.

사용된 API 메서드에 따라 또는 추가 필드가 사용되는지 여부에 따라 다른 필드가 필요할 수 있습니다. (예를 들어 사용자 이벤트가 항목과 연결되어 있는 경우 entity 필드를 지정해야 합니다.) 각 필드에 대한 자세한 내용과 필요한 필드는 UserEvent API 참고 문서를 확인하세요.

자바스크립트 Pixel

var user_event = {
  "eventType": "add-to-cart",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": { "value": product-quantity
  }]
};

태그 관리자

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'add-to-cart',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }]
      }
    });
</script>

BigQuery

이 사용자 이벤트 유형의 전체 JSON 스키마입니다. BigQuery에서 이 사용자 이벤트 유형의 테이블을 만들 때 이 스키마를 지정합니다.

필수 필드의 모드는 REQUIRED 또는 REPEATED로 설정됩니다. 선택 필드의 모드는 NULLABLE로 설정됩니다.

BigQuery로 이벤트를 가져오려면 eventTime이 필수입니다. eventTime은 타임스탬프 형식의 문자열입니다.

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

카테고리 페이지 조회

다음은 category-page-view 사용자 이벤트 형식을 보여줍니다.

최소 필수 category-page-view 객체

다음 예시는 category-page-view 사용자 이벤트 형식의 필수 입력란만 보여줍니다.

일반적으로 페이지와 연결된 카테고리는 하나이지만 pageCategories 필드는 카테고리 계층 구조도 지원하므로 목록으로 제공할 수 있습니다.

이벤트를 가져올 때는 eventTime 필드에 RFC 3339로 지정된 형식으로 타임스탬프를 제공해야 합니다.

사용된 API 메서드에 따라 또는 추가 필드가 사용되는지 여부에 따라 다른 필드가 필요할 수 있습니다. (예를 들어 사용자 이벤트가 항목과 연결되어 있는 경우 entity 필드를 지정해야 합니다.) 각 필드에 대한 자세한 내용과 필요한 필드는 UserEvent API 참고 문서를 확인하세요.

자바스크립트 Pixel

var user_event = {
  "eventType": "category-page-view",
  "visitorId": "visitor-id",
  "pageCategories": ["category1 > category2"]
};

태그 관리자

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'category-page-view',
        'visitorId": 'visitor-id',
        // You can also define the user ID and visitor ID
        // directly on the Tag Manager tag.
        'pageCategories': ['category1 > category2']
      }
    });
</script>

BigQuery

이 사용자 이벤트 유형의 전체 JSON 스키마입니다. BigQuery에서 이 사용자 이벤트 유형의 테이블을 만들 때 이 스키마를 지정합니다.

필수 필드의 모드는 REQUIRED 또는 REPEATED로 설정됩니다. 선택 필드의 모드는 NULLABLE로 설정됩니다.

BigQuery로 이벤트를 가져오려면 eventTime이 필수입니다. eventTime은 타임스탬프 형식의 문자열입니다.

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

세부정보 페이지 조회

다음은 detail-page-view 사용자 이벤트 데이터 형식을 보여줍니다.

최소 필수 detail-page-view 객체

다음 예시는 detail-page-view 사용자 이벤트 형식의 필수 입력란만 보여줍니다.

대부분의 경우 productDetails에는 연결된 제품의 세부정보가 포함됩니다. 단, 상품을 묶어서 함께 판매하는 경우는 예외입니다.

이벤트를 가져올 때는 eventTime 필드에 RFC 3339로 지정된 형식으로 타임스탬프를 제공해야 합니다.

사용된 API 메서드에 따라 또는 추가 필드가 사용되는지 여부에 따라 다른 필드가 필요할 수 있습니다. (예를 들어 사용자 이벤트가 항목과 연결되어 있는 경우 entity 필드를 지정해야 합니다.) 각 필드에 대한 자세한 내용과 필요한 필드는 UserEvent API 참고 문서를 확인하세요.

자바스크립트 Pixel

var user_event = {
  "eventType": "detail-page-view",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    }
  }]
};

태그 관리자

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'detail-page-view',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          }
        }]
      }
    });
</script>

BigQuery

이 사용자 이벤트 유형의 전체 JSON 스키마입니다. BigQuery에서 이 사용자 이벤트 유형의 테이블을 만들 때 이 스키마를 지정합니다.

필수 필드의 모드는 REQUIRED 또는 REPEATED로 설정됩니다. 선택 필드의 모드는 NULLABLE로 설정됩니다.

BigQuery로 이벤트를 가져오려면 eventTime이 필수입니다. eventTime은 타임스탬프 형식의 문자열입니다.

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

홈페이지 조회

다음은 home-page-view 사용자 이벤트 형식을 보여줍니다.

최소 필수 home-page-view 객체

다음 예시는 home-page-view 사용자 이벤트 형식의 필수 입력란만 보여줍니다.

이벤트를 가져올 때는 eventTime 필드에 RFC 3339로 지정된 형식으로 타임스탬프를 제공해야 합니다.

사용된 API 메서드에 따라 또는 추가 필드가 사용되는지 여부에 따라 다른 필드가 필요할 수 있습니다. (예를 들어 사용자 이벤트가 항목과 연결되어 있는 경우 entity 필드를 지정해야 합니다.) 각 필드에 대한 자세한 내용과 필요한 필드는 UserEvent API 참고 문서를 확인하세요.

자바스크립트 Pixel

var user_event = {
  "eventType": "home-page-view",
  "visitorId": "visitor-id",
};

태그 관리자

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'home-page-view',
        'visitorId': 'visitor-id'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
      }
    });
</script>

BigQuery

이 사용자 이벤트 유형의 전체 JSON 스키마입니다. BigQuery에서 이 사용자 이벤트 유형의 테이블을 만들 때 이 스키마를 지정합니다.

필수 필드의 모드는 REQUIRED 또는 REPEATED로 설정됩니다. 선택 필드의 모드는 NULLABLE로 설정됩니다.

BigQuery로 이벤트를 가져오려면 eventTime이 필수입니다. eventTime은 타임스탬프 형식의 문자열입니다.

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

구매 완료

다음은 purchase-complete 사용자 이벤트 데이터 형식을 보여줍니다.

최소 필수 purchase-complete 객체

다음 예시는 purchase-complete 사용자 이벤트 형식의 필수 입력란만 보여줍니다.

이벤트를 가져올 때는 eventTime 필드에 RFC 3339로 지정된 형식으로 타임스탬프를 제공해야 합니다.

사용된 API 메서드에 따라 또는 추가 필드가 사용되는지 여부에 따라 다른 필드가 필요할 수 있습니다. (예를 들어 사용자 이벤트가 항목과 연결되어 있는 경우 entity 필드를 지정해야 합니다.) 각 필드에 대한 자세한 내용과 필요한 필드는 UserEvent API 참고 문서를 확인하세요.

자바스크립트 Pixel

var user_event = {
  "eventType": "purchase-complete",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": product-quantity
  }],
  "purchaseTransaction": {
    "revenue": revenue,
    "currencyCode": "currency-code"
  }
};

태그 관리자

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'purchase-complete',
        'visitorId': 'visitor-id',
        // You can also define the visitor id directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }],
        'purchaseTransaction': {
          'revenue': revenue,
          'currencyCode': 'currency-code'
        }
      }
    });
</script>

BigQuery

이 사용자 이벤트 유형의 전체 JSON 스키마입니다. BigQuery에서 이 사용자 이벤트 유형의 테이블을 만들 때 이 스키마를 지정합니다.

필수 필드의 모드는 REQUIRED 또는 REPEATED로 설정됩니다. 선택 필드의 모드는 NULLABLE로 설정됩니다.

BigQuery로 이벤트를 가져오려면 eventTime이 필수입니다. eventTime은 타임스탬프 형식의 문자열입니다.

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         },
         {
           "name": "priceInfo",
           "type": "RECORD",
           "mode": "NULLABLE",
           "fields": [
             {
               "name": "price",
               "type": "FLOAT",
               "mode": "REQUIRED"
             },
             {
               "name": "originalPrice",
               "type": "FLOAT",
               "mode": "NULLABLE"
             },
             {
               "name": "currencyCode",
               "type": "STRING",
               "mode": "REQUIRED"
             },
             {
               "name": "cost",
               "type": "FLOAT",
               "mode": "NULLABLE"
             }
           ]
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "purchaseTransaction",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "revenue",
       "type": "FLOAT",
       "mode": "REQUIRED"
     },
     {
       "name": "tax",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "cost",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "currencyCode",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

다음은 search 사용자 이벤트 형식을 보여줍니다.

최소 필수 search 객체

소매업용 Vertex AI Search가 작동하려면 다음과 같은 최소 필수 입력란이 필요합니다.

  • 검색 결과 목록을 반환하려면 소매업용 Vertex AI Search에 searchQueryproductDetails가 모두 필요합니다.

    • searchQuerysearch_term 매개변수 또는 view_search_results 이벤트에서 읽습니다.
    • productDetailsview_item_list 이벤트의 items 매개변수에서 읽습니다. 검색 결과 페이지에 최종 사용자에게 표시되는 제품 ID 목록을 포함해야 합니다.
  • searchQuery 또는 pageCategories 필드 중 하나 이상이 필요합니다.

다음 예시는 search 사용자 이벤트 형식의 필수 입력란만 보여줍니다.

이벤트를 가져올 때는 eventTime 필드에 RFC 3339로 지정된 형식으로 타임스탬프를 제공해야 합니다.

사용된 API 메서드에 따라 또는 추가 필드가 사용되는지 여부에 따라 다른 필드가 필요할 수 있습니다. (예를 들어 사용자 이벤트가 항목과 연결되어 있는 경우 entity 필드를 지정해야 합니다.) 각 필드에 대한 자세한 내용과 필요한 필드는 UserEvent API 참고 문서를 확인하세요.

자바스크립트 Pixel

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
};

태그 관리자

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
      }
    });
</script>

BigQuery

이 사용자 이벤트 유형의 전체 JSON 스키마입니다. BigQuery에서 이 사용자 이벤트 유형의 테이블을 만들 때 이 스키마를 지정합니다.

필수 필드의 모드는 REQUIRED 또는 REPEATED로 설정됩니다. 선택 필드의 모드는 NULLABLE로 설정됩니다.

BigQuery로 이벤트를 가져오려면 eventTime이 필수입니다. eventTime은 타임스탬프 형식의 문자열입니다.

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

자동 완성

이 필드는 Autocomplete를 사용하려는 경우 검색 이벤트에만 필요합니다. 검색 시 필요하지 않습니다.

다음 예시는 사용자가 'sh'를 입력하고 추천 목록에서 두 번째 추천인 'shoes'를 클릭하여 검색 이벤트를 트리거할 때 completionDetail 필드를 보여줍니다. 사용자가 추천을 클릭하지 않으면 completionDetail 필드는 비어 있습니다.

eventType"search"여야 합니다.

completionAttributionTokencompleteQuery 응답의 attributionToken입니다.

selectedSuggestionsearchQuery와 같아야 합니다.

자바스크립트 Pixel

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
  "completionDetail": {
    "completionAttributionToken": "completion_token",
    "selectedSuggestion": "search-query",
    "selectedPosition": completion_position
  }
};

태그 관리자

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
        "completionDetail": {
          "completionAttributionToken": 'completion_token',
          "selectedSuggestion": 'search-query',
          "selectedPosition": completion_position
        }
      }
    });
</script>

BigQuery

이 사용자 이벤트 유형의 전체 JSON 스키마입니다. BigQuery에서 이 사용자 이벤트 유형의 테이블을 만들 때 이 스키마를 지정합니다.

필수 필드의 모드는 REQUIRED 또는 REPEATED로 설정됩니다. 선택 필드의 모드는 NULLABLE로 설정됩니다.

BigQuery로 이벤트를 가져오려면 eventTime이 필수입니다. eventTime은 타임스탬프 형식의 문자열입니다.

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "completionDetail",
   "type": "RECORD"
   "mode": "NULLABLE"
   "fields": [
     {
       "name": "completionAttributionToken",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedSuggestion",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedPosition",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
    ]
 }
]

장바구니 페이지 조회

다음은 shopping-cart-page-view 사용자 이벤트 데이터 형식을 보여줍니다.

최소 필수 shopping-cart-page-view 객체

다음 예시는 shopping-cart-page-view 사용자 이벤트 형식의 필수 입력란만 보여줍니다.

장바구니가 비어 있지 않다면 productDetails 객체를 제공하세요.

이벤트를 가져올 때는 eventTime 필드에 RFC 3339로 지정된 형식으로 타임스탬프를 제공해야 합니다.

사용된 API 메서드에 따라 또는 추가 필드가 사용되는지 여부에 따라 다른 필드가 필요할 수 있습니다. (예를 들어 사용자 이벤트가 항목과 연결되어 있는 경우 entity 필드를 지정해야 합니다.) 각 필드에 대한 자세한 내용과 필요한 필드는 UserEvent API 참고 문서를 확인하세요.

자바스크립트 Pixel

var user_event = {
  "eventType": "shopping-cart-page-view"",
  "visitorId": "VISITOR-ID"
  "cartId": "CART-ID",
  "productDetails": [{
      "product": {
        "id": "PRODUCT-ID"
      },
      "quantity": PRODUCT-QUANTITY
    }]
};

PRODUCT-ID, PRODUCT-QUANTITY, VISOTOR-ID, CART-ID를 제품 ID, 제품 수량, 세션 ID, 장바구니 ID로 바꿉니다.

태그 관리자

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'shopping-cart-page-view',
        'visitorId': 'VISITOR-ID'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'cartId': 'CART-ID',
        'productDetails': [{
            'product': {
              'id': 'PRODUCT-ID'
            },
            'quantity': PRODUCT-QUANTITY
          }]
      }
    });
</script>

PRODUCT-ID, PRODUCT-QUANTITY, VISOTOR-ID, CART-ID를 제품 ID, 제품 수량, 세션 ID, 장바구니 ID로 바꿉니다.

BigQuery

이 사용자 이벤트 유형의 전체 JSON 스키마입니다. BigQuery에서 이 사용자 이벤트 유형의 테이블을 만들 때 이 스키마를 지정합니다.

필수 필드의 모드는 REQUIRED 또는 REPEATED로 설정됩니다. 선택 필드의 모드는 NULLABLE로 설정됩니다.

BigQuery로 이벤트를 가져오려면 eventTime이 필수입니다. eventTime은 타임스탬프 형식의 문자열입니다.

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Google 애널리틱스 4 사용자 이벤트 필드

다음 표에서는 Google 애널리틱스 4 사용자 이벤트 필드가 소매업용 Vertex AI Search 필드에 매핑되는 방식을 보여줍니다.

Google 애널리틱스 4에서 사용자 이벤트를 가져오거나 기록하기 전에 소매업용 Vertex AI Search가 데이터를 올바르게 통합할 수 있도록 Google 애널리틱스 4 사용자 이벤트가 다음 필드를 사용하는지 확인해야 합니다.

Google 애널리틱스 4 소매업
ecommerce.purchase_revenue purchaseTransaction.revenue
event_name eventType
event_timestamp eventTime
items.item_id productDetails.product.id
items.price productDetails.product.priceInfo.price
items.quantity productDetails.quantity
키:
event_params.key"currency"로 설정

값:
event_params.value.string_value
productDetails.product.priceInfo.currencyCode
키:
event_params.key"currency"로 설정

값:
event_params.value.string_value
purchaseTransaction.currencyCode
키:
event_params.key"search_term"으로 설정

값:
event_params.value.string_value
searchQuery
user_id userInfo.userId
user_pseudo_id visitorId

맞춤 속성

사용자 이벤트에 대한 추가 맞춤 속성 및 기능을 포함할 수 있습니다. 이를 사용하면 추천을 사용할 때 사용자에게 보다 구체적인 추천이 제공될 수 있습니다. 맞춤 속성을 추가하려면 사용자 이벤트를 기록할 때 attributes를 사용합니다.

수집된 사용자 이벤트에 대해 맞춤 속성을 제공할 경우 예측 요청과 연결된 사용자 이벤트에도 해당 속성을 포함해야 합니다. 맞춤 속성의 형식은 가져온 이벤트와 예측 요청으로 제공된 이벤트 간에 일관되어야 합니다. 이렇게 하면 모델 학습 및 예측 제공 시 이러한 커스텀 속성을 사용할 수 있으므로 추천 품질을 개선할 수 있습니다.

text 필드를 사용하여 커스텀 텍스트 값을 제공하거나 number 필드를 사용하여 커스텀 숫자 값을 제공할 수 있습니다.

예를 들어 다음은 사용자 이벤트 기록 요청의 attributes 섹션을 보여줍니다.

"attributes": {
  "user_age": {"text": ["teen", "young adult"]},
  "user_location": {"text": ["CA"]}
}

사용자 정보

visitorId는 순 사용자 식별자를 나타내며 사용자 이벤트를 기록할 때 필요합니다.

사용자 이벤트를 기록할 때 포함되는 사용자 정보(UserInfo)에는 visitorId 값과 userId 값(있는 경우)이 포함됩니다. userId는 선택사항이며 사용자가 사이트에 로그인할 때마다 여러 기기에서 사용자의 고유한 영구 식별자로 사용할 수 있습니다. 사용자의 userId를 기록할 때 소매업용 Vertex AI Search는 휴대기기와 웹브라우저 등 여러 기기에서 사용자 한 명에 대해 더욱 맞춤설정된 결과를 생성할 수 있습니다.

타임스탬프 정보

사용자 이벤트를 기록할 때는 이벤트가 발생한 시점의 정확한 타임스탬프를 포함해야 합니다. 정확한 타임스탬프를 사용하면 이벤트가 올바른 순서로 저장될 수 있습니다. 태그 관리자 및 JavaScript Pixel을 사용하여 수집된 이벤트의 타임스탬프는 자동으로 기록됩니다. 이벤트를 가져올 때는 eventTime 필드에 RFC 3339로 지정된 형식으로 타임스탬프를 제공해야 합니다.

다음 단계