> ## Documentation Index
> Fetch the complete documentation index at: https://docs.core.sprocket.bz/llms.txt
> Use this file to discover all available pages before exploring further.

# データの取り込み

> イベント API、サイトトラッキング、データ基盤（DSV2）からの同期の 3 つの取り込み経路と、設定項目・制限をまとめています。

> この記事は Spumote のソースコードから生成した試験出力です。内容は確認中のため、正式な仕様は担当者に確認してください。

## この機能でできること

エンゲージで配信や分析を行うには、まず「誰が（顧客）」「何をしたか（イベント）」をエンゲージに入れる必要があります。取り込みの経路は 3 つあり、用途に応じて組み合わせて使います。

| 経路 | 向いているデータ | 鮮度 |
| - | - | - |
| イベント API | サイト・アプリ・自社システムで起きた行動（購入、カート追加など）と、そのときの顧客属性 | ほぼリアルタイム |
| サイトトラッキング | 自社サイト上のページ表示・クリック・フォーム送信など。タグを埋め込み、画面の設定だけで計測 | ほぼリアルタイム |
| データ基盤（DSV2）からの同期 | BigQuery で集計した会員属性や、過去の購買明細の一括投入 | ワークフローの実行周期 |

## 画面の場所

* API キー（イベント送信用の公開キー）: 設定 › エンゲージ › 基本設定 の「API キー」
* サイトトラッキング: 設定 › エンゲージ › 基本設定 の「トラッキング設定」
* DSV2 からの同期: データ › 自動処理（ワークフロー）のステップとして設定

## イベント API

自社サイトやシステムから、イベント（顧客の行動 1 件）を 1 件ずつ送る受け口です。送ったイベントは、セグメントの条件やジャーニーのきっかけ（トリガー）に使えます。

### 顧客の特定に使う識別子

1 件のイベントには、次のどちらか一方が必要です。

| 項目 | 意味 |
| - | - |
| 会員 ID（memberId） | 自社の会員番号など。顧客を特定する手がかりです |
| 匿名 ID（anonymousId） | ログイン前の訪問者を区別するための ID |

メールアドレス（email）は任意の項目です。メールアドレスだけを送っても受け付けられません（会員 ID か匿名 ID が必要です）。

### イベントと一緒に送れるもの

| 項目 | 内容 |
| - | - |
| イベント名（name） | 必須。例: `purchase`、`add_to_cart`。256 文字まで |
| プロパティ（properties） | イベントの詳細。例: 商品 ID、金額 |
| 顧客属性（traits） | 顧客の属性をこのタイミングで更新したいときに送ります。既存の属性に上書きでマージされます（送らなかった属性は残ります） |
| 発生時刻（timestamp） | 省略すると受信時刻になります |

* メールアドレスは、既存の顧客にまだ設定されていない場合にだけ補完されます。
* サイトから送る場合は、設定 › エンゲージ › 基本設定 で発行した公開 API キーを使います（「03-11 エンゲージの設定」参照）。

## サイトトラッキング

自社サイトにタグ（スニペット）を入れておき、「どのページの・どの要素で・何が起きたら・どんなイベントとして送るか」を画面で設定する仕組みです。サイト側の改修なしで計測項目を増やせます。

### 基本的な使い方

1. 設定 › エンゲージ › 基本設定 の「API キー」で「発行」を押し、サイトにタグを設置します。
2. 同じページの「トラッキング設定」で「新規作成」を押します。
3. 「名前」「トリガー種別」「イベント名」（いずれも必須）を入力し、必要なら「URL パターン」で対象ページを絞ります。
4. 「抽出セレクター」で、ページから一緒に取りたい値（例: カート金額）を「セレクターを追加」で登録します。
5. 「有効」をオンにして「作成」を押します。

一覧には「名前」「トリガー種別」「イベント名」「URL パターン」「状態」「操作」の列があり、「操作」から「編集」「削除」ができます。

### 設定項目

| 項目（画面表示） | 内容 |
| - | - |
| 名前 | 管理用の名前。例: カート追加ボタンのクリック |
| トリガー種別 | いつイベントを送るか（下表） |
| イベント名 | 送るイベントの名前。例: `add_to_cart` |
| URL パターン | 対象ページ。glob 形式（例: `/products/*`）。空欄なら全ページで有効 |
| 抽出セレクター | ページから抜き出してプロパティに入れる値。「プロパティ名」、CSS セレクター、「属性」（textContent / value / href / src / data-*。data-* を選ぶと「属性名」の入力欄が出ます）、「変換」（string / number / boolean / json）、「既定値（任意）」を指定します。「フォーム」と「JSON」の 2 つの編集方式を切り替えられます |
| debounceMs / throttleMs | 連打などで送りすぎないための間隔（ミリ秒） |
| intervalMs | トリガー種別が interval のときだけ表示される、送信間隔（ミリ秒） |
| 有効 | オン / オフ。無効の設定はタグに配られません |

