このドキュメントでは、イベント定義の目的とベストプラクティスについて説明します。
手元のロードマップ資料と照らし合わせながらイベント定義を作成していきましょう。

イベント定義の概要

イベントとは

イベントとはユーザーのサービス内（アプリやサイト）の行動一つひとつのことを表します。
イベントは接客サービス配信時に必要となるセグメント・配信のトリガー・ゴールに利用します。
null

なお、イベントの仕様詳細は KARTE基礎知識・仕様イベントの仕様 を参照ください。

イベント定義の目的

下図の通り、イベントを定義して実装する主な目的は「ユーザーの行動計測と属性取得」です。
イベントにはデータ型を持つフィールドを複数追加できます。
なお、実装したイベントはKARTEの以下機能で活用できます。
・セグメントの作成条件
・施策配信のトリガー
・接客に埋め込む情報
・効果測定（CVポイント規定）
null

イベント定義の進め方

施策から考える
まず施策を考え、その施策を実施するためのセグメントや配信トリガーに必要なイベントを定義しましょう。
イベント実装前にイベント定義書を正しく作成することで企画運用担当とSDK実装担当との認識齟齬がなくなり、特定のイベントが足りないことで施策ができなかったという事態を防げます。

KARTE活用のために定義すべき3つのイベント
KARTE活用のため定義すべきイベントは表の通り3種類です。
viewは機械的に全画面で送信するよう設計するため、イベント設計では、identify/attributeおよび、customイベントの送信タイミングや、施策に活用する属性及び行動を洗い出すことが主となります。

イベント種類（概要） 送信タイミング 用途
1. viewイベント（画面閲覧） 画面表示時 行動分析、配信トリガー用途
2. identify/attributeイベント（ユーザー情報更新） ユーザー属性情報の取得更新時 主に施策対象とするユーザー属性の指定
3. customイベント（その他のユーザー行動） 指定の行動時 主に施策対象、効果測定（CVポイント）

イベント定義書では、上記3つのイベントについて下記を明確に表現する必要があります。

  1. どんな施策がしたいか（例: ポップアップを配信したい/ユーザーの離脱箇所をファネルで分析したい）
  2. どんなイベントで （例: 商品の購入イベントをcustomイベントのbuyという名前で送る）
  3. どんなデータを（例: 購入した商品の個数や金額）
  4. いつ（例: 購入完了画面を表示した時に）
  5. どのように送るのか（例: アプリの購入はSDKから送る、Web側の購入はサーバーサイドAPIで送る）

イベントの実装イメージ（ECアプリ）

ECアプリでのイベント実装イメージ
下図はECアプリでのイベント実装イメージとなります。
以降のステップで、手元のイベント定義書と照らし合わせながら個別のイベントの定義を行いましょう。
null

設計や実装が不要なイベントを把握する

下記のイベントはSDKが自動で送信するため、設計や実装不要でセグメントなどにご活用いただけます。
自動送信されるイベントやフィールドを、アプリ側で重複して送信しないようご注意ください。

画面閲覧の計測（viewイベント）を定義する

閲覧イベントとも呼ばれ、webでは計測タグで計測が行われます。
viewイベントはユーザー行動の分析以外に施策のトリガーやゴールにも利用するため、全ての画面に実装してください。
viewイベントを実装しない場合の影響についてはこちらを参照ください。

フィールドの構成

下記表記載のフィールドはviewイベント送信の際の必須項目となります。
尚、詳細情報を送信したい場合にはviewイベントのフィールドを追加するのではなく、別途view_itemなどのカスタムイベントの実装を推奨します。（詳細）

No. フィールド名 値 備考
1 view_name ”top" 画面毎に一意な画面ID名を半角英数字で設定してください
2 title "トップ画面" 管理画面上で表示されるページ名、他の画面と区別でき認識しやすい名前を日本語で設定してください 
view_nameで一覧画面と詳細画面を区別する際は、商品一覧画面（item_list）、商品詳細画面（item_detail）のように_listと_detailを末尾につけることを推奨します。

イベントの送信タイミングと送信方法

イベントの送信タイミング
各画面の表示直後（実装: iOS/Android） 、WebViewの計測は計測タグ設定が必要です（実装: iOS/Android）

イベントの送信方法
viewイベントはSDKからのみ送信可能です。（参考: イベントの送信方法と機能差分）

ユーザー情報更新（identify/attributeイベント）を定義する

