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 Cookie で実装できます。これにより、1 台のデバイス上の訪問者を一意に識別できます。この一意の識別子は、訪問者がウェブサイトに対してログインまたはログアウトしても変更されません。

異なるユーザーに対して同じ固定 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 メソッドでのみ必須です。ユーザー イベントが発生したタイムスタンプ。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「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 リクエストがエンドユーザー（モバイルアプリなど）から直接行われた場合にのみ設定する必要があります（ゲートウェイまたはサーバーがユーザー イベントを処理して push している場合は設定しないでください）。

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 を URL パラメータとして商品 K のページに渡します。商品 K のページでイベントを記録するときは、このフィールドに RecommendResponse.attribution_token を記録します。
filter

string

フィルタ構文は、フィルタ対象となるドキュメントの 1 つ以上のフィールドから述語を生成するための式言語で構成されます。

たとえば、search イベントの場合、関連付けられた SearchRequest の SearchRequest.filter には、https://google.aip.dev/160#filtering に準拠したフィルタ式が含まれている場合があります。

同様に、RecommendRequest から生成された view-item-list イベントの場合、このフィールドは https://google.aip.dev/160#filtering に準拠する RecommendRequest.filter から直接入力されることがあります。

値は UTF-8 でエンコードされた文字列で、長さの上限は 1,000 文字です。それ以外の場合は、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

このユーザー イベントが属する独立したテストグループの ID リスト。これは、異なるテスト設定に関連付けられたユーザー イベントを区別するために使用されます。
promotionIds[]

string

プロモーションに関連付けられたイベントの場合のプロモーション ID。現在、このフィールドは最大 1 つの ID に制限されています。
attributes

map (key: string, value: object)

レコメンデーション モデルに含める追加のユーザー イベントの特徴。これらの属性には、JSON などの解析や処理が必要なデータを含めてはなりません。

取り込まれたユーザー イベントのカスタム属性を指定する場合は、予測リクエストに関連付けるユーザー イベントにも含めます。カスタム属性の形式は、インポートされたイベントと、予測リクエストで指定されたイベントの間で一貫している必要があります。これにより、Discovery Engine API はモデルのトレーニング時や予測の提供時にこれらのカスタム属性を使用できるため、レコメンデーションの品質向上に役立ちます。

このフィールドは、以下のすべての条件を満たしている必要があります。満たしていない場合、INVALID_ARGUMENT エラーが返されます。

  • キーは UTF-8 でエンコードされた文字列で、長さの上限は 5,000 文字です。
  • テキスト属性の場合、最大 400 個の値を指定できます。空の値は使用できません。各値は、長さの上限が 256 文字の UTF-8 でエンコードされた文字列にする必要があります。
  • 数値属性の場合、最大 400 個の値が許可されます。

商品のおすすめの場合、ユーザーがサイトにアクセスした経路を示す traffic_channel がユーザーの追加情報の例です。ユーザーは、サイトに直接アクセスしたり、Google 検索からアクセスしたり、その他の方法でサイトにアクセスしたりします。
attributes.text[]

string

このカスタム属性のテキスト値。たとえば、キーが「color」の場合は ["yellow", "green"] です。

空の文字列は使用できません。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。

CustomAttribute.text または CustomAttribute.numbers のいずれか 1 つのみを設定する必要があります。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。
attributes.numbers[]

number

このカスタム属性の数値。たとえば、キーが「lengths_cm」の場合は [2.3, 15.4] です。

CustomAttribute.text または CustomAttribute.numbers のいずれか 1 つのみを設定する必要があります。それ以外の場合は、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 ヘッダーに含まれるユーザー エージェント。

このフィールドは、長さの上限が 1,000 文字の UTF-8 でエンコードされた文字列にする必要があります。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。

GTM または JavaScript タグでクライアントサイドのイベント レポートを使用している場合（UserEventService.CollectUserEvent）や、UserEvent.direct_user_request が設定されている場合は、こちらを設定しないでください。
timeZone

string

省略可。IANA タイムゾーン（例: Europe/Budapest）。

PageInfo

詳細なページ情報。

JSON 表現 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
フィールド
pageviewId

string

ウェブページ ビューの一意の ID。

同じページビューからトリガーされたすべてのユーザー イベントで同じ値にする必要があります。たとえば、アイテムの詳細ページビューでは、ユーザーがページをブラウジングする際に複数のイベントがトリガーされる可能性があります。これらのイベントが適切にグループ化されるように、pageviewId プロパティはすべてのイベントで同じにする必要があります。

JavaScript Pixel と Google タグ マネージャーでクライアントサイドのイベント レポートを使用する場合、この値は自動的に入力されます。
pageCategory

string

カテゴリページに関連付けられている最も具体的なカテゴリ。

カテゴリのフルパスを表すには、異なる階層を区切るために「>」記号を使用します。'>' がカテゴリ名の一部である場合は、別の文字に置き換えます。

カテゴリページには、セールやプロモーションなどの特別なページが含まれます。たとえば、特別セールページには、"pageCategory" : "Sales > 2017 Black Friday Deals" などのカテゴリ階層を設定できます。

view-category-page イベントで必須です。他のイベントタイプでは、このフィールドを設定しないでください。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。
uri

string

ユーザーの現在のページの完全な URL（window.location.href）。

JavaScript Pixel と Google タグ マネージャーでクライアントサイドのイベント レポートを使用する場合、この値は自動的に入力されます。最大文字数は 5,000 文字です。
referrerUri

string

現在のページの参照元 URL。

JavaScript Pixel と 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。現在、このフィールドは最大 1 つの ID に制限されています。
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 をご覧ください。

値は UTF-8 でエンコードされた文字列で、長さの上限は 5,000 文字です。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。

search イベントには、searchQuery または PageInfo.page_category の少なくとも 1 つが必要です。他のイベントタイプでは、このフィールドを設定しないでください。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。
orderBy

string

商品が返される順序（該当する場合）。

定義と構文については、SearchRequest.order_by をご覧ください。

値は UTF-8 でエンコードされた文字列で、長さの上限は 1,000 文字です。それ以外の場合は、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

必須。トランザクションに関連付けられたゼロ以外の合計値。この値には、合計値に含める送料、税金、その他の調整額を含めることができます。
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 に設定されます。

s で終わる小数点以下 9 桁までの秒単位の期間。例: "3.5s"。
mediaProgressPercentage

number

メディアの進行状況は、メディアの合計長に対する mediaProgressDuration のみを使用して計算する必要があります。

この値は [0, 1.0] の範囲で指定する必要があります。

再生ではない場合や、進行状況を計算できない場合（ライブ配信中など）は、このフィールドを未設定にする必要があります。

メソッド

collect

 ブラウザから 1 つのユーザー イベントを書き込みます。

import

 ユーザー イベントを一括インポートします。

purge

 特定のフィルタで指定されたすべてのユーザー イベントを完全に削除します。

write

 1 つのユーザー イベントを書き込みます。