REST Resource: projects.locations.dataStores.userEvents

리소스: UserEvent

UserEvent는 최종 사용자가 웹사이트와 상호작용하는 방식에 관해 Discovery Engine API가 알아야 하는 모든 메타데이터 정보를 캡처합니다.

JSON 표현 
{
  "eventType": string,
  "conversionType": string,
  "userPseudoId": string,
  "engine": string,
  "dataStore": string,
  "eventTime": string,
  "userInfo": {
    object (UserInfo)
  },
  "directUserRequest": boolean,
  "sessionId": string,
  "pageInfo": {
    object (PageInfo)
  },
  "attributionToken": string,
  "filter": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panel": {
    object (PanelInfo)
  },
  "searchInfo": {
    object (SearchInfo)
  },
  "completionInfo": {
    object (CompletionInfo)
  },
  "transactionInfo": {
    object (TransactionInfo)
  },
  "tagIds": [
    string
  ],
  "promotionIds": [
    string
  ],
  "attributes": {
    string: {
      "text": [
        string
      ],
      "numbers": [
        number
      ]
    },
    ...
  },
  "mediaInfo": {
    object (MediaInfo)
  },
  "panels": [
    {
      object (PanelInfo)
    }
  ]
}
필드
eventType

string

필수 항목입니다. 사용자 이벤트 유형입니다. 허용되는 값은 다음과 같습니다.

일반 값:

  • search: 문서를 검색합니다.
  • view-item: 문서의 세부 페이지 뷰입니다.
  • view-item-list: 패널 또는 정렬된 문서 목록의 뷰입니다.
  • view-home-page: 홈페이지 보기
  • view-category-page: 카테고리 페이지 보기(예: 홈 > 남성 > 청바지)

소매 관련 값:

  • add-to-cart: 장바구니에 상품 추가(예: 소매 온라인 쇼핑)
  • purchase: 항목 구매

미디어 관련 값:

  • media-play: 동영상 시청, 노래 재생 등을 시작하거나 다시 시작합니다.
  • media-complete: 동영상, 노래 등을 끝까지 시청하거나 중간에 중단했습니다.

맞춤 전환 가치:

  • conversion: 고객 정의 전환 이벤트입니다.
conversionType

string

(선택사항) 전환 유형입니다.

UserEvent.event_type이 conversion인 경우에 필요합니다. '-'로 구분된 소문자 또는 숫자로 된 고객 정의 전환 이름입니다(예: 'watch', 'good-visit').

UserEvent.event_type이 conversion이 아닌 경우 필드를 설정하지 마세요. 이렇게 하면 맞춤 전환 이벤트가 search, view-item 등 사전 정의된 이벤트와 혼합됩니다.
userPseudoId

string

필수 항목입니다. 방문자 추적을 위한 고유 식별자입니다.

예를 들어 단일 기기에서 방문자를 고유하게 식별할 수 있는 HTTP 쿠키를 사용하여 이를 구현할 수 있습니다. 이 고유 식별자는 방문자가 웹사이트에 로그인/로그아웃해도 변경되지 않아야 합니다.

여러 사용자에 대해 필드를 동일한 고정 ID로 설정하지 마세요. 이렇게 하면 해당 사용자의 이벤트 기록이 혼합되어 모델 품질이 저하됩니다.

필드는 길이 제한이 128자(영문 기준)인 UTF-8로 인코딩된 문자열이어야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

필드에 PII 또는 사용자 데이터가 포함되어서는 안 됩니다. 이 필드에는 Google 애널리틱스 클라이언트 ID를 사용하는 것이 좋습니다.
engine

string

Engine 리소스 이름(projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId} 형식)

(선택사항) Engine에서 생성된 사용자 이벤트에만 필요합니다. 예를 들어 혼합 검색의 사용자 이벤트가 있습니다.
dataStore

string

DataStore 리소스 전체 이름입니다(projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId} 형식).

(선택사항) UserEvent.engine 또는 UserEvent.documents로 데이터 스토어를 확인할 수 없는 사용자 이벤트에만 필요합니다. 쓰기/가져오기/수집 사용자 이벤트 요청의 상위 항목에 데이터 스토어가 설정된 경우 이 필드를 생략할 수 있습니다.
eventTime

string (Timestamp format)

UserEventService.ImportUserEvents 메서드에만 필요합니다. 사용자 이벤트가 발생한 시점의 타임스탬프입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
userInfo