ユーザー情報更新に利用できるイベントはidentify/attributeの2種類があります。
ユーザー情報のうち、個人情報はidentifyで、それ以外をattributeで使い分けて送ることを推奨しております。

何が個人情報にあたるかは各社毎の個人情報の取り扱いポリシーにより異なります。貴社法務担当者と相談の上判断ください。

identifyイベントとは

identifyイベントはユーザーの個人情報を送信するイベントです。
identifyでuser_id（ハッシュ化したものでも可）を送ることでKARTE上でビジターからメンバーになります。
ログイン時のユーザー行動を統合するため、Web/アプリで必ず同じuser_idを送信ください。
このイベントは個人情報を扱うという特性上KARTEでのセグメント利用などの制限がございます。

attributeイベントとは

attributeイベントは個人情報以外のユーザー属性情報を送信するイベントです
identifyイベントとは異なり、セグメントに広く活用することができます。
user_idや個人情報以外のユーザー属性情報を付与したい場合は当イベントでの送信を推奨します。
attributeイベントで個人情報を送信しないようご注意ください

identifyイベントのフィールド構成

identifyイベントへのuser_idの付与は必須です。下記、フィールドの一例となります。
その他のフィールドを追加する場合はフィールド名や型の決め方も参照ください。

フィールド名 概要 例 型
user_id 後述する「user_idとは」をご参照ください。 “000”
“taro.karte@example.com”		 文字列
first_name 名前(名)
管理画面上やアクション時に、名前を参照することが出来ます。		 “茂” 文字列
last_name 名前(性)
管理画面上やアクション時に、名前を参照することが出来ます。		 “佐藤” 文字列
email メールアドレスです。
アクションとしてメールを利用する場合には必須です。		 “sato_shigeru@plaid.co.jp” 文字列
subscription メールマガジン登録の可否です。
falseの場合、アクションでメールを設定しても送信されません。
アクションとしてメールを利用する場合には必須です。		 true BOOL
phone 電話番号です。アクションとしてSMSを利用する場合には必須です。 "08012345678" 文字列
phone_subscribe SMS配信の可否です。
falseの場合、アクションでSMSを設定しても送信されません。
アクションとしてSMSを利用する場合には必須です。		 true BOOL

user_idとは
ユーザーを識別するユニークなIDです。
複数ブラウザ、端末間でユーザーを同一認識する事が出来ます。
ユーザーIDを意味する値をidentifyイベントで送信する場合は、必ずuser_idという名称で、システム上でユニークなID（1人のユーザーに対して与えられ、システム上で重複しない）を文字列形式で送信してください。
visitorの場合には、user_idを送付しないようご注意ください。
複数人のユーザーが1人のメンバーに紐付き、正常にユーザーを認識できなくなります。

attributeイベントのフィールド構成

下記がattributeイベントのフィールドの一例となります。
1人のユーザーに紐づく個人情報以外の属性情報や累積値（今月の購入金額の合計値）などは、attributeイベントのフィールドとしての送信を推奨しています。
その他のフィールドを追加する場合はフィールド名や型の決め方も参照ください。

フィールド名 概要 例 型
signup_date 会員登録日です。 1652839977（unixtime） 日付
age 年齢です 32 数値
gender 性別です "female", "male", "その他" 文字列
pref_cd 都道府県コード（JIS X 0401）です "01" 文字列
birth_date 誕生年月日です。 485230377（unixtime） 日付
birth_month 後述する「birth_monthとは」をご参照ください。 8, “08”, “AUG” 文字列
数値

birth_monthとは
誕生月です。
数値での指定も可能ですが、同一サイト内で型は揃える必要があります。
「以上/以下」というルールを指定をしたい場合は数値、正規表現でルールを指定したい場合は文字列型を推奨します。

イベントの送信タイミングと送信方法

identify/attributeイベントの送信タイミング
次のタイミングでの送信を推奨します。

  • 起動時（ユーザー情報を最新に保つため、例: Webサイト側での会員情報の更新など）
  • 会員登録時
  • ログイン時
  • ログアウト時
  • ユーザーの会員ランクやプロフィールなどユーザー属性が更新されたとき

identifyイベントの送信方法

  • SDKからの送信を推奨します（参考: イベントの送信方法と機能差分）
  • ユーザー情報がアプリ上で取得できない場合はWebタグやサーバーサイドAPIの併用をご検討ください
  • KARTE導入前のユーザー情報の一括連携や定期的なバッチ連携をする場合はKARTE Datahub導入をご検討ください

