> For the complete documentation index, see [llms.txt](https://docs.wicle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wicle.io/data-extension/custom-event.md).

# カスタムイベント

Wicleのカスタムイベントとフィールドを定義して独自の行動データを送信する手順、コンバージョン設定、分析画面での利用方法を説明します。

## カスタムイベントでできること <a href="#what-you-can-do" id="what-you-can-do"></a>

購入完了など、任意のタイミングでイベントを送信できます。購入金額や商品IDなど、その行動に付随する情報も一緒に送信できます。利用には、サイトやサーバーへのコードの実装が必要です。

すでに計測しているイベントを条件で絞り込み、別のイベントとして扱いたい場合は、コードの実装が不要な[コードレスイベント](https://docs.wicle.io/data-extension/codeless-event.md)を使えます。会員ランクなど、ユーザーごとの属性を更新する場合は[ユーザープロファイル](https://docs.wicle.io/data-extension/user-profile.md)を使います。

## 設定・実装方法 <a href="#setup-and-implementation" id="setup-and-implementation"></a>

先に管理画面でイベントとフィールドを定義し、その後で送信処理を実装します。設定前に送信したデータは遡って表示されません。設定後に送信したデータだけが集計・検索の対象になります。

イベント名は作成後に変更できません。同じプロジェクト内のカスタムイベント・コードレスイベントで重複しない名前を付けてください。

1. `データ設定`から`カスタムイベント`を開き、`作成`を選択します。
2. `表示名`と`イベント名`を入力します。表示名は管理画面で使う名前、イベント名はコードから送信するときの識別子です。
3. 購入金額などを一緒に送る場合はフィールドを追加し、`表示名`・`キー`・`データ型`を設定します。キーは送信するデータの項目名です。データ型は、文字列・数値・真偽値から選びます。
4. `作成`を選択し、確認画面でも作成を確定します。作成後の変更は、編集画面で`保存`します。

<figure><img src="https://1516189518-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhDtk9aBzYOvC8RRWtKCd%2Fuploads%2FEdF5lzaI3xBsz5QAYLFX%2Fimage.png?alt=media&amp;token=19c3ab54-f8f6-485e-9043-234da96c50ba" alt="データ設定からカスタムイベントを開くメニュー"><figcaption></figcaption></figure>

### 入力項目の制限 <a href="#input-limits" id="input-limits"></a>

| 項目           | 制限                                                                                             |
| ------------ | ---------------------------------------------------------------------------------------------- |
| 表示名          | 必須。50文字以内                                                                                      |
| イベント名        | 必須。50文字以内。半角英数字とアンダースコア（`_`）を使用し、先頭は英字またはアンダースコアにします                                           |
| フィールド数       | 新規作成時は1イベントにつき10個まで                                                                            |
| フィールドの表示名・キー | どちらも必須。それぞれ30文字以内                                                                              |
| フィールドのキー     | 半角英数字・アンダースコア（`_`）・ドット（`.`）を使用できます。先頭は英字またはアンダースコア、末尾は半角英数字またはアンダースコアにします。同じイベント内で重複するキーは使えません |

イベント名には、Wicleが予約している名前や`_wcl`を含む名前は使用できません。

10個を超えるフィールドが登録済みの場合は、保存済みの個数が上限になります。フィールドを削除して保存すると上限も減りますが、10個未満にはなりません。

カスタムイベントの作成数の上限は、Freeプランが10個、Growthプランが30個です。Customプランや個別の契約条件は、[プロジェクトのリミット](https://docs.wicle.io/organization-project/project-setting/limitation.md)で確認してください。

### クライアントサイドでの実装方法 <a href="#block-7928913db673463faea6dab1f8695aa2" id="block-7928913db673463faea6dab1f8695aa2"></a>

計測するページに[計測タグ](https://docs.wicle.io/initial-setting/tag.md)を設置してから、カスタムイベントの送信処理を組み込みます。設定画面のコードサンプルを実装担当者に渡し、送信するタイミングと値を指定してください。

たとえば、イベント名が`buy`、購入金額のキーが`revenue`、注文IDのキーが`transaction_id`の場合は、次のように送信します。フィールドの定義とデータ型は、管理画面の設定に合わせます。

```javascript
window.krt('send', 'buy', {
  revenue: 9800,
  transaction_id: 'ORDER-001'
});
```

購入完了を計測する場合は、購入が完了したタイミングで送信します。購入ボタンを押した時点とは区別してください。

実装後はサイトで対象の操作を行い、[Chrome拡張のイベントビューア](https://docs.wicle.io/chrome-extension/event-viewer.md)でイベント名と送信した値を確認します。管理画面への反映には[集計の時間](https://docs.wicle.io/data-setting/measured-data/renewal-period.md)がかかります。

<figure><img src="https://1516189518-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhDtk9aBzYOvC8RRWtKCd%2Fuploads%2FuUqvN3uXLR8WSAGEP7Zy%2Fimage.png?alt=media&amp;token=98b3459f-eb53-49de-8888-13793663f215" alt="カスタムイベントのフィールド設定とコードサンプルの表示例"><figcaption><p>画像内のコードは表示例です。実装には、現在の設定画面に表示されるコードサンプルを使ってください。</p></figcaption></figure>

### タグ読み込み前のエラーを防ぐ <a href="#wait-for-krt" id="wait-for-krt"></a>

計測タグの初期化コードは、`window.krt`を定義し、外部スクリプトの読み込みが完了するまで呼び出しを保存します。初期化コードを送信処理より先に実行すれば、外部スクリプトの読み込み完了を待つ必要はありません。

初期化コードより先に送信処理を実行すると、`window.krt is not a function`のようなJavaScriptエラーが発生します。たとえば、ページ下部にタグを設置した場合や、GTMによるタグ配信より先に送信処理が動く場合です。

まず、初期化コードが送信処理より先に実行されるように設置してください。実行順を揃えられない場合は、次の例のように`window.krt`が定義されるまで待ちます。

```javascript
function whenKrtReady(callback) {
  if (typeof window.krt === 'function') return callback();
  var timer = setInterval(function () {
    if (typeof window.krt === 'function') {
      clearInterval(timer);
      callback();
    }
  }, 200);
}

whenKrtReady(function () {
  window.krt('send', 'signup');
});
```

{% hint style="info" %}
計測タグを `</head>` タグの直前など、できるだけ早い位置に設置することで、このエラーが発生しにくくなります。
{% endhint %}

### サーバーサイドでの実装方法 <a href="#server-side-implementation" id="server-side-implementation"></a>

Web APIで送信できます。利用には弊社側での設定とアクセストークンの受け渡しが必要です。[サポート窓口](https://docs.wicle.io/other/support/contact.md)へお問い合わせください。

## コンバージョンの設定 <a href="#conversion-setting" id="conversion-setting"></a>

作成・編集画面の`コンバージョン設定`で、`中間コンバージョン`または`最終コンバージョン`を有効にします。途中の目標には中間コンバージョン、購入完了などの最終目標には最終コンバージョンを使います。同時に両方を指定することはできません。

設定したイベントは、[CVダッシュボード](https://docs.wicle.io/analytics/dashboard.md#conversion)や[CV到達経路分析](https://docs.wicle.io/analytics/dashboard/cv-path.md)で使えます。

## その他の設定 <a href="#other-settings" id="other-settings"></a>

### フォルダ管理 <a href="#folder-management" id="folder-management"></a>

一覧画面の`フォルダを作成`で、カスタムイベントをフォルダに整理できます。

## おすすめの設定例 <a href="#recommended-examples" id="recommended-examples"></a>

イベント名やキーは一例です。計測したい行動と、分析に必要な情報に合わせて設定します。

| 表示名・イベント名         | 送信するタイミング     | フィールドの例                                                                                                   |
| ----------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
| 会員登録（`signup`）    | 会員登録が完了したとき   | 付随する情報が不要なら、フィールドなしで送信                                                                                    |
| ログイン（`login`）     | ログイン状態が変わったとき | 状態（`status`）。ログイン時は`true`、ログアウト時は`false`                                                                  |
| カート（`cart`）       | カートを操作したとき    | 価格（`price`）、商品ID（`item_id`）、商品名（`name`）、商品カテゴリ（`item_category`）                                           |
| 購入（`buy`）         | 購入が完了したとき     | 購入金額（`revenue`）、商品数（`item_count`）、ユーザーの累計購入回数（`buy_total`）、累計購入金額（`buy_pay_total`）、注文ID（`transaction_id`） |
| お気に入り（`favorite`） | お気に入りに追加したとき  | 対象のID（`item_id`）、名前（`name`）、カテゴリ（`item_category`）                                                         |
| 検索（`search`）      | 検索したとき        | 検索キーワード（`keyword`）                                                                                        |

## 各画面での利用/確認方法 <a href="#block-bc055e0b0a9345ebb580d02346b1ed76" id="block-bc055e0b0a9345ebb580d02346b1ed76"></a>

| 画面                 | 利用箇所           | できること                                         |
| ------------------ | -------------- | --------------------------------------------- |
| ユーザー               | 検索条件           | `ユーザーディメンション（コードレス/カスタムイベント）`で発生回数を条件に設定      |
| ユーザー               | ユーザーリスト        | カスタムイベントごとの発生回数を表示                            |
| イベント               | 検索条件・ファセット     | イベントやフィールドの値で検索し、値の内訳を確認                      |
| ライフサイクル            | フェーズの条件        | エントリー・活性化済み・ファンの条件として設定                       |
| キー行動               | キー行動の条件        | 対象の行動として設定                                    |
| ファネル               | ステップの条件・ユーザー一覧 | 特定のイベントやフィールドの値を条件に設定し、ステップに到達した・しなかったユーザーを確認 |
| ユーザー詳細             | イベントタイムライン     | `イベントデータを表示`から、送信された値を確認                      |
| セグメント              | 検索条件           | カスタムイベントの発生回数を条件として設定                         |
| CVダッシュボード・CV到達経路分析 | コンバージョン        | 中間・最終コンバージョンに設定したイベントを確認                      |
