このページは Cloud Translation API によって翻訳されました。

メディアユーザーイベントについて

このページでは、ユーザーイベントの種類、要件、ユーザーイベントの種類の例など、メディア検索とレコメンデーションアプリのユーザーイベントについて説明します。メディアアプリではユーザーイベントが必要です。

メディア検索とレコメンデーションの一般的な情報については、メディア検索とレコメンデーションの概要をご覧ください。

ユーザーイベントの記録については、リアルタイムユーザーイベントの記録をご覧ください。過去のユーザーイベントを一括でインポートするには、過去のユーザーイベントをインポートするをご覧ください。

ユーザーイベントタイプ

エンドユーザーがサイトを閲覧または検索する際に、次の種類のユーザーイベントを記録できます。

ユーザーイベント名	ユーザーの操作
`view-item`	ドキュメントの詳細を表示します。
`view-home-page`	ホームページを表示します。
`search`	データストアを検索します。
`media-play`	メディアアイテムの再生をクリックします。
`media-complete`	メディアアイテムの再生を停止し、視聴の終了を示します。

ユーザーイベントオブジェクトの詳細については、UserEvent API リファレンスドキュメントをご覧ください。

メディア検索とレコメンデーションのイベント要件

必要なユーザーイベントのタイプは、アプリが検索アプリかレコメンデーションアプリか、目標（クリック率、コンバージョン率、総再生時間）によって決まります。レコメンデーションアプリの場合は、選択したモデルのタイプによっても決まります。レコメンデーションモデルのタイプと最適化の目標について詳しくは、メディアアプリのレコメンデーションタイプについてをご覧ください。

収集する必要があるユーザーイベントを特定するには、次の表を参照してください。

イベント	`search`	`view-home-page`	`view-item`	`media-play`	`media-complete`
検索のユースケース
	必須	不要	必須	必須	必須
目標別の「あなたへのおすすめ」モデルタイプ
クリック率	不要	ホームページコンテキストでは必須一般的なコンテキストでは必須ではありません	`view-item` または `media-play` のいずれかが必要です		強く推奨履歴の降格がオンの場合は必須
CVR	不要	ホームページコンテキストでは必須一般的なコンテキストでは必須ではありません	`view-item` または `media-play` のいずれかが必要です		必須
視聴時間	不要	ホームページコンテキストでは必須一般的なコンテキストでは必須ではありません	`view-item` または `media-play` のいずれかが必要です		必須
[関連商品のおすすめ] モデルタイプ（目標別）
クリック率	不要	不要	`view-item` または `media-play` のいずれかが必要です		強く推奨履歴の降格がオンの場合は必須
CVR	不要	不要	`view-item` または `media-play` のいずれかが必要です		必須
視聴時間	不要	不要	`view-item` または `media-play` のいずれかが必要です		必須
「もっと見る」モデルタイプ（目標別）
クリック率	不要	不要	`view-item` または `media-play` のいずれかが必要です		履歴の降格がオンになっている場合は必須
CVR	不要	不要	`view-item` または `media-play` のいずれかが必要です		必須
視聴時間	不要	不要	`view-item` または `media-play` のいずれかが必要です		必須
目標別の最も人気のあるモデルタイプ
クリック率	不要	不要	`view-item` または `media-play` のいずれかが必要です		不要
CVR	不要	不要	不要	不要	必須

メディアユーザーイベントの要件

メディアアプリが高品質の結果を生成できるように、ユーザーイベントが次の要件を満たしていることを確認します。