attributeイベントの送信方法

  • （推奨）SDKからidentifyを送信後、個人情報以外のフィールドを「attributeイベントで送る」機能で振り分けできます
  • 直接SDKからattributeイベントを送信することも可能です
  • ユーザー情報がアプリ上で取得できない場合はWebタグやサーバーサイドAPIの併用をご検討ください
  • KARTE導入前のユーザー情報の一括連携や定期的なバッチ連携をする場合はKARTE Datahub導入をご検討ください

その他のユーザー行動の計測（customイベント）を定義する

customイベントはviewイベントとidentifyイベント以外のユーザー行動を計測するイベントの総称です。

イベント名やフィールドの決め方

イベント名はユーザーの行動を端的に示す「動詞」で表現することを推奨します。
※イベント名には制限がございます。詳細は使用できないイベント名を参照ください。
イベントのフィールドについて検討する際はフィールド名や型の決め方も参照ください。

代表的なイベント

以下にユーザー分析観点で実装を推奨する代表的なイベントを記載します。
これらのイベントのスキーマは業界毎に良く利用されるイベントをまとめたイベントストアでも確認いただけます。

イベント名 計測対象 送信タイミング
signup 会員登録を計測するためのイベント 会員登録完了時
login ログインを計測するイベント。ログインはstatusがtrue、ログアウト時はfalseで更新ください。 ログイン又はログアウト時
search 検索機能の利用を計測するためのイベント 検索実行時
favorite お気に入りへの追加を計測するためのイベント お気に入りに商品を追加した時
view_item アイテム詳細画面の情報をセグメントなどに活用するため計測します、アイテムのIDをitem_idというフィールドで追加ください アイテム詳細画面の閲覧時
buy 購入を計測するためのイベント（主にECで利用想定） 購入金額はrevenue, 個別商品はitemsというフィールドを追加ください 購入完了時
cart カートへの追加を計測するイベント（カート落ちユーザーへの施策で利用、主にECで利用想定） カートに商品を追加した時

イベントの送信タイミングと送信方法

イベントの送信タイミング
会員登録のタイミングや商品の購入などコンバージョンとなるタイミングや、新機能の利用傾向など特に分析を行いたいユーザー行動を送信します

イベントの送信方法

  • SDKからの送信を推奨します。（参考: イベントの送信方法別の機能差分）
  • 必要な情報がアプリ上で取得できない場合はWebタグやサーバーサイドAPIの併用をご検討ください

フィールド名や型の決め方

フィールド名や値について
フィールド名や値についてはこちらの制限を参考にご判断ください。

フィールドの型の決め方ついて
KARTEではイベントのフィールド型毎に異なる統計データが作られ、セグメントに指定できる条件も異なります。
下記にデータの種類別に推奨するフィールドのデータ型について記載します。

データの種類 推奨データ型 推奨理由
個数や金額 数値型 値の大小比較をセグメント条件に指定可能になるため
ID（ユーザーIDや商品IDなど） 文字列型 複数IDへの完全一致などがセグメント条件に指定可能になるため
日付（会員登録日や退会日など） 日付型（詳細） dateフィールドと同様に相対/絶対時間指定で比較可能になるため

その他のケースについては解析される統計値の計算パターンを参考に個別に判断ください。

イベントの送信方法と機能差分

イベントには3つの送信方法があり、それぞれ実装手段が異なります。
イベント定義書作成時に各イベントをどの方法で送信するか明確にしておきましょう。

  1. SDK: 基本かつ推奨の送信方法です。ユーザーの行動に合わせてイベントをKARTEに送信します。
  2. Web計測タグ: アプリ内Webviewの行動を計測タグとSDKを紐付けることにより計測します。
  3. サーバーサイドAPI: アプリ内で取得できない情報をサーバーサイドから直接KARTEに送信する方法です。

下記表の通りアプリ内メッセージの配信トリガーに利用できるのはSDKからのイベント送信だけです。
出来る限りSDKからのイベント送信をご検討ください。

送信方法 アプリ内メッセージ配信トリガー ゴール機能 リアルタイム解析 必要な準備や実装
SDK ◯ ◯ ◯ 実装方法
Web計測タグ △（接客表示制御の対象外） ◯ ◯ 実装方法（iOS/Android）
サーバーサイドAPI ✕ ◯ ◯ お申し込み及び実装が必要（詳細）