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 から直接入力されることがあります。

この値は、長さの上限が 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

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

string

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

map (key: string, value: object)

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

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

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

  • キーは、長さの上限が 5,000 文字の UTF-8 でエンコードされた文字列にする必要があります。
  • テキスト属性の場合、最大 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 または UserEventService.CollectUserEvent の 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 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

ユーザー イベントに関連付けられた Document の数量。デフォルトは 1 です。

たとえば、同じ Document の 2 つの数量が add-to-cart イベントに関与している場合、このフィールドは 2 になります。

次のイベントタイプのイベントで必須です。

  • add-to-cart
  • purchase
conversionValue

number

省略可。このドキュメントに関連付けられているコンバージョン値。UserEvent.event_type が「conversion」の場合は設定する必要があります。

たとえば、値 1,000 は、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 の少なくとも 1 つが必要です。他のイベントタイプでは、このフィールドを設定しないでください。それ以外の場合は、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

必須。取引に関連付けられたゼロ以外の合計金額。この金額には、含めるべき送料、税金、合計金額に対するその他の調整額を含めることができます。
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 つのユーザー イベントを書き込みます。