イベントの種類	要件	影響
すべてのイベント	合成データまたは重複イベントを含めないでください。	合成イベントや重複イベントは結果の品質に悪影響を及ぼし、アプリのデプロイを妨げる可能性があります。重複イベントにより、指標の値に誤りが生じる可能性があります。
	取り込まれるイベントのタイプごとに 100 個以上の一意のユーザー疑似 ID を含みます。	メディアレコメンデーションアプリが高品質の結果を生成するのに十分なデータを確保できるように、これらの ID を含めます。
	ユーザー疑似 ID は、イベントのインポートまたはイベントの記録全体で、またメディアレコメンデーションリクエストでも、まったく同じ形式にする必要があります。	ユーザー疑似 ID に一貫した形式を使用すると、メディアレコメンデーションアプリは訪問者のパターンを正しく識別し、ユーザーの行動に基づいてより良い結果を提供できます。
	すべてのドキュメントで `DocumentInfo.name` フィールドまたは `DocumentInfo.id` フィールドが必要です。	`DocumentInfo.name` フィールドまたは `DocumentInfo.id` フィールドのないドキュメントを含むイベントは、メディアレコメンデーションアプリでは使用できません。
	イベントに含まれるドキュメントは、データストアに存在する必要があります。	未結合イベントの比率はできるだけ低くする必要があります。この比率が高いと、結果の品質に悪影響を与える可能性があります。
	ユーザーイベントによっては、同じユーザー疑似 ID を使用する必要があります。	有効な動作シーケンスの履歴を作成するには、メディアレコメンデーションアプリが同じユーザー仮想 ID を持つ複数のイベントを参照できる必要があります。たとえば、`visitor123` は 5 つのアイテムを閲覧し、2 つのアイテムで再生をクリックしました。これらのイベントで同じ形式のユーザー疑似 ID が一貫して提供される場合、メディアレコメンデーションアプリは、その動作シーケンスを結果に反映できます。
`view-item`	イベントごとに 1 つのドキュメントのみを含めます。	ドキュメントが存在しない場合、イベントは使用できません。複数のドキュメントが含まれている場合、イベントは不正な形式になり、使用できません。
`search`	`attributionToken` を含めます。`attributionToken` は、検索またはブラウジングの結果とともに search メソッドによって返されます。	`attributionToken` により、Vertex AI Search は検索イベントを特定の検索レスポンスに正確に関連付けることができます。
`media-play`	イベントごとに 1 つのドキュメントのみを含めます。	複数のドキュメントが含まれている場合、イベントは不正な形式になり、使用できません。

A/B テストのユーザーイベントタグ

A/B テストを実施する場合は、収集するすべてのユーザーイベントにタグ ID を追加し、テストグループごとに 1 つのタグを追加してください。

たとえば、現在のモデルのユーザーイベントに "tagIds": ["original"] タグを追加し、メディア向け Vertex AI Search のユーザーイベントに "tagIds": ["google"] タグを追加します。

ユーザーイベントタイプの例とスキーマ

このセクションでは、メディアレコメンデーションでサポートされる各イベントタイプのデータ形式について説明します。JavaScript Pixel の例が用意されています。BigQuery の場合、各タイプのテーブルスキーマ全体が用意されています。

すべてのユーザーイベントタイプでは、userId は省略可能です。

ユーザーイベントオブジェクトの詳細については、UserEvent API リファレンスドキュメントをご覧ください。

view-item

view-item ユーザーイベントのデータ形式は、次のとおりです。

最低限必要な view-item オブジェクト

次の例は、view-item ユーザーイベント形式の必須項目のみを示しています。

ほとんどの場合、documents には関連付けられたドキュメントの詳細が含まれます。

JavaScript Pixel

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "id": "document-id"
  }]
  "panels": [
     {
       "panelId": "HOME_RFY_1",
       "documents": [
         {
           "id": "123"
         },
         {
           "id": "456"
         }
       ],
       "panelPosition": 1,
       "totalPanels": 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"
          }
        ]
      }
    ]
  }
]

完全な view-item オブジェクトの例

次の例は、view-item ユーザーイベントの必須項目と省略可能な項目の両方を含んでいます。

JavaScript 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: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  panels [
         {
           panelId: "HOME_RFY_1",
           documents: [
             {
               id: "123"
             },
             {
               id: "456"
             }
           ],
           panelPosition: 1,
           totalPanels: 2
         }
      ]
};

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 ユーザーイベント形式の必須項目のみを示しています。

