이 페이지에서는 실시간 사용자 이벤트를 기록하는 방법을 설명합니다. 소매업용 Vertex AI Search는 실시간 사용자 이벤트를 사용하여 추천 및 검색결과를 생성합니다. 유효한 제품 정보로 가능한 한 많은 유형의 사용자 이벤트를 기록하면 결과의 품질이 향상됩니다.
이 페이지의 기록 절차는 추천 및 검색 모두에 적용됩니다. 데이터를 기록한 후에 두 서비스 모두에서 해당 이벤트를 사용할 수 있으므로 두 서비스를 모두 사용하는 경우 동일한 데이터를 두 번 업로드하지 않아도 됩니다.
사용자 이벤트 유형 및 모든 유형에 대한 샘플 JSON을 포함하여 사용자 이벤트에 대한 상세 설명은 사용자 이벤트 정보를 참조하세요.
여러 방법으로 사용자 이벤트를 기록할 수 있습니다.
자바스크립트 Pixel 사용
백엔드 서버에서 API로 직접 이벤트 전송
태그 관리자 태그 사용
이러한 모든 메서드에 대해 detail-page-view
유형의 사용자 이벤트 기록 예시는 아래에서 찾아볼 수 있습니다. 다른 이벤트 유형은 사용자 이벤트 정보를 참조하세요.
이전 사용자 이벤트도 가져올 수 있습니다. 모델을 학습시키는 데 충분한 사용자 이벤트 데이터를 기록하기까지 상당한 시간이 걸릴 수 있습니다. 이전 이벤트에서 사용자 이벤트 데이터를 일괄적으로 가져와 초기 모델 학습을 가속화할 수 있습니다. 이전 사용자 이벤트 가져오기를 참조하세요.
기록 중인 사용자 이벤트가 사용자가 이전에 제공된 추천이나 검색 결과를 기반으로 제품과 처음 상호작용하는 경우 기여 분석 토큰을 포함하여 성능 측정항목을 제공할 수 있습니다. 소매업을 위한 Vertex AI Search가 작동하려면 기여 분석 토큰을 포함해야 합니다. 기여 분석 토큰 사용 방법에 대한 상세 설명은 기여 분석 토큰을 참조하세요.
방문자 ID는 사용자 이벤트를 기록할 때 필요합니다. 방문자 ID 및 사용자 ID에 대한 자세한 내용은 사용자 정보를 참조하세요.
서버 측 태그 지정으로 사용자 이벤트 기록
서버 측 태그 지정을 사용하면 여러 다운스트림 클라이언트를 포함하는 단일 서버 측 컨테이너를 배포할 수 있습니다. 이렇게 하면 여러 서버 측 소비자를 포함하는 단일 정보 소스가 클라이언트 측에 생성됩니다. 이 아키텍처는 웹의 부하를 서버로 이전하므로 웹사이트 성능을 극대화하려는 사용자에게 적합합니다.
서버 측 태그 지정에는 단일 서버 측 태그가 여러 업스트림 클라이언트(예: 웹 및 모바일)를 지원할 수도 있다는 이점도 있습니다. 서버 측 태그 지정을 설정하는 방법을 알아보세요.
소매업용 Vertex AI Search는 자체적으로 서버 측 태그를 기본 제공합니다.
Cloud Retail 서버 측 태그는 Cloud Retail 웹 태그와 비슷한 다음과 같은 매개변수를 요구하고 수락합니다.
- 프로젝트 번호
- API 키(인증용)
visitorId
및searchQuery
등의 키 필드에 대한 재정의
Cloud Retail 태그의 서버 버전과 웹 버전의 주요 차이점은 데이터 소스를 정의할 수 없다는 것입니다. 서버 태그의 데이터 소스는 GA4 스키마의 Google 태그에서 전송된 데이터 스트림입니다.
사용자 이벤트 작성 튜토리얼
이 튜토리얼에서는 userEvents.write
메서드를 사용하여 사용자 이벤트를 기록하는 방법을 보여줍니다.
Cloud Shell 편집기에서 이 태스크의 단계별 안내를 직접 수행하려면 둘러보기를 클릭합니다.
시작하기 전에
사용자 이벤트를 기록하기 전에 다음 항목이 있어야 합니다.
인증이 설정된 Google Cloud 프로젝트
유효한 API 키(자바스크립트 Pixel 또는 태그 관리자용) 또는 API를 사용하여 직접 쓰는 경우 Retail 편집자 역할이 할당된 유효한 서비스 계정
자세한 내용은 시작하기 전에를 참조하세요.
사용자 이벤트 기록 권장사항
소매업용 Vertex AI Search에서 고품질 결과를 생성하려면 고품질 데이터가 필요합니다. 데이터가 안전하지 않거나 잘못된 경우 결과 품질이 저하됩니다.
사용자 이벤트를 기록할 때는 다음 권장사항을 구현해야 합니다.
카탈로그를 가져오기 전 또는 가져오는 동안 사용자 이벤트를 기록하는 경우 카탈로그 가져오기가 완료되기 전에 기록된 모든 이벤트를 재조인하세요.
사용자 이벤트를 기록하기 전이나 후 또는 동시에 카탈로그 가져오기를 수행할 수 있습니다. 카탈로그가 크고 사용자 이벤트가 많으면 이러한 작업을 병렬로 수행하여 시간을 절약할 수 있습니다. 카탈로그 가져오기가 완료된 다음에는 API를 사용해서 가져오기가 완료되기 전 업로드된 이벤트를 다시 조인해야 합니다.
소매업용 Vertex AI Search는 사용자 이벤트가 생성될 때 기록된 사용자 이벤트를 제품 카탈로그의 메타데이터와 조인하려고 합니다. 성공적으로 조인된 이벤트만 학습에 사용되므로 카탈로그를 완전히 가져오기 전에 기록된 이벤트에 재조인해야 합니다. 카탈로그에 없는 항목을 참조하는 이벤트는 삭제되거나 올바른 제품과 연결되지 않습니다. 마찬가지로, 과거의 사용자 이벤트를 가져오는 경우 참조하는 모든 제품이 카탈로그에 포함되어야 합니다. 이전 제품을 카탈로그에서 삭제하지 않고
OUT_OF_STOCK
으로 표시할 수 있습니다.-
사용자 이벤트를 기록하면 사용자 이벤트에 포함된 제품이 현재 카탈로그에 연결됩니다. 현재 카탈로그에 없는 제품에 대해 이벤트를 기록하면 모델을 학습하는 데 사용할 수 없습니다. 이를 '조인되지 않은' 이벤트라고 부릅니다. 카탈로그를 완전히 가져오기 전에 이벤트를 기록한 경우에는 가져오기 중에 기록된 이벤트를 다시 조인해야 합니다. 일부 이벤트는 조인되지 않을 수 있습니다. 하지만 조인되지 않은 이벤트 백분율이 총 사용자 이벤트 중 5%를 초과하면 카탈로그가 최신 상태인지 확인하고, 카탈로그가 완전히 업데이트되기 전 기록된 이벤트를 다시 조인하고, 조인되지 않은 이벤트가 생성되는 이유를 조사해야 합니다.
이벤트 필터링을 사용하여 조인되지 않은 이벤트를 확인할 수 있습니다. 자세히 알아보기
사용자 이벤트에 최대한 많은 정보를 제공하세요.
각 사용자 이벤트에는 필수 및 허용되는 여러 정보가 포함됩니다. 자세한 내용은 사용자 이벤트 정보를 참조하세요.
사용자 이벤트 기록 프로세스가 중단될 경우 알 수 있도록 Cloud Monitoring 알림을 설정하세요.
일괄 사용자 이벤트 가져오기를 수행할 때는 가져올 데이터의 크기를 제한하세요.
일괄 사용자 이벤트 가져오기는 완료하는 데 최대 24시간이 걸릴 수 있습니다.
각 파일의 크기는 2GB 이하여야 합니다. 가져오기 요청 하나에 최대 100개의 파일을 포함할 수 있습니다. 한 가지 방법은 하루 한 번만 사용자 이벤트를 가져오는 것입니다.
일괄 가져오기를 수행한 후 오류 보고를 검토하여 데이터를 올바르게 가져왔는지 확인합니다.
사용자 이벤트 데이터를 가져올 때 각 사용자 이벤트의 정확한 타임스탬프를 포함하고, 타임스탬프가 동일한 순차 사용자 이벤트를 가져오지 않도록 합니다.
잘못된 사용자 이벤트를 가져왔으면 소매업용 Vertex AI Search 담당자에게 연락하여 문제 해결 방법을 문의하세요.
가능하다면 사용자 이벤트 데이터가 연속되게 유지합니다.
사용자 이벤트 데이터에 격차가 있을 경우 모델 품질이 저하될 수 있습니다.
안전한 형태의 고유 식별자를 사용하여 소매업용 Vertex AI Search에 사용자를 익명으로 유지하고 사용자 개인정보를 보호하세요. 사용자는 이메일 또는 집 주소와 같은 PII(개인 식별 정보)를 데이터에서 수정할 책임이 있습니다.
자바스크립트 Pixel로 사용자 이벤트 기록
다음 예시에서는 자바스크립트 Pixel을 사용하여 detail-page-view
UserEvent를 기록합니다.
<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>
Google 애널리틱스 360으로 사용자 이벤트를 가져왔으면 visitorID
를 Google Analytics 클라이언트 ID로 설정합니다. Google Analytics 클라이언트 ID가 전체 _ga cookie 이름의 일부인지 확인합니다(예: 클라이언트 ID 123456789.123456789
는 _ga cookie GA1.3.123456789.123456789
의 일부).
다음은 사용자 이벤트에 클라이언트 ID를 설정하는 형식을 보여주는 축약형 예시입니다. 'G-XXXXXX'를 Google 애널리틱스 추적 ID로 바꿉니다.
<script type="text/javascript"> var tracker = ga.getByName('G-XXXXXX'); var user_event = { "visitorId": tracker.get('clientId') }; </script>
userEvents.write
메서드로 사용자 이벤트 기록
userEvents.write
메서드를 사용하면 백엔드 서버에서 API로 직접 사용자 이벤트를 보낼 수 있습니다.
사용자 이벤트를 기록하려면 POST
요청을 userEvents.write
메서드로 전송하고 적절한 요청 본문을 제공합니다.
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
Google 애널리틱스 4로 사용자 이벤트 기록
소매업용 Vertex AI Search에 Google 애널리틱스 4 사용자 이벤트 데이터를 기록할 수 있습니다.
데이터 소스 확인
가져오려는 사용자 이벤트 데이터의 형식이 올바른지 확인합니다.
소매업용 Vertex AI Search에서 사용하는 Google 애널리틱스 4 필드와 이러한 필드가 매핑되는 소매업 필드용 Vertex AI Search에 대한 표는 Google 애널리틱스 4 사용자 이벤트 필드를 참조하세요.
모든 Google 애널리틱스 이벤트 매개변수는 Google 애널리틱스 이벤트 참고 문서를 확인하세요.
다음 사항을 확인합니다.
일부 소매업용 Vertex AI Search 모델에 필요한 구매 이벤트를 가져오는 경우 이벤트 보고에 통화 코드가 포함됩니다. Google 애널리틱스 문서의
purchase
이벤트 매개변수를 참고하세요.search
이벤트를 가져오려는 경우 이벤트 보고에 검색어가 포함됩니다.search
이벤트 가져오기는 지원되지만 Google 애널리틱스 4는 기본적으로 소매업용 Vertex AI Searchsearch
이벤트 유형을 지원하지 않으므로 다른 이벤트 유형과 동일한 방식으로 Google 애널리틱스 4에서search
이벤트가 매핑되지 않습니다. 가져오는 동안search
이벤트는view_item_list
및search_term
이벤트 매개변수의 정보를 결합하여 Google 애널리틱스 4에서 구성됩니다.Google 애널리틱스 문서의
search
이벤트 매개변수를 참고하세요.
Google 애널리틱스 4 이벤트 기록
userEvents.collect
메서드 호출에 이벤트의 URL 인코딩 원시 JSON 데이터를 포함하여 사용자 이벤트를 기록합니다.
prebuilt_rule
매개변수에 ga4_bq
값을 사용합니다.
가독성을 위해 userEvents.collect
호출을 사용하는 예시는 먼저 예시 이벤트의 원시 JSON 데이터가 포함된 변수로 GA4_EVENT
를 설정합니다. 그런 다음 예시에서 userEvents.collect
호출은 GA4_EVENT
변수를 사용하여 이벤트 데이터를 URL로 인코딩합니다.
나중에 URL 인코딩을 쉽게 하기 위해
GA4_EVENT
를 이벤트 데이터가 포함된 변수로 설정할 수 있습니다. 이 예시에서는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" }'
사용자 이벤트의 URL 인코딩 원시 JSON 데이터가 포함된
userEvents.collect
호출을 수행합니다.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'"
Google 태그 관리자로 사용자 이벤트 기록
태그 관리자를 사용하면 사이트에 대한 여러 서버 측 코드를 변경하지 않고도 태그 여러 개를 관리하고 테스트할 수 있습니다.
설정 중에 결정한 일부 사항은 Google 애널리틱스와 Google 애널리틱스 전자상거래 사용 여부에 따라 다릅니다. Google 애널리틱스 전자상거래는 Google 애널리틱스 4 또는 향상된 전자상거래를 사용하여 구현할 수 있습니다. Cloud Retail 태그는 둘 다 지원합니다.
둘 다 사용하지 않는 경우 Google 애널리틱스나 Google 애널리틱스 전자상거래가 필요하지 않습니다. Cloud Retail 태그를 만들 때 변수 - 전자상거래를 구성하거나 태그를 만든 후 사이트의 데이터 영역 코드를 수동으로 채우면 됩니다.
Google 애널리틱스 전자상거래는 제품 제목, ID, 가격, 거래 세부정보, 기타 구조화된 전자상거래 데이터를 Google 애널리틱스로 전달하는 Google 애널리틱스의 추가 구성입니다. 소매업용 Vertex AI Search는 자동으로 Google 애널리틱스 전자상거래 데이터 영역을 사용하므로 이미 설정했으면 구성이 더 쉬울 수 있습니다. Google 애널리틱스에 맞게 Google 애널리틱스 전자상거래를 구성하지 않았지만 이를 사용하려면 GA4 개발자 가이드에서 자세한 내용과 설정 안내를 참고하세요.
사용자 이벤트를 기록할 수 있도록 이 일회성 절차를 수행하여 태그 관리자에서 Cloud Retail 태그를 설정합니다.
방문자 ID 변수 만들기
visitorId
값은 사용자를 추적하는 데 사용됩니다.
visitorId
는 일반적으로 세션 ID이며 모든 이벤트에 필요합니다. 세션 ID를 visitorId
로 설정하는 변수를 설정합니다.
Google 애널리틱스를 사용하는 경우 Google 애널리틱스 방문자 ID를 사용할 수 있습니다. 이를 구성하려면 다음 절차를 수행하여 Cloud Retail 태그의 방문자 ID 값을 재정의합니다. 이렇게 하면 퍼스트 파티 쿠키 '_ga'가 태그 관리자 변수인 'GA visitorId'에 매핑됩니다. 모든 세션 ID 쿠키에 이 작업을 수행할 수 있습니다. Google 애널리틱스에서 수행할 필요는 없습니다.
이 절차에서는 Google 애널리틱스를 사용한다고 가정합니다. 그 밖의 경우에는 다른 쿠키 또는 변수를 사용하거나 cloud_retail
데이터 영역에서 방문자 ID를 가져오면 됩니다.
Cloud Retail 태그에 대해 visitorID
값을 변수로 설정하려면 다음 안내를 따르세요.
태그 관리자에서 변수 탭으로 이동하고 새로 만들기를 클릭하여 새 사용자 정의 변수를 만듭니다.
대화상자의 상단에서 변수의 이름을 지정합니다(예: 'GA visitorId').
변수 설정을 입력합니다.
클라이언트 ID 또는 쿠키 ID를 사용하여 방문자 ID의 소스로 설정할 수 있습니다. 이전 사용자 이벤트 및 실시간 사용자 이벤트를 수집할 때는 항상 일관된 방문자 ID 소스를 사용하세요.
클라이언트 ID
Google 애널리틱스 4에서 이 변수는 Google 애널리틱스 4 BigQuery 내보내기 스키마의
user_pseudo_id
필드에 매핑됩니다.변수 유형을 커스텀 자바스크립트로 설정합니다.
커스텀 자바스크립트 필드에 다음 스크립트를 입력합니다.
'G-XXXXXX'를 Google 애널리틱스 추적 ID로 바꿉니다. 추적 ID를 찾으려면 추적 ID는 어떻게 되었나요?를 참고하세요.
function() { var tracker = ga.getByName('G-XXXXXX'); return tracker.get('clientID'); }
저장을 클릭하여 변수를 저장합니다.
쿠키 ID
변수 유형으로 제1사 쿠키를 선택합니다.
쿠키 이름 필드에 _ga를 입력합니다.
형식 값을 클릭하고 정의되지 않은 항목 변환..을 선택하고 ""(빈 문자열)를 입력합니다.
저장을 클릭하여 변수를 저장합니다.
이렇게 하면 퍼스트 파티 쿠키 '_ga'가 태그 관리자 변수인 'GA visitorId'에 매핑됩니다.
다음으로 태그 관리자에서 Cloud Retail 태그를 만듭니다. 이 태그는 방금 만든 방문자 ID 변수를 사용합니다.
Google 태그 관리자 태그 만들기
태그 관리자에 태그를 설정하여 사용자 이벤트 정보를 소매업용 Vertex AI Search로 보냅니다.
태그 관리자에 로그인하고 사이트의 컨테이너를 선택합니다.
태그 탭으로 이동하고 새로 만들기를 클릭하여 새 태그를 추가합니다.
패널 상단에 '소매업용 Vertex AI Search'와 같은 태그 이름을 지정합니다(자리표시자는 제목 없는 변수).
태그 구성을 클릭하고 Cloud Retail 태그를 선택하여 태그 구성 패널을 엽니다.
API 키를 입력합니다.
소매업용 Vertex AI Search를 설정할 때 만든 키를 사용합니다.
API 키는 Google Cloud 콘솔의 API 및 서비스 > 사용자 인증 정보 페이지에서 제공됩니다.
소매업용 Vertex AI Search가 사용 설정된 Google Cloud 프로젝트의 프로젝트 번호를 입력합니다.
프로젝트 번호는 Google Cloud 콘솔 대시보드에서 제공됩니다.
사용자 이벤트 데이터 소스 필드에 대해 다음을 수행합니다.
데이터 영역 (권장): 구현이 다음 중 하나가 될 경우에 선택합니다.
태그 관리자를 통해 Google 애널리틱스 전자상거래를 구현합니다. 데이터 영역을 새 데이터 소스를 채우는 대신 이벤트 데이터 소스로 재사용합니다. 이 경우 Google 애널리틱스 4 스키마가 사용됩니다. 그렇지 않으면 UA 향상된 전자상거래를 사용합니다. 이 데이터 소스를 사용하면
add-to-cart
,purchase-complete
,detail-page-view
,search
이벤트만 기록할 수 있습니다.search
이벤트는 검색어와 결합된 전자상거래 노출을 사용하여 기록됩니다(검색어 변수 만들기 참조).Google 애널리틱스 전자상거래를 사용 중이며 데이터 영역 코드를 수동으로 채울 수 있습니다. 태그 관리자 개발자 가이드를 참조하세요.
변수 - Cloud Retail: 태그 관리자 변수를 소매업용 Vertex AI Search의 필수 필드로 채우려면 선택합니다. Google 애널리틱스 전자상거래를 사용하지 않거나 Google 애널리틱스 전자상거래에 소매업용 Vertex AI Search에 필요한 데이터가 없으면 이 옵션을 선택할 수 있습니다. 기존 데이터 영역 - Cloud Retail 옵션에서 이 소스로 전환하는 경우
cloud_retail
키로 데이터 영역 변수를 만들고 이 변수 - Cloud Retail 옵션에 연결합니다.변수 - 전자상거래: 데이터 영역에서 Google 애널리틱스 전자상거래를 사용하지 않고 데이터 영역 코드를 직접 입력할 수 없는 경우에 선택합니다.
표시된 사용자 변수에서 전자상거래 데이터 읽기 필드에서 변수를 선택합니다. 그러면 소매업용 Vertex AI Search가 생성된 커스텀 변수에서 Google 애널리틱스 전자상거래 사용자 이벤트 데이터를 읽을 수 있습니다.
변수가 GA4 개발자 가이드에 설명된 형식과 일치해야 합니다. 변수를 올바른 형식으로 구성하려면 태그 관리자 커뮤니티 템플릿 갤러리의 커스텀 변수 템플릿인 향상된 전자상거래 객체 빌더를 사용하면 됩니다. 커뮤니티 템플릿은 Google에서 유지관리하지 않습니다. 이 템플릿을 사용하려면 향상된 전자상거래 객체 빌더 갤러리 페이지에서 문서 및 기타 리소스를 참조하세요.
+ UserEvent 메시지에서 값 덮어쓰기 버튼을 클릭합니다.
필드 선택기에서 필드로
visitorId
를 선택하고, 필드 값으로 방문자 ID 변수 만들기에서 생성한 새 방문자 ID 변수를 선택합니다.저장을 클릭합니다.
Cloud Retail 태그가 생성됩니다.
기존 데이터 소스 옵션
이전에는 데이터 영역 - 전자상거래 및 데이터 영역 - Cloud Retail을 데이터 소스 옵션으로 사용할 수 있었습니다. 새 태그에서는 이러한 기존 옵션을 사용할 수 없습니다. 기존 태그를 새 데이터 소스로 전환하는 경우 태그 관리자를 사용하여 미리 보고 배포 전에 확인합니다. 전환 시 다음 사항이 적용됩니다.
데이터 영역 - 전자상거래를 사용한 경우 데이터 영역으로 전환할 수 있습니다. 이 경우 Google 애널리틱스 4 스키마가 사용됩니다. 그렇지 않으면 UA 향상된 전자상거래를 사용합니다.
데이터 영역 - Cloud Retail을 사용한 경우 변수 - Cloud Retail 옵션으로 전환합니다.
cloud_retail
키로 데이터 영역 변수를 만들고 변수 - Cloud Retail 옵션과 연결합니다.
다음:
- 검색을 사용하는 경우 검색어 변수를 만들고 새 태그에 연결합니다.
- 태그에 대한 이벤트 트리거를 만듭니다.
검색어 변수 만들기
검색을 사용하는 경우 검색 쿼리를 위해 변수를 태그 관리자에 만들고 이를 Cloud Retail 태그에 연결할 수 있습니다. 이렇게 하면 소매업용 Vertex AI Search가 애널리틱스에서 검색어를 가져올 수 있습니다.
만드는 변수 유형은 사용자 이벤트 데이터 소스에 따라 다릅니다.
- 변수 - 전자상거래 또는 Google 애널리틱스 전자상거래 스키마를 사용하는 데이터 영역: 태그 관리자에서 URL 또는 DOM 요소 변수를 만들고 Cloud Retail 태그에 연결합니다. 또한 태그에서 Google 애널리틱스 전자상거래 노출을 사용하여 검색 이벤트를 구성할 수 있는 옵션을 사용 설정합니다.
- 변수 - Cloud Retail 또는 수동으로 채워진 데이터 영역: 태그 관리자에서 URL 또는 DOM 요소 변수를 만들고 Cloud Retail 태그에 연결합니다. 사용자 이벤트 유형이
search
인지 확인하려면 다음 중 하나를 수행해야 합니다.- 검색 이벤트 유형의 상수 유형 변수를 만들고 태그에 연결합니다.
- 데이터 영역 또는 Cloud Retail 변수에서 검색 이벤트 유형을 설정합니다.
검색어에 태그 관리자 변수 만들기 및 연결
검색을 사용하는 경우 사이트에 입력한 검색어로 채워지는 URL, DOM 요소, 커스텀 JavaScript 변수를 만들 수 있습니다.
이 절차의 대안으로 데이터 영역을 구성하여 검색어 정보를 제공할 수 있습니다. 하지만 데이터 영역에 액세스할 수 없거나 데이터 영역을 구성하지 않으려면 태그 관리자 변수를 사용해야 할 수 있습니다.
URL 유형 변수, DOM 요소 유형 변수, 커스텀 자바스크립트(페이지) 변수를 만들 수 있습니다. 어떤 것을 만들고 구성하는 방법은 사이트 구현에 따라 다릅니다.
- URL 변수는 사이트의 검색결과 URL에서 검색어를 가져옵니다. 사이트의 검색결과 URL에 쿼리 문자열이 포함된 경우 이 변수를 사용합니다.
- DOM 요소 변수는 사이트의 문서 객체 모델(DOM)에서 검색어 정보를 가져옵니다. 이 변수를 사용하기 위해 DOM을 수정할 필요는 없습니다. 하지만 이 변수를 올바르게 구성하려면 DOM을 읽고 이해할 수 있어야 합니다.
- 커스텀 자바스크립트 변수는 자바스크립트 함수로 형식 지정된 데이터를 반환합니다. 이 방법은 Cloud Retail 또는 전자상거래 스키마에 형식 지정하려는 기존 데이터가 있는 경우에 유용합니다.
먼저 URL, DOM 요소 유형 또는 커스텀 자바스크립트 태그 관리자 변수를 만듭니다.
태그 관리자에서 변수 탭으로 이동하고 새로 만들기를 클릭하여 새 사용자 정의 변수를 만듭니다.
대화상자의 상단에서 변수의 이름을 지정합니다(예: '검색_변수').
변수 설정을 입력합니다.
URL 유형
변수 유형을 URL로 설정합니다.
구성요소 유형을 쿼리로 설정합니다.
쿼리 키를 지정하는 경우 URL에서 검색어 앞에 있는 키로 설정합니다.
예를 들어 URL이
http://example.com/?q=shoes
이면 쿼리 키는q
입니다. 이 예시에서는 변수 값이shoes
로 설정됩니다.
DOM 요소 유형
변수 유형을 DOM 요소로 설정합니다.
선택 방법을 설정하고 검색어의 요소 ID 또는 요소 선택기를 입력합니다.
이 설정은 사이트에서 검색어를 식별하는 데 요소 ID를 사용하는지 또는 CSS 선택기를 사용하는지에 따라 다릅니다.
속성을 지정하는 경우 검색어가 포함된 속성으로 설정합니다.
예를 들어 DOM의 검색어가
<id="search" value="shoes">
이면 속성은value
입니다. 이 예시에서는 변수 값이shoes
로 설정됩니다.
커스텀 자바스크립트 유형
변수 유형을 커스텀 자바스크립트로 설정합니다.
다음 코드의 변수를 바꾸고 커스텀 자바스크립트 창에 붙여넣습니다.
커스텀 JavaScript 창에서 Retail 스키마에 검색 이벤트를 반환하는 JavaScript 코드를 추가합니다.
다음 샘플 코드는 기존
Ecommerce Items
변수의 데이터를 소매업용 Vertex AI Search 스키마에서 사용하는 productDetails 배열로 변환하고 전체 이벤트를 반환합니다. 이 코드를 사용하려면Ecommerce Items
,Search Query
,Search Filter
를 태그 관리자 구현의 변수로 바꿉니다.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; }
저장을 클릭하여 변수를 저장합니다.
다음으로 Cloud Retail 태그에 변수를 연결합니다.
태그 관리자, 태그 페이지에서 Cloud Retail 태그를 클릭하여 수정합니다.
태그의 사용자 이벤트 데이터 소스가 변수 - 전자상거래이거나 Google 애널리틱스 전자상거래 스키마로 데이터 영역을 사용하는 경우 향상된 전자상거래 노출을 사용하여 검색 이벤트 구성 체크박스를 선택합니다.
이를 통해 소매업용 Vertex AI Search는 이 태그에서 가져온 검색 데이터를 기반으로 사용자 이벤트 유형이
search
인지 확인할 수 있습니다.사용자 이벤트 데이터 섹션에서 + UserEvent 메시지에서 값 덮어쓰기 버튼을 클릭합니다.
필드 선택기에서
searchQuery
를 선택하고 검색어 변수를 필드 값으로 설정합니다.태그를 저장합니다.
다음:
- Cloud Retail 변수를 사용하거나 수동으로 채워진 데이터 영역을 Cloud Retail 태그의 사용자 이벤트 소스로 사용하는 경우 상수 변수 만들기 및 연결을 참조하세요.
- 태그에 대한 이벤트 트리거를 만듭니다.
상수 변수 만들기 및 연결
변수 - Cloud Retail을 선택하거나 수동으로 채워진 데이터 영역을 Cloud Retail 태그의 사용자 이벤트 소스로 선택한 경우 이 절차를 사용할 수 있습니다.
검색 이벤트의 상수 유형 변수를 만들고 Cloud Retail 태그에서 사용자 이벤트 재정의로 설정하면 소매업용 Vertex AI Search가 사용자 이벤트 유형이 search
인지 확인할 수 있습니다.
이 절차의 대안으로 태그의 이벤트 소스로 사용하는 데이터 영역 또는 Cloud Retail 사용자 변수를 통해 search
사용자 이벤트 유형을 지정할 수 있습니다. 그렇지 않으면 다음 단계를 따라 이벤트 유형을 설정합니다.
먼저 상수 유형 변수를 만듭니다.
태그 관리자에서 변수 탭으로 이동하고 새로 만들기를 클릭하여 새 사용자 정의 변수를 만듭니다.
대화상자의 상단에서 변수의 이름을 지정합니다(예: '검색_상수').
변수 유형을 상수로 설정합니다.
값 필드에
search
입력저장을 클릭하여 변수를 저장합니다.
다음으로 Cloud Retail 태그에 변수를 연결합니다.
태그 관리자, 태그 페이지에서 Cloud Retail 태그를 클릭하여 수정합니다.
사용자 이벤트 데이터 섹션에서 + UserEvent 메시지에서 값 덮어쓰기 버튼을 클릭합니다.
필드 선택기에서
eventType
를 선택하고 검색어 변수를 필드 값으로 설정합니다.태그를 저장합니다.
그런 후 태그에 대해 이벤트 트리거 만들기를 수행합니다.
태그 관리자 태그용 이벤트 트리거 만들기
소매업용 Vertex AI Search 모델이 사용할 모든 사용자 이벤트 유형에 대한 트리거를 만듭니다.
태그 관리자 태그에는 사이트에서 태그를 '실행'해야 하는 시기를 제어하는 트리거가 있어야 합니다. 트리거는 이벤트가 발생하는 때(예: 사용자가 홈페이지를 보거나 장바구니에 항목을 추가하는 경우)를 수신 대기하고 사용자 이벤트 정보를 소매업용 Vertex AI Search로 전송하도록 태그를 표시합니다.
태그 관리자는 일부 표준 트리거를 제공합니다. 예를 들어 Window Loaded는 detail-page-view
이벤트의 트리거입니다. 각 유형에 대한 상세 설명은 태그 관리자 문서의 트리거 유형을 참조하세요.
일반적으로 사용자가 소매업용 Vertex AI Search에 필요한 이벤트가 포함된 페이지(예: 홈페이지, 제품 세부정보 페이지, 장바구니 페이지 또는 결제 완료 페이지)를 볼 때 트리거되도록 태그를 설정합니다. 이러한 경우 쿠키가 사용 가능해지고 모든 데이터 영역 변수가 채워지도록 페이지가 로드된 후에 태그가 실행되어야 합니다. 이를 수행하려면 Window Loaded 또는DOM Ready 발생 시 트리거가 실행되도록 설정합니다.
페이지가 로드될 때가 아닌 작업이 수행될 때 태그를 실행해야 할 수도 있습니다. 예를 들어 사용자가 장바구니에 항목을 추가해도 강제로 페이지가 새로 고쳐지지 않는 경우가 있습니다. 이러한 경우 사이트에서의 클릭 동작이 동시에 업데이트를 데이터 영역에 푸시하고 트리거를 이 작업과 연결하도록 구성할 수 있습니다.
예를 들어 add-to-cart
이벤트의 트리거를 만든 경우 트리거 유형을 클릭 - 링크만으로 선택하고 ID(이 예시에서는 addtocart
)를 클릭하면 실행하도록 설정할 수 있습니다. 그런 다음 사이트에서 addtocart
링크를 구성하여 클릭할 때 데이터 영역도 새 값으로 업데이트합니다.
<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>
일부 사용자 이벤트의 경우 커스텀 트리거를 만들어야 합니다. 일반적으로 태그 관리자에서 사용자 이벤트 이름을 사용하여 커스텀 트리거를 만듭니다. 프런트엔드 코드를 수정할 수 없는 경우 자바스크립트 매크로를 사용하여 커스텀 트리거를 만들 수 있습니다. 커스텀 트리거에 대한 상세 설명은 커스텀 이벤트 트리거를 참조하세요.
태그 관리자에서 트리거를 만들려면 다음 절차를 수행합니다.
- 기존 트리거가 구성되지 않은 경우: 태그 관리자 태그의 새 트리거를 만듭니다.
- Google 애널리틱스 전자상거래 트리거를 이미 설정한 경우: 새 트리거를 만드는 대신 Google 애널리틱스 전자상거래를 위해 구성한 트리거를 재사용할 수 있습니다. Google 애널리틱스 전자상거래 트리거 재사용을 참조하세요.
태그 관리자 태그용 새 트리거 만들기
Google 애널리틱스 전자상거래를 사용하지 않는 경우 소매업용 Vertex AI Search 모델이 필요한 사용자 이벤트에 대한 새 이벤트 트리거를 만듭니다. 그런 후 새 트리거를 태그 관리자에서 만든 Cloud Retail 태그와 연결합니다.
다음 단계를 시작하기 전에 태그 관리자에서 Cloud Retail 태그를 만들었는지 확인합니다. 태그 관리자 태그 만들기를 참조하세요.
먼저 트리거를 만듭니다. 소매업용 Vertex AI Search 모델에 필요한 모든 사용자 이벤트에 이 절차를 반복합니다.
그런 후 새 트리거를 Cloud Retail 태그와 연결합니다. 이것은 일회성 절차입니다.
태그 관리자, 태그 페이지에서 Cloud Retail 태그를 클릭하여 수정합니다.
트리거를 클릭하고 새 트리거를 선택한 후 추가를 클릭합니다.
태그를 저장합니다.
다음으로 태그를 미리 보고, 이벤트 기록 오류와 기타 문제의 모니터링을 설정하고 데이터가 계속 수신되는지 확인합니다.
cloud_retail
데이터 영역을 사용자 이벤트 소스로 사용하는 경우 데이터 영역도 설정해야 합니다.
Google 애널리틱스 전자상거래 트리거 재사용
태그 관리자를 통해 Google 애널리틱스 전자상거래를 구현했다면 Google 애널리틱스 전자상거래의 이벤트 트리거를 소매업용 Vertex AI Search에 재사용하세요.
이 데이터 소스를 사용하면 add-to-cart
, purchase-complete
, detail-page-view
, search
이벤트만 기록할 수 있습니다. search
이벤트는 검색어와 결합된 전자상거래 노출을 사용하여 기록됩니다(검색어 변수 만들기 참조).
다음 표에서는 Google 애널리틱스 전자상거래 및 향상된 전자상거래 이벤트가 소매업용 Vertex AI Search 이벤트에 어떻게 매핑되는지 보여줍니다.
Google 애널리틱스 4 | 향상된 전자상거래 | 소매업용 Vertex AI Search |
---|---|---|
add_to_cart |
add |
add-to-cart |
purchase |
purchase |
purchase-complete |
view_item |
detail |
detail-page-view |
view_item_list 또는 view_search_results |
impressions |
search (searchQuery 필드와 결합된 경우) |
이 단계를 시작하기 전에 다음을 먼저 수행하세요.
- 태그 관리자에서 Google 애널리틱스 - GA4 이벤트 태그 유형의 태그를 설정하고 여기에 향상된 전자상거래 또는 GA4를 사용 설정했습니다. 자세한 내용은 태그 관리자 문서 및 GA4 개발자 가이드를 참고하세요.
- 태그 관리자에서 소매업용 Vertex AI Search에 기록하려는 사용자 이벤트가 발생할 때 트리거할 향상된 전자상거래 또는 GA4 태그를 구성했습니다.
- 태그 관리자에서 사용자 이벤트 데이터 소스로 '데이터 영역' 또는 '변수 - 전자상거래'를 사용하여 Cloud Retail 태그를 만들었습니다(태그 관리자 태그 만들기 참조).
Google 애널리틱스 전자상거래 트리거를 재사용하려면 다음 안내를 따르세요.
태그 관리자의 태그 페이지에서 Google 애널리틱스 전자상거래 태그 (유형 Google 애널리틱스 - GA4 이벤트)를 클릭하여 수정합니다.
고급 설정 > 태그 시퀀싱에서 <향상된 전자상거래 또는 GA4 태그 이름> 실행 후 태그 실행을 선택합니다.
Cloud Retail 태그를 삭제 태그로 선택합니다.
<향상된 전자상거래 또는 GA4 태그 이름>이 실패하거나 일시 중지된 경우 <Cloud Retail 태그 이름> 실행 안 함을 선택합니다.
태그를 저장합니다.
다음으로 태그를 미리 보고, 이벤트 기록 오류와 기타 문제의 모니터링을 설정하고 데이터가 계속 수신되는지 확인합니다.
cloud_retail
데이터 영역을 사용자 이벤트 소스로 사용하는 경우 데이터 영역도 설정해야 합니다.
태그 관리자에서 cloud_retail
데이터 영역 사용
cloud_retail
데이터 영역을 사용자 이벤트 소스로 사용하기 위해 태그 관리자에서 Cloud Retail 태그를 만든 경우 태그 관리자 개발자 가이드에 설명된 대로 소스 HTML에서 dataLayer
변수를 설정합니다.
데이터 영역 정보
대부분의 태그 관리자 태그에는 사용자 또는 페이지(예: 사용자 ID 또는 제품 ID)에 따라 변경되는 데이터가 필요합니다. Cloud Retail 태그의 경우 태그 관리자가 사용할 수 있도록 데이터를 데이터 영역을 통해 구조화된 방식으로 노출해야 합니다.
데이터 영역은 일반적으로 서버 측 코드 또는 HTML이나 템플릿을 사용하여 프런트엔드에서 페이지에 추가되는 자바스크립트 객체입니다. 페이지가 데이터 영역으로 구성되면 다음과 같은 코드가 포함됩니다.
dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'home-page-view', 'visitorId': 'visitor_a', 'userInfo': { 'userId': '789' }, } });
이 코드는 dataLayer
객체를 만들고 cloud_retail
구조를 배열 요소로 할당합니다.
cloud_retail
데이터 영역의 필수 필드
사용자 이벤트 정보에는 cloud_retail
데이터 영역에 전달해야 하는 이벤트 유형의 모든 필수 필드와 예시가 나와 있습니다.
서버 측 코드 또는 템플릿에서 이벤트를 전송하려는 각 페이지에 올바른 스크립트 태그가 있어야 합니다. 각 페이지에서 dataLayer
객체가 올바르게 채워지면 Cloud Retail 태그를 테스트할 수 있어야 합니다.
visitorId
와 같은 일부 필드는 UserEvent
메시지에 필요하지만 데이터 영역을 채울 때 사용할 수 없는 경우도 있습니다. 예를 들어 visitorId
가 사용자의 쿠키에서 파생되거나 experimentIds
가 A/B 실험 프레임워크에서 파생될 수 있습니다. 이 경우 변수를 사용하여 태그 관리자 태그의 필드를 덮어씁니다.
다음 필드를 덮어쓸 수 있습니다.
visitorId
userInfo.userId
attributionToken
experimentIds
태그 관리자에서 UserEvent
필드를 덮어쓰는 방법은 태그 관리자에서 visitorID
필드 설정을 참조하세요. 여기서는 사용자 정의 변수로 visitorId
필드 값을 덮어쓰는 방법을 안내합니다.
다음 예에서는 태그 관리자를 사용하여 detail-page-view
UserEvent의 페이지에 포함되어야 하는 데이터 영역을 보여줍니다.
<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>
태그 관리자 태그 미리보기
태그 관리자의 미리보기 모드를 사용하면 새 태그를 실제 사이트에 게시하기 전에 테스트할 수 있습니다.
미리보기 모드에 대한 상세 설명은 미리보기 모드의 태그 관리자 문서를 참조하세요.
다음 절차를 수행하여 태그가 올바르게 실행되고 있는지 확인합니다.
태그 관리자 개요 페이지에서 미리보기를 클릭합니다.
새 브라우저 탭에서 태그 관리자 미리보기 모드가 열립니다.
사이트 정보를 입력하고 시작을 클릭하여 Tag Assistant를 시작합니다.
현재 브라우저 탭에서 Tag Assistant가 시작하고 새 탭에서 사이트가 열립니다.
사이트에서 Cloud Retail 태그를 트리거해야 하는 페이지를 방문합니다.
Tag Assistant가 실행된 태그 수 섹션의 태그 탭에 Cloud Retail 태그를 나열하는지 확인합니다.
Tag Assistant에서 데이터 영역 탭으로 이동하고
cloud_retail
또는 전자상거래 데이터 영역에서 올바른 값이 표시되는지 확인합니다.
태그 오류 확인
태그를 미리 볼 때 일부 필드가 잘못되었거나 누락된 경우 태그가 실행되지 않으면 일반적으로 태그에서 오류를 반환합니다.
Search for Retail 콘솔의 Monitoring 페이지에서 오류가 있는지 확인할 수 있습니다. 이 페이지에는 일반적으로 요청 결과에만 표시되는 문법 오류를 제외한 대부분의 오류가 로깅됩니다.
다음 단계를 수행하면 Chrome DevTools를 사용하여 문법 오류를 포함하여 생성된 오류를 확인할 수 있습니다.
Chrome 브라우저에 있는 사이트의 태그 관리자에서 미리보기 모드를 사용 설정하고 Cloud Retail 태그를 트리거해야 하는 페이지를 방문합니다.
미리보기 모드가 열린 상태에서 DevTools를 열고 네트워크 탭을 클릭합니다.
페이지를 새로고침하세요.
DevTools에서
userEvent
를 검색합니다.네트워크 탭에
userEvent:collect
이벤트와 관련 상태 코드가 표시됩니다.200
응답은 태그가 정상 상태임을 나타냅니다.400
오류 및 이벤트를 빨간색으로 강조표시하는 다른 응답은 디버깅이 필요함을 나타냅니다.
이벤트 이름을 더블클릭하여 요청을 실행하고 추가 오류 정보가 포함된 전체 응답을 표시합니다.
예를 들어
visitorId
가 올바르게 설정되지 않았음을 나타내는 "visitorId' is required, and cannot be empty"라는 메시지가 포함된400
오류가 표시될 수 있습니다.userEvent
가 실행되지 않으면 DevTools Console 탭에서 데이터 영역에 구문 오류가 있는지 확인합니다.
가져오기 상태 모니터링
고품질의 결과를 받으려면 사용자 이벤트를 성공적으로 기록하는 것이 중요합니다. 이벤트 기록 오류 비율을 모니터링하고 필요에 따라 조치를 수행해야 합니다. 자세한 내용은 데이터 업로드 문제 알림 설정을 참조하세요.
기록된 이벤트 보기
Search for Retail 콘솔 데이터 페이지의 이벤트 탭에서 이벤트 통합 측정항목을 확인합니다. 이 페이지에는 지난해에 쓰거나 가져온 모든 이벤트가 표시됩니다. 데이터 수집이 완료된 후 측정항목이 표시되는 데 최대 24시간이 걸릴 수 있습니다.
다음 단계
- 사용자 이벤트에 대해 자세히 알아보기
- 카탈로그 가져오기가 완료되기 전에 기록된 이벤트 재조인
- 사용자 이벤트 가져오기 및 관리 자세히 알아보기
- 예측 시작하기
- 데이터 업로드 프로세스 모니터링 및 문제 해결
- 태그 관리자에 대해 자세히 알아보기