ユーザー イベントについて

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

カスタムアプリではユーザー イベントは必須ではありませんが、強く推奨されます。

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

ユーザー イベントタイプ

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

ユーザー イベント名 ユーザーの操作
view-item-list ドキュメントのパネルまたは順序付きリストを表示します。
view-item ドキュメントの詳細を表示します。
view-home-page ホームページを表示します。
search データストアを検索します。

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

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

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

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

次のことに注意してください。

  • tagIds 項目は、A/B テストを実行する場合にのみ必要です。

  • attributionToken 項目は省略可能です。パフォーマンスを測定するために使用されます。 レコメンデーションのクリックから生成された search イベントと view-item イベントには、イベントを生成したレコメンデーションにリンクするための属性トークンが必要です。

ユーザー イベント オブジェクトの詳細については、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"
  }]
};

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

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

search ユーザー イベントの形式は、次のとおりです。

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

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

searchQuery または pageCategory フィールドの少なくとも 1 つは必須です。

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

  • ユーザーがブラウジング（テキスト クエリの入力ではなくカテゴリのクリック）によって興味のあるアイテムに移動した場合は、pageCategory を指定します。

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",
  }, 
  pageInfo: {
    pageCategory: "category1 > category2",
  }, 
  attributionToken: "attribution-token",
  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": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

ユーザー情報について

userPseudoId は一意のユーザー ID を表し、ユーザー イベントを記録する際に必要です。

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

タイムスタンプについて

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

次のステップ