# 実装ガイド グループ分析を利用するための、フィールド設定からタグ実装、確認までの一連の手順を説明します。 ## 全体の流れ 実装は3つのステップで完了します。 1. **グループプロファイルのフィールド設定** — 管理画面でグループの属性項目を定義する 2. **`group_identify` の実装** — 各グループの属性情報をWicleに送信する 3. **`set_group` の実装** — 各イベントを「どのグループの行動か」と紐付ける {% hint style="info" %} 2と3の両方を実装する必要があります。それぞれの役割は [概要ページの「仕組みの全体像」](/group-analytics/group_analytics/overview.md#mechanism) を参照してください。 {% endhint %} ## ステップ0: 自社環境の確認 実装方法を決める前に、自社プロダクトが以下のどちらの環境かを確認してください。 | 環境 | 例 | 実装方針 | | --------------- | ---------------------------------------- | ----------------------------------------------------------- | | **シングルアカウント環境** | 1ユーザー = 1企業に固定で所属。ログインしたら所属企業は変わらない | ログイン直後に1度 `set_group` を実行する | | **マルチアカウント環境** | 1ユーザーが複数企業を切り替え可能（マルチテナント、複数組織を扱うコンソール等） | グループ切り替えのタイミングで `set_group` を実行する。フックが取れない場合はインターバル処理での実装も可 | 詳しい実装の違いは [ステップ3](#set-group) を参照してください。 ## 最小実装サンプル まずは動くコードから把握したい場合、以下が最小構成です。シングルアカウント環境を前提としています。 ```javascript // ① グループの属性情報を送信（ログインユーザーの所属企業情報など） window.krt('send', 'group_identify', { group_id: 'company_001', name: '株式会社サンプル', }); // ② 以降のイベントを上記グループに紐付け window.krt('local', { wicle: { method: 'set_group', group_id: 'company_001', }, }); ``` この2つを、ユーザーがログインした直後など、グループが特定できたタイミングで実行します。 詳細とマルチアカウント環境の実装は以下のステップで説明します。 ## ステップ1: グループプロファイルのフィールド設定 `データ設定` > `フィールド設定(グループプロファイル)` から、グループの属性として送信したいフィールドを設定します。 設定したフィールドに応じて、データを送信するためのJavaScriptサンプルコードが自動生成されます。 ### デフォルトフィールド 以下のフィールドはデフォルトで設定されています。
key名セットする内容
group_idグループのID。グループとして特定したい一意の値をセットしてください。グループ単位は任意ですが、非常に大量のユーザーが所属するグループでは分析が成立しないため、適切に分割される単位を選んでください
nameグループの表示名（Wicle内各画面の表示名としても使用されます）
photoグループのプロフィール画像のURL（Wicle内各画面のアイコンとしても使用されます）
### カスタムフィールドを追加する 業界、契約プラン、利用開始日などの独自属性を追加できます。`+` ボタンでフィールドを追加し、表示名・キー・データ型を入力します。 サポートされているデータ型: `String` / `Number` / `Boolean` {% hint style="warning" %} **フィールド編集時の制約** * デフォルトフィールド (`group_id`, `name`, `photo`) は、表示名のみ編集可能です（キーとデータ型は変更不可） * 一度作成したカスタムフィールドのキーは、後から変更できません * カスタムフィールドの数には契約プランごとの上限があります {% endhint %} ## ステップ2: グループプロファイルの送信 (`group_identify`) 設定画面に表示されるサンプルコードを参考に、`window.krt` の呼び出しをサイト上に組み込みます。 ```javascript window.krt('send', 'group_identify', { group_id: '', name: '', photo: '', // 他のカスタムフィールドも同様に }); ``` 実行すると、指定した `group_id` に対する属性情報が登録され、管理画面でグループの詳細閲覧や検索が可能になります。 ### `group_id` の設計指針 * String型・256文字以内の値を指定してください * グループ単位は任意ですが、1グループに非常に多くのユーザーが所属する設計では分析が成立しにくくなります。適切に分割される単位を選んでください * 一度割り当てた `group_id` は変更しないことを推奨します（紐付け済みのイベントとの整合性が取れなくなるため） ### 注意事項 * `group_identify` を送信した段階では、ユーザーとの紐付けは発生しません。`set_group` の実装が別途必要です * 第二引数のオブジェクトのフィールドは `group_id` を除き全てオプショナルです。データを更新したくないキーは記述自体を省略してください {% hint style="info" %} `group_identify` はカスタムイベント送信と同様のインターフェースですが、イベント数としてカウントされません(請求対象外です)。 また、同一端末上で再度同じデータが送信された場合、データ送信が抑制されることがあります。 {% endhint %} ## ステップ3: イベントへのグループ紐付け (`set_group`) `set_group` を実行することで、それ以降に発生するイベントが「どのグループの行動か」と紐付きます。 ```javascript window.krt('local', { wicle: { method: 'set_group', group_id: '', }, }); ``` 実装方法は、自社環境がシングルアカウントかマルチアカウントかで異なります。 ### シングルアカウント環境の場合 ユーザーが特定の企業に固定で所属し、所属が切り替わらない環境では、シンプルに以下を実装すれば十分です。 * ユーザーがログインした直後（または所属企業が特定できたタイミング）で `set_group` を1度実行する 一度実行すると、そのユーザーの以降の行動には自動でグループ情報が引き継がれます。 {% hint style="info" %} **毎回のアクセス時に実行することを推奨** 引き継ぎ情報はブラウザのストレージで保持されますが、長期間（目安として約30日以上）アクセスがない状態から復帰したケースや、別端末でアクセスしたケースでは引き継ぎができない場合があります。 そのため、毎回のアクセス時に1度は `set_group` を実行する実装を推奨します。 {% endhint %} ### マルチアカウント環境の場合 1ユーザーが複数のグループを切り替えて利用する環境では、グループの切り替えが発生するたびに `set_group` を実行してください。 切り替えのタイミングをフックで取れる場合は、その都度実行します。フックが取れない場合は、インターバル処理で常に現在のグループをセットし続ける実装も可能です。 ```javascript setInterval(() => { window.krt('local', { wicle: { method: 'set_group', group_id: getCurrentGroupId(), // 現在のグループIDを返す関数 }, }); }, 300); ``` {% hint style="info" %} `set_group` 自体はイベント送信を発生させないため、頻繁に実行しても請求や負荷の観点で問題はありません。 {% endhint %} 複数タブで異なるグループを操作する場合も、`SessionStorage` と `LocalStorage` の併用により、同一タブ内では混在せずに `group_id` が引き継がれます。詳しい挙動は [詳細仕様](/group-analytics/group_analytics/advanced-spec.md) の「複数グループに所属するユーザーの扱い」を参照してください。 ### グループ所属をリセットする ユーザーがログアウトした場合など、どのグループにも所属していない状態にしたい場合は、`group_id` に `null` をセットして実行します。 ```javascript window.krt('local', { wicle: { method: 'set_group', group_id: null, }, }); ``` ## 実装後の確認方法 [Wicle Chrome拡張機能](https://chromewebstore.google.com/detail/wicle/bffmcidaikenijljoemhaghdciokoeei) の最新バージョンをインストールすることで、`group_identify` と `set_group` の実装が正しく動作しているかを確認できます。 拡張の詳しい使用方法は [タグ埋め込み後のイベント確認方法](/data-setting/event-tracking/debug-event.md) を参照してください。 ### `group_identify` の確認 Chrome拡張で送信データを確認し、`Group identify` (Group Profile) の送信履歴と、Payloadの値（`group_id` 等）が期待値と一致しているかを確認します。
* 送信履歴自体が表示されない場合: タグの実装方法に問題がある可能性があります * Payloadの値が期待値と違う場合: 引数の設定方法に問題がある可能性があります ### `set_group` の確認 `set_group` が正しく実行されていれば、各イベントの `Event Meta` セクションの `Group ID` 欄に、セットした `group_id` 文字列が表示されます。
{% hint style="warning" %} `set_group` の処理はアプリケーション側で実行されるため、`view` イベントなどタグ読み込み後に即座に送信されるイベントでは、多くの場合 `Group ID` が表示されません。 その場合はクリック等のイベントで `Group ID` を確認してください。 なお、Chrome拡張上で `Group ID` が認識されていないイベントも、データ解析時の補正処理で `Group ID` のセットが行われます。 {% endhint %} 正しい送信が確認できない場合は、チャットでお気軽にお問い合わせください。 ## データインポート（CSV） `データ設定` > `データインポート(グループプロファイル)` から、CSVファイルをアップロードしてグループプロファイルデータを一括更新できます。 ### CSVファイル形式 * ヘッダー行が必須です * `group_id` 列は必須です。それ以外は更新したいフィールドのキー名を指定します サンプル: ``` group_id,int_field,string_field,boolean_field group1,123,ABC,true group2,456,DEF,false ``` ### インポート履歴の確認 データインポート画面では、過去のインポート履歴をテーブル形式で確認できます。各履歴のステータス、ファイル名、対象カラム、行数、実行者が表示されます。 エラーが発生した行については、詳細を確認できます。 ### インポート時の注意事項 * ヘッダー行に `group_id` が無い場合や、フィールド設定に存在しないキー名が記述されている場合、データ型がフィールド設定と一致しない場合（数値型フィールドに文字列をセットするなど）は、アップロード処理自体がエラーとなります * 存在しない `group_id` のレコードは正常に処理されますが、そのレコードのデータ更新処理は行われません * データインポートで更新するフィールドを `group_identify` タグでも送信している場合、最後に実行されたものが採用されます。両方で更新が行われても不整合とならない運用設計をしてください ## 注意事項・制約 * `group_id` は String型・256文字以内です * カスタムフィールドの数には契約プランごとの上限があります（[利用状況](/organization-project/organization-setting/usage.md) から確認できます） --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.wicle.io/group-analytics/group_analytics/implementation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.