| トリガー種別 | 意味 |
| - | - |
| page\_view（ページ表示） | ページが表示されたとき |
| click（クリック） | 指定した要素がクリックされたとき |
| form\_submit（フォーム送信） | フォームが送信されたとき |
| dom\_change（DOM 変化） | ページの中身が書き換わったとき（カートの中身が変わったときなど） |
| interval（一定間隔） | 一定時間ごと |

## データ基盤（DSV2）からの同期

データ › 自動処理（ワークフロー）にエンゲージへ同期するステップ（engage\_sync）を置くと、BigQuery のテーブルやビューの内容をエンゲージへ流し込めます。同期には 2 つのモードがあります。

| モード（画面表示） | 同期元 | 同期先 | 用途 |
| - | - | - | - |
| コンタクト（属性同期） | 会員ごとに 1 行の集計表 | 顧客の属性 | 最終購入日、累計購入金額、会員ランクなど |
| イベント（backfill） | 行動明細の表 | 顧客のイベント | 過去の購買明細などのまとめて投入 |

共通の設定項目は次のとおりです。

| 項目（画面表示） | 内容 |
| - | - |
| 同期元 BigQuery | 「プロジェクト ID」「データセット ID」とテーブル |
| member\_id 列 | 必須。会員 ID が入っている列。NULL / 空の行はスキップされ、件数が記録されます |
| 同期後にセグメントを再評価 | 同期完了後にセグメントのフル評価を 1 回実行します（既定はオン） |

コンタクト（属性同期）モードの設定項目:

| 項目（画面表示） | 内容 |
| - | - |
| 属性同期する列（カンマ区切り、省略可） | 省略すると member\_id 列以外の全列を同期します |
| 列名 → 属性名の rename（省略可） | 「rename を追加」で、ソースの列名と別の属性名に付け替えます |
| フル同期 | オンにすると、ソースから消えたコンタクトに `source_missing` 属性を付けます（物理削除はしません） |

イベント（backfill）モードの設定項目:

| 項目（画面表示） | 内容 |
| - | - |
| イベント名 | 「固定名」か「列参照」のどちらかで指定します |
| 発生時刻の列 | 必須 |
| 一意キー列（省略可） | 重複登録を防ぐ ID のもとになります。省略するとハッシュで代用します |
| properties に入れる列（カンマ区切り、省略可） | 省略すると会員 ID・イベント名・発生時刻・一意キー以外の全列が入ります |

* **フル同期**で `source_missing` が付いた顧客は、退会者の除外などにセグメント条件として使えます。
* **同期では、ジャーニーの「イベント発生」トリガーは動きません。** 過去の購買履歴を取り込んだ瞬間に大量のメールが送られる事故を防ぐためです。同期が終わったあとにセグメントの再計算が 1 回行われ、その結果セグメントに新しく入った顧客には「セグメントに入った」トリガーが動きます。

## 活用例

* **カート放棄の把握**: トラッキング設定で「カートに入れる」ボタンのクリックを `add_to_cart` として計測し、カートの中身を顧客属性に送ると、セグメントやジャーニーのトリガーに使えます。
* **毎朝の会員属性更新**: DSV2 で会員ごとの最終購入日・累計購入金額を集計し、毎朝の同期で属性に反映。「90 日以上購入のない優良顧客」のようなセグメントが常に最新になります。

## 注意点・制限

* イベントの識別子: 会員 ID か匿名 ID のどちらか 1 つ以上が必要です。
* イベント名・会員 ID は 256 文字まで、匿名 ID は 64 文字までです。
* トラッキング設定: 名前・イベント名は 256 文字まで、URL パターンは 1,024 文字までです。
* トラッキング設定の閲覧はエンゲージの閲覧権限、作成・編集はエンゲージの編集権限が必要です。

## 関連ページ

* [03-1 エンゲージの概要と用語](/mav2/engage-overview)
* [03-5 セグメント](/mav2/segments)
* [03-11 エンゲージの設定](/mav2/engage-settings)
* [02-3-2 自動処理（ワークフロー）：ステップの種類](/dsv2/workflow-steps)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.