사용자 이벤트 정보

이 페이지에서는 사용자 이벤트 유형, 요구사항, 사용자 이벤트 유형의 예시를 포함하여 미디어 앱의 사용자 이벤트를 설명합니다.

미디어 추천 앱에는 사용자 이벤트를 기록해야 합니다. 미디어 추천 앱은 실시간 사용자 이벤트를 사용하여 추천을 생성합니다. 다른 앱 유형에는 사용자 이벤트가 필요하지 않습니다.

다음 표에는 사용자 이벤트를 업로드할 앱 유형이 나와 있습니다.

앱 유형	사용자 이벤트가 필요한가요?
미디어 추천	예
미디어 검색	아니요, 그러나 적극 권장됩니다.
일반 권장사항	아니요
일반 검색	아니요, 그러나 적극 권장됩니다.

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

사용자 이벤트 유형

최종 사용자가 사이트를 탐색할 때 다음 유형의 사용자 이벤트를 기록할 수 있습니다.

사용자 이벤트 이름	사용자 작업
view-category-page	홈 > TV > 드라마, 홈 > 영화 > 액션과 같은 카테고리 페이지를 봅니다.
view-item	문서의 세부정보 페이지를 봅니다.
view-home-page	홈페이지를 봅니다.
search	데이터 스토어를 검색합니다.
media-play	미디어 항목에서 재생을 클릭합니다.
media-complete	미디어 항목의 재생을 중지하여 시청 종료를 나타냅니다.

UserEvent 객체에 관한 자세한 내용은 UserEvent API 참조를 확인하세요.

미디어 앱의 사용자 이벤트 요구사항 및 권장사항

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

또한 사용하려는 추천 유형 및 최적화 목표에 따라 필요한 사용자 이벤트 유형이 나열된 미디어 앱 추천 유형 정보도 참고하세요.

미디어 추천의 이벤트 유형 우선순위

다음 표에서는 미디어 추천에 대한 사용자 이벤트 유형의 우선순위를 설명합니다. 미디어 추천을 사용하려면 일부 사용자 이벤트가 필요합니다. 다른 항목은 결과를 개선하는 데 도움이 되지만 필수는 아닙니다.

우선순위 사용자 이벤트

미디어 추천을 사용한 초기 실시간 실험에 필수

우선순위	사용자 이벤트
미디어 추천을 사용한 초기 실시간 실험에 필수	`view-item` `view-home-page` `media-play` `media-complete`
시간 경과에 따른 미디어 추천 결과 품질 개선에 중요	`view-category-page`

시간 경과에 따른 미디어 추천 결과 품질 개선에 중요

view-category-page

미디어 추천 요구사항

미디어 추천 앱에서 품질 결과를 생성할 수 있도록 사용자 이벤트가 다음 요구사항을 충족하는지 확인합니다.

이벤트 유형	요구사항	영향
모든 이벤트	합성 데이터나 중복 이벤트를 포함하지 마세요.	합성 또는 중복 이벤트는 결과 품질에 부정적인 영향을 미치며 앱을 배포하지 못하게 될 수 있습니다. 중복 이벤트로 인해 측정항목 값이 잘못될 수 있습니다.
	수집된 각 이벤트 유형에 순 사용자 가명 ID를 100개 이상 포함합니다.	이렇게 하면 미디어 추천 앱이 고품질 결과를 생성할 만큼 충분한 데이터를 갖게 됩니다.
	사용자 가명 ID는 이벤트 가져오기 또는 이벤트 기록과 미디어 추천 요청에서 정확히 동일한 형식이어야 합니다.	사용자 가명 ID에 일관된 형식을 사용하면 미디어 추천 앱이 방문자 패턴을 올바르게 식별하고 사용자 행동을 기준으로 더 나은 품질의 결과를 제공할 수 있습니다.
	모든 문서에는 `DocumentInfo.name` 필드 또는 `DocumentInfo.id` 필드가 필요합니다.	`DocumentInfo.name` 필드 또는 `DocumentInfo.id` 필드가 없는 문서가 포함된 이벤트는 미디어 추천 앱에서 사용할 수 없습니다.
	이벤트에 포함된 문서는 데이터 스토어에 있어야 합니다.	조인되지 않은 이벤트 비율을 최대한 낮게 유지해야 합니다. 비율이 높으면 결과 품질에 부정적인 영향을 줄 수 있습니다.
	일부 사용자 이벤트의 사용자 가명 ID는 동일해야 합니다.	유효한 동작 시퀀스 기록을 구성하려면 미디어 추천 앱은 동일한 사용자 가명 ID로 여러 이벤트를 볼 수 있어야 합니다. 예를 들어 `visitor123`은 5개의 항목을 조회하고 2개에서 재생을 클릭했습니다. 이러한 이벤트가 모두 동일한 형식의 사용자 가명 ID를 제공하는 경우 미디어 추천 앱은 결과에서 이 동작 시퀀스를 고려할 수 있습니다.