object (UserInfo)

최종 사용자에 관한 정보입니다.
directUserRequest

boolean

최종 사용자로부터 직접 요청이 이루어진 경우 true로 설정해야 합니다. 이 경우 UserEvent.user_info.user_agent는 HTTP 요청에서 채울 수 있습니다.

이 플래그는 모바일 앱과 같은 최종 사용자로부터 직접 API 요청이 이루어진 경우에만 설정해야 합니다(게이트웨이 또는 서버가 사용자 이벤트를 처리하고 푸시하는 경우에는 설정하지 않음).

UserEventService.CollectUserEvent에서 JavaScript 태그를 사용하는 경우 이 값을 설정하면 안 됩니다.
sessionId

string

방문자 세션을 추적하는 고유 식별자로 길이 제한은 128바이트입니다. 세션은 일정 기간 동안의 최종 사용자 행동을 집계한 것입니다.

sessionId를 채우기 위한 일반 가이드라인은 다음과 같습니다.

  1. 사용자가 30분 동안 활동이 없으면 새 sessionId가 할당되어야 합니다.
  2. sessionId는 사용자 간에 고유해야 합니다. uuid를 사용하거나 UserEvent.user_pseudo_id를 접두사로 추가하는 것이 좋습니다.
pageInfo

object (PageInfo)

카테고리, view-category-page와 같은 특정 이벤트 유형의 기타 중요 정보와 같은 페이지 메타데이터
attributionToken

string

이벤트를 트리거하는 사용자 작업에 API 응답을 귀속시키는 토큰입니다.

RecommendationService.Recommend의 결과인 사용자 이벤트에 적극 권장됩니다. 이 필드를 사용하면 추천 모델 성능을 정확하게 기여 분석할 수 있습니다.

값은 다음 중 하나여야 합니다.

이 토큰을 사용하면 페이지 조회 또는 전환 완료를 이벤트 및 클릭/구매된 제품이 포함된 특정 예측 응답에 정확하게 기여도를 부여할 수 있습니다. 사용자가 추천 결과에서 제품 K를 클릭하면 RecommendResponse.attribution_token를 제품 K 페이지의 URL 매개변수로 전달합니다. 제품 K 페이지에서 이벤트를 기록할 때 RecommendResponse.attribution_token을 이 필드에 로깅합니다.
filter

string

필터 구문은 필터링되는 문서의 하나 이상의 필드에서 조건자를 구성하기 위한 표현식 언어로 구성됩니다.

한 예로 search 이벤트의 경우 연결된 SearchRequest에 https://google.aip.dev/160#filtering을 준수하는 SearchRequest.filter의 필터 표현식이 포함될 수 있습니다.

마찬가지로 RecommendRequest에서 생성된 view-item-list 이벤트의 경우 https://google.aip.dev/160#filtering을 준수하는 RecommendRequest.filter에서 이 필드가 직접 채워질 수 있습니다.

값은 1,000자 길이 제한이 있는 UTF-8 인코딩 문자열이어야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
documents[]

object (DocumentInfo)

이 사용자 이벤트와 연결된 Document 목록입니다.

이 필드는 다음 이벤트 유형을 제외하고 선택사항입니다.

  • view-item
  • add-to-cart
  • purchase
  • media-play
  • media-complete

search 이벤트에서 이 필드는 현재 페이지에서 최종 사용자에게 반환된 문서를 나타냅니다 (최종 사용자가 아직 전체 페이지를 탐색하지 않았을 수 있음). 동일한 검색어에 대해서도 페이지로 나누기/필터링/정렬 후 새 페이지가 최종 사용자에게 반환되면 UserEvent.documents가 다른 새 search 이벤트가 필요합니다.
panel

object (PanelInfo)

이 사용자 이벤트와 연결된 패널 메타데이터입니다.
searchInfo

object (SearchInfo)

이벤트와 관련된 SearchService.Search 세부정보입니다.

이 필드는 search 이벤트에 설정해야 합니다.
completionInfo

object (CompletionInfo)

이벤트와 관련된 CompletionService.CompleteQuery 세부정보입니다.

이 필드는 자동 완성 기능이 사용 설정되어 있고 사용자가 검색 추천을 클릭할 때 search 이벤트에 설정해야 합니다.
transactionInfo

object (TransactionInfo)

이 사용자 이벤트와 연결된 거래 메타데이터입니다 (있는 경우).
tagIds[]