JavaScript Pixel

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "panels": [
     {
       "panelId": "HOME_RFY_1",
       "documents": [
         {
           "id": "123"
         },
         {
           "id": "456"
         }
       ],
       "panelPosition": 1,
       "totalPanels": 2
     }
  ]
};

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

panels オブジェクトについては、パネルについてをご覧ください。

完全な view-home-page オブジェクトの例

次の例は、view-home-page ユーザーイベントの必須項目と省略可能な項目の両方を含んでいます。

JavaScript 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: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  panels [
         {
           panelId: "HOME_RFY_1",
           documents: [
             {
               id: "123"
             },
             {
               id: "456"
             }
           ],
           panelPosition: 1,
           totalPanels: 2
         }
      ]
};

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 ユーザーイベント形式の必須項目のみを示しています。

ユーザーがテキストクエリを入力した検索イベントに searchQuery を指定します。

attributionToken は検索クエリの結果とともに返されます。

documents には、検索結果ページ内でエンドユーザーに表示されるドキュメント ID のリストを含める必要があります。

JavaScript Pixel

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

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": "attributionToken",
    "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 ユーザーイベント形式の必須項目のみを示しています。

JavaScript Pixel

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

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 ユーザーイベントの必須項目と省略可能な項目の両方を含んでいます。

JavaScript 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: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
};

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 ユーザーイベント形式の必須項目のみを示しています。

JavaScript 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": 0.2
  }
};

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 ユーザーイベントの必須項目と省略可能な項目の両方を含んでいます。

JavaScript 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: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  mediaInfo: {
    mediaProgressDuration: "65s",
    mediaProgressPercentage: 0.2,
  },
};

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 は一意のユーザー ID を表し、ユーザーイベントを記録する際に必要です。

ユーザーイベントを記録するときに表示されるユーザー情報（UserInfo）には、userPseudoId の値と userId の値（使用可能な場合）が含まれます。userId は省略可能で、ユーザーがサイトにログインするたびに、デバイス間で一意の永続的な識別子として使用できます。ユーザーの userId を記録すると、メディア検索アプリとおすすめアプリは、モバイルデバイスやウェブブラウザなど、ユーザーが複数のデバイスで 1 人のユーザーに対してカスタマイズされた結果を生成できます。

タイムスタンプについて

ユーザーイベントを記録する際は、イベントが発生した正確なタイムスタンプを必ず含めるようにしてください。正確なタイムスタンプにより、イベントが正しい順序で保存されます。タイムスタンプは、JavaScript Pixel を使用して収集されたイベントに対して自動的に記録されます。イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。

パネルについて

ホームページには通常、「急上昇」パネルや「おすすめ」パネルなど、1 つ以上のパネルがあります。詳細ページには、「おすすめ」などのパネルが表示されることもあります。

ユーザーイベントのパネル情報

パネル情報は、タイプ view-home-page と view-item のレコメンデーションユーザーイベントに必要です。Google がおすすめするコンテンツを表示するホームページと詳細ページには、パネル情報が必要です。

パネルの A/B テストを実施する場合は、ソースに関係なく、テスト内のすべてのコンテンツについて、パネル情報を含むユーザーイベントを記録する必要があります。Google が生成したパネルコンテンツのないホームページと詳細ページでは、view-home-page イベントと view-item イベントでパネル情報を提供することが推奨されますが、必須ではありません。これらの要件を次の表にまとめます。

ユーザーイベントのソース（`view-home-page` と `view-item`）	`PanelInfo`（必須）
Google がおすすめするコンテンツが含まれます。	○
Google が推奨していないコンテンツや A/B テストで使用されているコンテンツも含まれます	○
Google が推奨しておらず、A/B テストで使用されていないコンテンツが含まれます。	×

パネル情報（PanelInfo）は、パネルのさまざまな要素を記述する一連のフィールドです。

パネルの ID 番号
表示名
ページ上のパネルの位置（例: ページ上の最初のパネル（1）、ページ上の 3 番目のパネル（3）など）
ページ上のパネルの合計数
各パネルに表示されるドキュメントのリスト（DocumentInfo）