`view-item`	이벤트당 정확히 하나의 문서를 포함합니다.	문서가 없으면 이벤트를 사용할 수 없습니다. 문서가 여러 개 포함된 경우 이벤트 형식이 잘못되어 사용할 수 없습니다.
`media-play`	이벤트당 정확히 하나의 문서를 포함합니다.	여러 문서가 포함된 경우 이벤트 형식이 잘못되어 사용할 수 없습니다.

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

이 섹션에서는 미디어 추천에서 지원하는 각 이벤트 유형의 데이터 형식을 제공합니다.

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

모든 사용자 이벤트 유형에서 userId는 선택사항입니다.

다음 사항을 참고하세요.

tagIds 필드는 A/B 실험을 실행하는 경우에만 필수입니다.
attributionToken 필드는 선택사항이며 성능 측정에 사용됩니다. 미디어 추천 클릭에서 생성된 search 및 view-item 이벤트에는 이벤트를 생성한 추천에 다시 연결하려면 기여 분석 토큰이 있어야 합니다.

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

view-category-page

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

최소 필수 view-category-page 객체

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

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

자바스크립트 Pixel

var user_event = {
  "eventType": "view-category-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "pageInfo": {
    "pageCategory": "category1 > category2"
  }
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

전체 view-category-page 객체 예시

다음 예시에는 view-category-page 사용자 이벤트의 필수 필드와 선택 필드가 모두 포함되어 있습니다.

자바스크립트 Pixel

var user_event = {
  eventType: "view-category-page",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "abc@example.com",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    pageCategory: "Sales > New Year Deals",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["321"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

view-item

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

최소 필수 view-item 객체

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

대부분의 경우 documents에는 연결된 문서의 세부정보가 포함됩니다.

자바스크립트 Pixel

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "id": "document-id"
  }]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

전체 view-item 객체 예시

다음 예시에는 view-item 사용자 이벤트의 필수 필드와 선택 필드가 모두 포함되어 있습니다.

자바스크립트 Pixel

var user_event = {
  eventType: "view-item",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "abc@example.com",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["321"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

view-home-page

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

최소 필수 view-home-page 객체

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

자바스크립트 Pixel

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "quantity",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

전체 view-home-page 객체 예시

다음 예시에는 view-home-page 사용자 이벤트의 필수 필드와 선택 필드가 모두 포함되어 있습니다.

자바스크립트 Pixel

var user_event = {
  eventType: "view-home-page",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "abc@example.com",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
      quantity: 2,
    },
  ],
  tagIds: ["321"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "quantity",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

search

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

최소 필수 search 객체

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

searchQuery 또는 pageCategory 필드 중 하나 이상이 필요합니다.

사용자가 텍스트 쿼리를 입력한 검색 이벤트에는 searchQuery를 제공합니다.
사용자가 텍스트 쿼리를 입력하는 대신 둘러보기를 통해 관심분야 항목으로 이동한 경우(즉, 카테고리를 클릭하여 이동한 경우) pageCategory를 제공합니다.

documents는 검색 결과 페이지에 최종 사용자에게 표시되는 문서 ID 목록을 포함해야 합니다.

자바스크립트 Pixel

var user_event = {
  eventType: "search",
  userPseudoId: "user-pseudo-id",
  eventTime: "2020-01-01T03:33:33.000001Z",
  searchInfo: {
    searchQuery: "search-query",
  },
  pageInfo: {
    pageCategory: "category1 > category2",
  },
  documents: [
    {
      id: "document-id1",
    },
    {
      id: "document-id2",
    },
  ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "searchInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "searchQuery",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

media-play

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

최소 필수 media-play 객체

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

자바스크립트 Pixel

var user_event = {
  "eventType": "media-play",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [
    {
      "id": "document-id1"
    }
  ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

전체 media-play 객체 예시

다음 예시에는 media-play 사용자 이벤트의 필수 필드와 선택 필드가 모두 포함되어 있습니다.

자바스크립트 Pixel

var user_event = {
  eventType: "media-play",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "abc@example.com",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["321"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

media-complete

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

최소 필수 media-complete 객체

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

자바스크립트 Pixel

var user_event = {
  "eventType": "media-complete",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [
    {
      "id": "document-id1"
    }
  ],
  "mediaInfo": {
    "mediaProgressDuration": "65s",
    "mediaProgressPercentage": 1.2
  }
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "mediaInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mediaProgressDuration",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "mediaProgressPercentage",
        "type": "NUMERIC",
        "mode": "NULLABLE"
      }
    ]
  }
]

전체 media-complete 객체 예시

다음 예시에는 media-complete 사용자 이벤트의 필수 필드와 선택 필드가 모두 포함되어 있습니다.

자바스크립트 Pixel

var user_event = {
  eventType: "media-complete",
  userPseudoId: "visitor0",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "abc@example.com",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["321"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  mediaInfo: {
    mediaProgressDuration: "65s",
    mediaProgressPercentage: 1.2,
  },
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "mediaInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mediaProgressDuration",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "mediaProgressPercentage",
        "type": "NUMERIC",
        "mode": "NULLABLE"
      }
    ]
  }
]

맞춤 속성

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

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

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

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

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

사용자 정보

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

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

타임스탬프 정보

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

다음 단계

사용자 이벤트 기록 방법 알아보기