string

이 사용자 이벤트가 속한 독립 실험 그룹의 식별자 목록입니다. 이는 다양한 실험 설정과 관련된 사용자 이벤트를 구분하는 데 사용됩니다.
promotionIds[]

string

프로모션과 연결된 이벤트인 경우 프로모션 ID입니다. 현재 이 필드는 ID가 최대 1개로 제한됩니다.
attributes

map (key: string, value: object)

추천 모델에 포함할 추가 사용자 이벤트 기능입니다. 이러한 속성에는 JSON이나 기타 인코딩과 같이 추가로 파싱하거나 처리해야 하는 데이터가 포함되어서는 안 됩니다(NOT).

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

이 필드는 아래 기준을 모두 통과해야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

  • 키는 UTF-8로 인코딩된 문자열이어야 하며 길이 제한은 5,000자(영문 기준)입니다.
  • 텍스트 속성의 경우 최대 400개의 값이 허용됩니다. 빈 값은 허용되지 않습니다. 각 값은 UTF-8로 인코딩된 문자열이어야 하며 길이 제한은 256자(영문 기준)입니다.
  • 숫자 속성의 경우 최대 400개의 값이 허용됩니다.

제품 추천의 경우 추가 사용자 정보의 예시는 traffic_channel(사용자가 사이트에 도달하는 방법)입니다. 사용자는 사이트를 직접 방문하거나 Google 검색 등을 통해 사이트에 도달할 수 있습니다.
attributes.text[]

string

이 맞춤 속성의 텍스트 값입니다. 예를 들어 키가 'color'인 경우 ["yellow", "green"]입니다.

빈 문자열은 허용되지 않습니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

CustomAttribute.text 또는 CustomAttribute.numbers 중 정확히 하나만 설정해야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
attributes.numbers[]

number

이 맞춤 속성의 숫자 값입니다. 예를 들어 키가 'lengths_cm'인 경우 [2.3, 15.4]입니다.

CustomAttribute.text 또는 CustomAttribute.numbers 중 정확히 하나만 설정해야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
mediaInfo

object (MediaInfo)

미디어 관련 정보입니다.
panels[]

object (PanelInfo)

(선택사항) 이 이벤트와 연결된 패널 목록입니다. 페이지 수준 노출 데이터에 사용됩니다.

UserInfo

최종 사용자 정보입니다.

JSON 표현 
{
  "userId": string,
  "userAgent": string,
  "timeZone": string
}
필드
userId

string

로그인한 사용자에게 적극 권장됩니다. 로그인한 사용자의 고유 식별자입니다(예: 사용자 이름). 익명 사용자에게는 설정하지 마세요.

이 ID에는 항상 해시된 값을 사용하세요.

여러 사용자에 대해 필드를 동일한 고정 ID로 설정하지 마세요. 이렇게 하면 해당 사용자의 이벤트 기록이 혼합되어 모델 품질이 저하됩니다.

필드는 길이 제한이 128자(영문 기준)인 UTF-8로 인코딩된 문자열이어야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
userAgent

string

HTTP 헤더에 포함된 사용자 에이전트입니다.

필드는 UTF-8로 인코딩된 문자열이어야 하며 길이 제한은 1,000자(영문 기준)입니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

UserEventService.CollectUserEvent에서 GTM 또는 JavaScript 태그를 사용하여 클라이언트 측 이벤트 보고를 사용하는 경우 또는 UserEvent.direct_user_request가 설정된 경우에는 이 값을 설정하면 안 됩니다.
timeZone

string

(선택사항) IANA 시간대(예: Europe/Budapest)

PageInfo

자세한 페이지 정보입니다.

JSON 표현 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
필드
pageviewId

string

웹페이지 조회의 고유 ID입니다.

동일한 페이지 조회에서 트리거된 모든 사용자 이벤트에 대해 동일하게 유지해야 합니다. 예를 들어 사용자가 페이지를 탐색할 때 항목 세부정보 페이지 조회가 여러 이벤트를 트리거할 수 있습니다. 이러한 이벤트를 올바르게 그룹화할 수 있도록 pageviewId 속성은 모든 이벤트에 대해 동일하게 유지되어야 합니다.

JavaScript 픽셀 및 Google 태그 관리자를 사용하여 클라이언트 측 이벤트 보고를 사용하는 경우 이 값이 자동으로 채워집니다.
pageCategory

string