PanelInfo オブジェクトの詳細については、PanelInfo をご覧ください。

パネルのプリロードと遅延読み込み

ウェブページやモバイルページにレコメンデーションを表示する一般的な方法は 2 つあります。使用するメソッドによって、記録する view-home-page ユーザーイベントの数と内容が決まります。

事前読み込み: 事前読み込みでは、ユーザーがページにアクセスする前に、すべての推奨アイテムが生成されます。この場合、ユーザーがホームページを読み込むと、すべてのパネルとドキュメントを含む 1 つの view-home-page（または view-item）ユーザーイベントが記録されます。
遅延読み込み: 遅延読み込みでは、ユーザーがページにアクセスしたときにパネルのコンテンツは生成されません。ユーザーがパネルまで下にスクロールしたり、右にスクロールしておすすめのコンテンツを表示したりしたときに、コンテンツが動的に読み込まれます。この場合、ユーザーがホームページを読み込むと、最初の view-home-page（または view-item）ユーザーイベントが記録され、ユーザーがスクロールしておすすめコンテンツを生成すると、さらに多くのイベントが記録されます。後続のイベントでは、表示されるドキュメントの増分のみを panels 配列に含める必要があります。

シナリオの例

メディア企業のホームページに、おすすめの 2 つのパネルが表示されています。

最も人気のあるモデルを搭載した、急上昇中のパネル。
A/B テスト中のパーソナライズされたおすすめパネル。一部のユーザーには、あなたへのおすすめモデル（グループ A）による候補のパネルが表示され、他のユーザーには、会社の独自モデル（グループ B）によるおすすめが表示されます。

グループ B に割り当てられたユーザーがこのホームページを閲覧すると、JavaScript ピクセル形式のユーザーイベントは次のようになります。

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "4003345673.123451357",
  "eventTime": "2025-07-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "jane.doe@example.com",
  },
  "tagIds": ["group-B"],
  "panels": [
    {
      "panelId": "panel-1",
      "displayId": "Trending Now",
      "documents": [
        {
          "id": "254722"
        },
        {
          "id": "2951"
        },
        ...
        {
          "id": "1201"
        }
      ],
      "panelPosition": 1,
      "totalPanels": 2
    },
    {
      "panelId": "panel-2",
      "displayId": "Recommended for You",
      "documents": [
        {
          "id": "79132"
        },
        {
          "id": "109487"
        },
        ...
        {
          "id": "164179"
        }
      ],
      "panelPosition": 2,
      "totalPanels": 2
    }
  ]
};

次のステップ

詳しくは、ユーザーイベントを記録する方法をご覧ください。

メディア ユーザー イベントについて コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ユーザー イベントタイプ

メディア検索とレコメンデーションのイベント要件

メディア ユーザー イベントの要件

A/B テストのユーザー イベントタグ

ユーザー イベントタイプの例とスキーマ

view-item

最低限必要な view-item オブジェクト

JavaScript Pixel

BigQuery

完全な view-item オブジェクトの例

JavaScript Pixel

BigQuery

view-home-page

最低限必要な view-home-page オブジェクト

JavaScript Pixel

BigQuery

完全な view-home-page オブジェクトの例

JavaScript Pixel

BigQuery

検索

最低限必要な search オブジェクト

JavaScript Pixel

BigQuery

media-play

最低限必要な media-play オブジェクト

JavaScript Pixel

BigQuery

完全な media-play オブジェクトの例

JavaScript Pixel

BigQuery

media-complete

最低限必要な media-complete オブジェクト

JavaScript Pixel

BigQuery

完全な media-complete オブジェクトの例

JavaScript Pixel

BigQuery

カスタム属性

ユーザー情報について

タイムスタンプについて

パネルについて

ユーザー イベントのパネル情報

パネルのプリロードと遅延読み込み

シナリオの例

次のステップ

メディアユーザーイベントについて

ユーザーイベントタイプ

メディアユーザーイベントの要件

A/B テストのユーザーイベントタグ

ユーザーイベントタイプの例とスキーマ

ユーザーイベントのパネル情報