イベントを送信する

🚧

このドキュメントは古いバージョンのiOS SDK v1について記載しています

iOS SDK v1は 2021/05/11でサポート終了となります。
SDK v1 からのアップグレードについては、まず SDK v1からv2のアップグレード方法 をご覧ください。

ユーザーの行動に応じたアクションを行うために、あらかじめユーザーの行動に基づくイベントを KARTE に送る必要があります。

SDK では目的別にイベント送信メソッドを複数用意しています。

イベントの送信方法について

画面閲覧イベントを送信する

画面の閲覧をイベントとして送る場合は、view イベントを送信します。

第2引数の title の指定は任意ですが、指定することでユーザー詳細画面（管理画面）に画面名が表示されるようになり、どの画面を閲覧しているのか認識しやすくなります。

view メソッドの仕様に関しては、リファレンス をご覧ください。

KarteTracker.shared.view("signup", title: "会員登録")

[[KarteTracker sharedTracker] view:@"signup" title:@"会員登録"];

なお viewイベントの送信は、track メソッドの第1引数にviewを指定して行うことも可能です。
下記の実装は、上記実装と同等の意味合いとなります。

KarteTracker.shared.track("view", values: [
  "view_name": "signup",
  "title": "会員登録"
])

[[KarteTracker sharedTracker] track:@"view" values:@{
  @"view_name": @"signup",
  @"title": @"会員登録"
}];

ユーザー情報を送信する

ユーザーに紐付く情報 (名前や年齢、性別等) を送る場合は、identify イベントを送信します。

イベントは複数回送信することが可能です。
また送信したデータは、過去に送ったデータとマージして管理されます。

identify メソッドの仕様に関しては、リファレンス をご覧ください。

KarteTracker.shared.identify([
  "name": "KARTE太郎"
])

[[KarteTracker sharedTracker] identify:@{
  @"name": @"KARTE太郎",
}];

なお identifyイベントの送信は、track メソッドの第1引数にidentifyを指定して行うことも可能です。
下記の実装は、上記実装と同等の意味合いとなります。

KarteTracker.shared.track("identify", values: [
  "name": "KARTE太郎"
])

[[KarteTracker sharedTracker] track:@"identify" values:@{
  @"name": @"KARTE太郎"
}];

任意のイベントを送信する

上記以外のイベントを送信する場合は、カスタムイベントとしてイベントを送信できます。

なお一部のイベント名は予約されており、KARTE 上で特殊な扱いを受けます。
詳細に関しては、定義済みイベント をご覧ください。

track メソッドの仕様に関しては、リファレンス をご覧ください。

KarteTracker.shared.track("favorite", values: [
  "id": "P00003",
  "name": "ミネラルウォーター (500ml)",
  "price": 100
])

[[KarteTracker sharedTracker] track:@"favorite" values:@{
  @"id": @"P00003",
  @"name": @"ミネラルウォーター (500ml)",
  @"price": @100
}];

送信可能な値型について

各イベント送信メソッドには、カスタムオブジェクトと呼ばれるオブジェクト一緒に渡すことが可能です。
これにより、イベントに様々な値を紐づけて送信することが可能です。

なおカスタムオブジェクトには、任意の key や value を指定することが可能ですが、指定時の型には制限があります。

key として利用可能な型

NSString のみ利用可能です。
イベントで使用できないフィールド名も合わせてご確認ください。

value として利用可能な型

以下の型のみ利用可能です。
なお 日付型（NSDate）は内部で数値（NSNumber）に変換されます。

• NSDictionary
• NSArray
• NSNumber
• NSString
• NSDate
• NSNull

自動で付与されるフィールドについて

Identify以外のイベントでは、自動で端末や各種バージョン等の情報をSDKが自動で付与します。

特別な扱いが行われるフィールドについて

日時情報を送信するためのフィールド

日時情報を送信するためには、任意のイベントに、フィールド名の末尾が date となるフィールドを追加する必要があります（例：xxx_date）
このようにすることで、管理画面で日時情報を含むフィールドとして扱われ、日時（絶対時間・相対時間）を利用したセグメントやトリガーの設定が可能になります。

なおフィールドの値には、 NSDate または NSNumber 型の値を指定してください。

位置情報を送信するためのフィールド

位置情報を送信するためには、任意のイベントに、フィールド名の末尾が latlng となるフィールドを追加する必要があります（例：latlng / xxx_latlng）
このようにすることで、KARTE側で位置情報を含むフィールドとして扱われ、位置情報（マップ）を利用したセグメントやトリガーの設定が可能になります。

なおフィールドの値には、位置情報を配列（経度、緯度の順番）で指定してください。

📘

位置情報フィールドの値の指定方法について

配列の0番目には、経度 (longitude) を、1番目には 緯度 (latitude) を、それぞれ数値で指定する必要があります。
逆に指定した場合正しくセグメント・トリガーが機能しませんので、ご注意ください。

KarteTracker.shared.track("current_location", values: [
  "latlng": [139.7649361, 35.6812362]
])

[[KarteTracker sharedTracker] track:@"current_location" values:@{
  @"latlng": @[@139.7649361, @35.6812362]
}];

閲覧人数表示テンプレートを利用するために必要なフィールド

閲覧人数表示テンプレートを利用するためには Viewイベントに、 view_id フィールドを追加する必要があります。
view_id の値には、画面を一意に識別するための文字列を指定してください。

また 閲覧人数表示テンプレート については こちら のドキュメントも併せてご覧ください。

KarteTracker.shared.view("product", title: "商品詳細", values: [
  "view_id": "p123456789"
])

[[KarteTracker sharedTracker] view:@"product" title:@"商品詳細" values:@{
  @"view_id": @"p123456789"
}];

（参考）イベントの送信に関する仕様について

リクエストの仕組み

SDKではリクエスト数を削減する目的で、イベントを一時的にバッファリングする機構を備えております。
そのため、trackメソッドを呼び出した際、即座にイベントが送信される訳ではありません。

なお空の状態のバッファにイベントが蓄積されてから、500msec以内に発生したイベントについては1つのリクエストにまとめた上で送信する仕様となっております。

リクエストサイズの上限値

trackメソッドで送信する1リクエストのContent-Lengthの上限値は8,192byteです。
上限値を超えたリクエストに含まれるイベントは解析対象となりませんのでご注意ください。

イベントの再送について

イベント送信時の通信状況によりイベントの送信に失敗した場合でも、SDKではリトライを行いません。