카테고리 페이지와 연결된 가장 구체적인 카테고리입니다.

카테고리의 전체 경로를 나타내려면 '>' 기호를 사용하여 다양한 계층 구조를 구분합니다. '>'가 카테고리 이름에 포함된 경우 다른 문자로 바꿉니다.

카테고리 페이지에는 할인이나 프로모션과 같은 특별 페이지가 포함됩니다. 예를 들어 특별 할인 페이지의 카테고리 계층 구조는 다음과 같습니다. "pageCategory" : "Sales > 2017 Black Friday Deals"

view-category-page 이벤트에 필요합니다. 다른 이벤트 유형에는 이 필드를 설정하면 안 됩니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
uri

string

사용자의 현재 페이지의 전체 URL (window.location.href)입니다.

JavaScript 픽셀 및 Google 태그 관리자를 사용하여 클라이언트 측 이벤트 보고를 사용하는 경우 이 값이 자동으로 채워집니다. 최대 길이는 5,000자입니다.
referrerUri

string

현재 페이지의 리퍼러 URL입니다.

JavaScript 픽셀 및 Google 태그 관리자를 사용하여 클라이언트 측 이벤트 보고를 사용하는 경우 이 값이 자동으로 채워집니다. 하지만 일부 브라우저 개인 정보 보호 제한으로 인해 이 필드가 비어 있을 수 있습니다.

DocumentInfo

사용자 이벤트와 연결된 세부적인 문서 정보입니다.

JSON 표현 
{
  "promotionIds": [
    string
  ],
  "joined": boolean,

  // Union field document_descriptor can be only one of the following:
  "id": string,
  "name": string,
  "uri": string
  // End of list of possible types for union field document_descriptor.
  "quantity": integer,
  "conversionValue": number
}
필드
promotionIds[]

string

이 문서와 연결된 프로모션 ID입니다. 현재 이 필드는 ID가 최대 1개로 제한됩니다.
joined

boolean

출력 전용입니다. 참조된 문서를 데이터 스토어에서 찾을 수 있는지 여부입니다.

통합 필드 document_descriptor. 연결된 Document의 필수 설명자입니다.

  • id가 지정되면 저장된 문서로 주석을 달 때 {location}, {collection_id}, {data_store_id}, {branch_id}의 기본값이 사용됩니다.

  • name가 지정되면 저장된 문서로 주석을 달 때 {location}, {collection_id}, {data_store_id}, {branch_id}에 제공된 값 (기본값 허용)이 사용됩니다. document_descriptor은 다음 중 하나여야 합니다.
id

string

Document 리소스 ID입니다.
name

string

Document 리소스 전체 이름으로, 형식은 projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/branches/{branchId}/documents/{documentId}입니다.
uri

string

Document URI - 웹사이트 데이터 스토어에만 허용됩니다.
quantity

integer

사용자 이벤트와 연결된 문서의 수량입니다. 기본값은 1입니다.

예를 들어 동일한 문서의 수량이 2개인 경우 add-to-cart 이벤트에 참여하면 이 필드는 2가 됩니다.

다음 이벤트 유형의 이벤트에 필요합니다.

  • add-to-cart
  • purchase
conversionValue

number

(선택사항) 이 문서와 연결된 전환 가치입니다. UserEvent.event_type이 'conversion'인 경우 설정해야 합니다.

예를 들어 값 1000은 watch 전환 유형의 문서를 보는 데 1, 000초가 소요되었음을 나타냅니다.

PanelInfo

사용자 이벤트와 연결된 세부 패널 정보입니다.

JSON 표현 
{
  "panelId": string,
  "displayName": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panelPosition": integer,
  "totalPanels": integer
}
필드
panelId

string

필수 항목입니다. 패널 ID입니다.
displayName

string

패널의 표시 이름입니다.
documents[]

object (DocumentInfo)

(선택사항) 이 패널과 연결된 문서 ID입니다.
panelPosition

integer

사용자에게 다른 패널과 함께 표시되는 경우 패널의 순서가 지정된 위치입니다. 설정된 경우 totalPanels도 설정해야 합니다.
totalPanels

integer

사용자에게 표시되는 패널의 총수입니다(이 패널 포함). panelPosition가 설정된 경우 설정해야 합니다.

SearchInfo

자세한 검색 정보입니다.

JSON 표현 
{
  "searchQuery": string,
  "orderBy": string,
  "offset": integer
}
필드
searchQuery

