イベントを送信する
ユーザーの行動に応じたアクションを行うために、あらかじめユーザーの行動に基づくイベントを KARTE に送る必要があります。
SDK では目的別にイベント送信メソッドを複数用意しています。
イベントの送信方法について
画面閲覧イベントを送信する
画面の閲覧をイベントとして送る場合は、viewイベントを送信します。
第2引数のtitleの指定は任意ですが、指定することでユーザー詳細画面（管理画面）に画面名が表示されるようになり、どの画面を閲覧しているのか認識しやすくなります。
第3引数のvaluesの指定も任意ですが、指定することでアプリケーション固有の情報を追加で付与することが可能です。
Viewメソッドの仕様に関しては、APIリファレンスをご覧ください。
using Newtonsoft.Json.Linq;
using Io.Karte;
JObject values = new JObject ();
values.Add("stage_name", "1st_stage");
values.Add("game_score", 200);
Tracker.View("game_clear", "ゲームクリア", values);
// valuesが不要な場合
// Tracker.View("game_clear", "ゲームクリア");
なお Viewイベントの送信は、Trackメソッドを利用しても行うことが可能です。
下記の実装は、上記実装と同等の意味合いとなります。
using Newtonsoft.Json.Linq;
using Io.Karte;
JObject values = new JObject ();
values.Add("view_name", "game_clear");
values.Add("title", "ゲームクリア");
Tracker.Track("view", values);
ユーザー情報を送信する
ユーザーに紐付く情報 (名前や年齢、性別等) を送る場合は、identifyイベントを送信します。
イベントは複数回送信することが可能です。
また送信したデータは、過去に送ったデータとマージして管理されます。
Identifyメソッドの仕様に関しては、APIリファレンスをご覧ください。
ユーザーデータ管理プラグインがインストールされたKARTEプロジェクトでは、identify イベント 送信の際、user_id の値は必須となります。user_id の送信なしに、属性情報の送信を行う場合は attributeイベント をご利用下さい。
using Newtonsoft.Json.Linq;
using Io.Karte;
JObject values = new JObject ();
values.Add("user_id", "ユーザーID（文字列）");
values.Add("name", "KARTE太郎");
Tracker.Identify(values);
なおidentifyイベントの送信は、trackメソッドを利用しても行うことが可能です。
下記の実装は、上記実装と同等の意味合いとなります。
using Newtonsoft.Json.Linq;
using Io.Karte;
JObject values = new JObject ();
values.Add("user_id", "ユーザーID（文字列）");
values.Add("nick_name", "KARTE太郎");
Tracker.Track("identify", values);
任意のイベントを送信する
上記以外のイベントを送信する場合は、カスタムイベントとしてイベントを送信できます。
なお一部のイベント名は予約されており、KARTE 上で特殊な扱いを受けます。
詳細に関しては、定義済みイベント をご覧ください。
Trackメソッドの仕様に関しては、APIリファレンスをご覧ください。
using Newtonsoft.Json.Linq;
using Io.Karte;
JObject values = new JObject ();
values.Add("item_name", "awesome_item");
Tracker.Track("get_item", values);
送信可能な値型について
各イベント送信メソッドには、カスタムオブジェクトと呼ばれるオブジェクト一緒に渡すことが可能です。
これにより、イベントに様々な値を紐づけて送信することが可能です。
なおカスタムオブジェクトには、任意の key や value を指定することが可能ですが、指定時の型には制限があります。
key として利用可能な型
string のみ利用可能です。
イベントで使用できないフィールド名も合わせてご確認ください。
value として利用可能な型
以下の型のみ利用可能です。
なお 日付型はlong(unixtime)で指定してください。
- JObject
- JArray
- string
- bool
- int
- long
- float
- null
JObject, JArrayについて
JObject,JArrayはJson.NETのクラスです。
詳細は以下のAPIリファレンスをご覧ください。
自動で付与されるフィールドについて
Identify以外のイベントでは、自動で端末や各種バージョン等の情報をSDKが自動で付与します。
各プラットフォーム毎の自動で付与されるフィールドの詳細については以下をご覧ください。
特別な扱いが行われるフィールドについて
日時情報を送信するためのフィールド
日時情報を送信するためには、任意のイベントに、フィールド名の末尾が date となるフィールドを追加する必要があります（例：xxx_date）
このようにすることで、管理画面で日時情報を含むフィールドとして扱われ、日時（絶対時間・相対時間）を利用したセグメントやトリガーの設定が可能になります。
なおフィールドの値には、long型(unixtime)の値を指定してください。
using System;
using Newtonsoft.Json.Linq;
using Io.Karte;
long unixTime = DateTimeOffset.Now.ToUnixTimeSeconds ();
JObject values = new JObject ();
values.Add("event_date", unixTime);
Tracker.Track("event", values);
位置情報を送信するためのフィールド
位置情報を送信するためには、任意のイベントに、フィールド名の末尾がlatlngとなるフィールドを追加する必要があります（例：latlng / xxx_latlng）
このようにすることで、KARTE側で位置情報を含むフィールドとして扱われ、位置情報（マップ）を利用したセグメントやトリガーの設定が可能になります。
なおフィールドの値には、位置情報を配列（経度、緯度の順番）で指定してください。
位置情報フィールドの値の指定方法について
配列の0番目には、
経度 (longitude)を、1番目には緯度 (latitude)を、それぞれ数値で指定する必要があります。
逆に指定した場合正しくセグメント・トリガーが機能しない場合がありますので、ご注意ください。
using Newtonsoft.Json.Linq;
using Io.Karte;
JArray latlng = new JArray();
latlng.Add(139.7649361);
latlng.Add(35.6812362);
JObject values = new JObject ();
values.Add("latlng", latlng);
Tracker.Track("current_location", values);
閲覧人数表示テンプレートを利用するために必要なフィールド
閲覧人数表示テンプレートを利用するためにはViewイベントに、view_idフィールドを追加する必要があります。
view_idの値には、画面を一意に識別するための文字列を指定してください。
また閲覧人数表示テンプレートについてはこちらのドキュメントも併せてご覧ください。
using Newtonsoft.Json.Linq;
using Io.Karte;
JObject values = new JObject ();
values.Add("view_id", "p123456789");
Tracker.View("product", values);
Updated 5 months ago