string

사용자의 검색어입니다.

정의는 SearchRequest.query를 참고하세요.

값은 5,000자 길이 제한이 있는 UTF-8 인코딩 문자열이어야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

search 이벤트에는 searchQuery 또는 PageInfo.page_category 중 하나 이상이 필요합니다. 다른 이벤트 유형에는 이 필드를 설정하면 안 됩니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
orderBy

string

해당하는 경우 제품이 반환되는 순서입니다.

정의 및 구문은 SearchRequest.order_by를 참고하세요.

값은 1,000자 길이 제한이 있는 UTF-8 인코딩 문자열이어야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

search 이벤트에만 설정할 수 있습니다. 다른 이벤트 유형에는 이 필드를 설정하면 안 됩니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
offset

integer

페이지로 나누기 위한 현재 오프셋을 지정하는 정수입니다(API에서 관련성 있는 것으로 간주되는 제품 중에서 0부터 시작하는 색인의 시작 위치).

정의는 SearchRequest.offset를 참고하세요.

이 필드가 음수이면 INVALID_ARGUMENT이 반환됩니다.

search 이벤트에만 설정할 수 있습니다. 다른 이벤트 유형에는 이 필드를 설정하면 안 됩니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

CompletionInfo

완료 기여 분석 토큰 및 클릭된 완료 정보를 포함한 자세한 완료 정보입니다.

JSON 표현 
{
  "selectedSuggestion": string,
  "selectedPosition": integer
}
필드
selectedSuggestion

string

최종 사용자가 CompleteQueryResponse.QuerySuggestion.suggestion를 선택했습니다.
selectedPosition

integer

최종 사용자가 선택한 CompleteQueryResponse.QuerySuggestion.suggestion 위치입니다(0부터 시작).

TransactionInfo

거래는 전체 구매 거래를 나타냅니다.

JSON 표현 
{
  "currency": string,
  "transactionId": string,
  "value": number,
  "tax": number,
  "cost": number,
  "discountValue": number
}
필드
currency

string

필수 항목입니다. 통화 코드입니다. 3자리 ISO-4217 코드를 사용하세요.
transactionId

string

길이 제한이 128자(영문 기준)인 거래 ID입니다.
value

number

필수 항목입니다. 거래와 관련된 0이 아닌 총 값입니다. 이 값에는 배송비, 세금 또는 포함하려는 총 가치에 대한 기타 조정 금액이 포함될 수 있습니다.
tax

number

거래와 관련된 모든 세금입니다.
cost

number

제품과 관련된 모든 비용입니다. 제조 비용, 최종 사용자가 부담하지 않는 배송비 또는 기타 비용이 여기에 해당할 수 있습니다.
discountValue

number

이 거래에 적용된 총 할인 값입니다. 이 수치는 TransactionInfo.value에서 제외해야 합니다.

예를 들어 사용자가 TransactionInfo.value 금액을 지불한 경우 거래의 명목상 (할인 전) 값은 TransactionInfo.value와 TransactionInfo.discount_value의 합계입니다.

즉, 할인 값과 관계없이 이익이 동일한 방식으로 계산되며 TransactionInfo.discount_value이 TransactionInfo.value보다 클 수 있습니다.

MediaInfo

미디어 관련 사용자 이벤트 정보입니다.

JSON 표현 
{
  "mediaProgressDuration": string,
  "mediaProgressPercentage": number
}
필드
mediaProgressDuration

string (Duration format)

해당하는 경우 미디어 진행 시간(초)입니다. 예를 들어 최종 사용자가 90초 길이의 재생 동영상을 시청했다면 MediaInfo.media_progress_duration.seconds는 90으로 설정해야 합니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.
mediaProgressPercentage

number

미디어 진행률은 미디어 전체 길이에 대한 mediaProgressDuration만 사용하여 계산해야 합니다.

이 값은 [0, 1.0] 이상이어야 합니다.

재생이 아니거나 진행률을 계산할 수 없는 경우 (예: 진행 중인 라이브 스트림) 이 필드는 설정되지 않아야 합니다.

메서드

collect

 브라우저에서 단일 사용자 이벤트를 작성합니다.

import

 사용자 이벤트를 일괄 가져옵니다.

purge

 제공된 필터로 지정된 모든 사용자 이벤트를 영구적으로 삭제합니다.

write

 단일 사용자 이벤트를 작성합니다.