APIの仕様について
b→dash mobile SDKのTracker APIについて、引数やプロパティに渡すことができるデータの上限値については以下をご参照ください。
API | 送信内容 | 上限値 |
Tracker.screenName | スマホアプリでアクセスした画面の名前 | 256 byte |
Tracker.relationalKey | データ統合のためのレコードを一意に特定するカラムの名前 | 128 byte |
Tracker.relationalValue | データ統合するためのレコードを一意に特定するカラムの値 | 256 byte |
Tracker.loginUser | ログインしたユーザーの名前 |
Key: 128 byte
value: 256 byte |
Tracker. setBootTypeWithValue() | スマホアプリの起動方法とその設定値 |
第1引数: 32 byte
第2引数: 512 byte |
Tracker.userMap | ユーザーがスマホアプリ内で到着した画面のURL |
格納できるキーバリューのペアは10個まで
(キー: 32 byte バリュー: 128 byte) ※10個を越えるデータを入れることはできす、サーバーに送信されるキーは順不同です。 |
Tracker.idfa | iOS端末における広告識別子 | 128 byte |
EventBuilder.eventLabel | 発生したイベントのラベル | 256 byte |
EventBuilder.eventCategory | 発生したイベントのカテゴリー | 256 byte |
EventBuilder. eventActionName | 発生したイベントの名前 | 256 byte |
EventBuilder.eventValue | 発生したイベントの値 | 256 byte |
EventBuilder.eventMap | イベントが発生した画面のURL |
格納できるキーバリューのペアは10個まで
(キー: 32 byte バリュー: 128 byte) ※10個を越えるデータを入れることはできず、サーバーに送信されるキーは順不同です。 |
ExceptionBuilder.crashName | 発生したエラーの名前 | 256 byte |
ExceptionBuilder.crashDescription | 発生したエラーの内容 | 1024 byte |
弊社では各項目の上限値に基づきテストしておりますので、上限を超えて設定される場合は貴社の自己責任にてご設定いただくようにお願いいたします。
トラッキング機能を提供するTrackerはスレッドセーフではありません。複数のスレッド(メインスレッド、ワーカースレッド)から同時に書き込む処理を行う場合、排他制御をする必要があります。
APIの組み込み
b→dash mobile SDKを用いてb→dashへログを送信するには、SDKが提供するAPIをスマホアプリに組み込む必要があります。
APIには「スマホアプリのログを非同期処理で送信するAPI」と「スマホアプリのログを同期処理で送信するAPI」に分けられます。送信するログごとにAPIを組み込んでいきます。
スマホアプリのログを非同期処理で送信する
b→dashのSDKは、取得したログを1件ずつb→dashに送信する同期処理ではなく、ログが10件蓄積されたタイミングでまとめて送信する非同期処理をベースとしています。
取得したログを1件ずつb→dashに送信した場合、b→dashとの通信回数が多くなりアプリのパフォーマンスに影響を与えてしまうため10件を閾値としています。
スクリーンログを送信する
スクリーンログを送信するにはScreenViewBuilderが必要になります。ScreenViewBuilderはスクリーンビューが単純に発生したときに、画面名を設定して成果を生成するクラスです。
以下の例では、WebVewイベントやライフサイクルイベント時に成果を取得するサンプルコードを紹介します。Webページが正常に表示されたとき、スクリーンビュー成果を送ってみましょう。
下記サンプルコードでは UIWebView 利用しておりますが、2020年時点より「WKWebView」が推奨されているため、読み替えての実装をお願いいたします。
func webViewDidFinishLoad(_ webView:UIWebView) -> void{
//計測イベント
//スクリーン名のセット
Tracker.getInstance().screenName = "Mainスクリーン";
//ログ出力
Tracker.getInstance().send(ScreenViewBuilder());
//計測イベント(ユーザーID, 外部キー含める)
//ログインユーザーIDをセットする
Tracker.getInstance().loginUserId = "ログインユーザーID";
//外部キーをセットする
Tracker.getInstance().relationalKey = "外部キー";
//外部値をセットする
Tracker.getInstance().relationalValue = "外部値";
//スクリーン名をセットする
Tracker.getInstance().screenName = "Mainスクリーン";
//ログ出力
Tracker.getInstance().send(ScreenViewBuilder())
}
-(void)webViewDidFinishLoad:(UIWebView*)webView{
//webview使用時例:web画面がロード終わった時にログを出力する。
//トラッカーのインスタンス取得
Tracker* tracker = [Tracker getInstance];
//スクリーン名をセットする。
tracker.screenName = @"web-画面A";
//イベントビルダーを生成する。
ScreenViewBuilder* screenViewBuilder = [[ScreenViewBuilder alloc]init];
//ログ出力
[tracker send:screenViewBuilder];
イベントログを送信する
イベントログを取得するにはEventBuilderが必要になります。EventBuilderはスマホアプリ内でイベントが単純に発生したときに、イベント内容を設定し成果を生成するクラスです。GUIを操作した際に実行するメソッドで成果を送信するサンプルコードを紹介します。
//省略
//インスタンスの取得
let tracker = Tracker.getInstance()
//ユーザー情報を設定する
let userDic = [ "sex":"男" ]
tracker.userMap = userDic as NSDictionary
//付加情報を追加する
tracker.screenName = "ネイティブ画面"
//イベントビルダーを生成する
let eventBuilder = EventBuilder()
//イベントビルダーの付加情報を追加する--start--
//アクション名を設定する
eventBuilder.eventActionName = "モーダル"
//イベント値を設定する
eventBuilder.eventValue = "イベント値"
//イベントカテゴリを設定する
eventBuilder.eventCategory = "初期表示"
//ラベルを設定する
eventBuilder.eventLabel = "初期表示"
//イベントプロパティを設定する
let eventMap = ["eventDefineKey1":"eventValue1" , "price":"100" , "eventDefineKey2":"eventValue2"]
eventBuilder.eventMap = eventMap as NSDictionary
//イベントビルダーの付加方法を追加する--end--
//ログを出力する
tracker.send(eventBuilder)
//ストーリーボード呼び出し
//省略
- (IBAction)actionEvent:(id)sender {
//トラッカーのインスタンス取得
Tracker* tracker = [Tracker getInstance];
//ユーザ情報を設定する。
NSDictionary *userDic = @{
@"sex": @"男"
};
tracker.userMap = userDic;
//付加情報を追加する。
tracker.screenName = @"ネイティブ画面";
//イベントビルダーを生成する。
EventBuilder* eventBuilder = [[EventBuilder alloc]init];
//イベントビルダーの付加情報を追加する。--start--
//アクション名を設定する。
eventBuilder.eventActionName = @"モーダル";
//イベント値を設定する。
eventBuilder.eventValue = @"イベント値";
//イベントカテゴリを設定する。
eventBuilder.eventCategory = @"画面遷移";
//ラベルを設定する。
eventBuilder.eventLabel = @"初期表示";
//イベントプロパティを設定する。
NSDictionary *eventMap = @{@"eventDefineKey1": @"eventValue1",@"price": @"100",
@"eventDefineKey2": @"eventValue2"};
eventBuilder.eventMap = eventMap;
//イベントビルダーの付加情報を追加する。--end--
//ログ出力する。
[tracker send:eventBuilder];
//ストーリーボード呼び出し
//省略 〜
エラーログを送信する
エラーログを送信するにはExceptionBuilderが必要になります。ExceptionBuilderはアプリ内で、軽微・致命的問わず、クラッシュが発生したときの情報を、追加して成果を生成するクラスです。例外が発生したことを検知したい箇所で実装します。
//省略
let str = ""
/* 常に実行される */
do{
//範囲外の例外(NSRangeException)を起こす
throw NSError(domain: "errorメッセージ", code: -1, userInfo: nil)
}catch let error as NSError{
/*本来の例外処理に投げる。(throwしなければクラッシュされない。
finallyが実行されstrは元の1234の値のまま)*/
/*ExceptionBuilderの使い道としては、try,catch等の例外、エラーのハンドリングが
行われる箇所に挿入することを想定している。*/
//トラッカーのインスタンス取得
let tracker = Tracker.getInstance()
//付加情報を追加する
tracker.screenName = "ネイティブA画面"
//イベントビルダーを生成する
let exceptionBuilder = ExceptionBuilder()
//イベントビルダーの付加情報を追加する--start--
//クラッシュ内容
exceptionBuilder.crashDescription = "n (error)"
//致命的か否か
exceptionBuilder.crashFatal = true
//クラッシュネーム
exceptionBuilder.crashName= "範囲例外"
//イベントビルダーの付加情報を追加する--end--
//ログ出力する
tracker.send(exceptionBuilder)
//必要であれば例外throwを行う
//省略
//省略
NSMutableString *str = [@"01234" mutableCopy];
/* 常に実行される */
@try {
// 範囲外の例外(NSRangeException)を起こす
[str replaceCharactersInRange:NSMakeRange(0, 6) withString:@"x"];
}
/* 例外が起きると実行される */
@catch (NSException *exception) {
/* 本来の例外処理に投げる (@throwしなければクラッシュされない。@finallyが実行されstrは元の@"01234"の値のまま) */
//ExceptionBuilderの使いみちとしては、try,catch等の例外、エラーのハンドリングが行われる箇所に挿入することを想定している。
//トラッカーのインスタンス取得
Tracker* tracker = [Tracker getInstance];
//付加情報を追加する。
tracker.screenName = @"ネイティブA画面";
//イベントビルダーを生成する。
ExceptionBuilder* exceptionBuilder = [[ExceptionBuilder alloc]init];
//イベントビルダーの付加情報を追加する。--start--
//クラッシュ内容
exceptionBuilder.crashDescription = exception.description;
//致命的か否か
exceptionBuilder.crashFatal = true;
//クラッシュネーム
exceptionBuilder.crashName = @"範囲例外";
//イベントビルダーの付加情報を追加する。--end--
//ログ出力する。
[tracker send:exceptionBuilder];
@throw exception;
//省略
起動タイプログを送信する
ExceptionBuilderでは起動タイプログを送信することもできます。外部起動(スキーマ/Push通知起動) などで、通常と異なる「アプリ起動時のイベント」を集計することができます。
アプリ独自のurlスキーマで外部からアプリを起動された時の例:
func application(application: UIApplication, openURL url: URL, sourceApplication: String?, annotation: AnyObject) -> Bool {
let tracker = Tracker.getInstance()
tracker.screenName = "初回画面"
//固定値:BOOT_SCHEMAとurlオブジェクトを
//setBootTypeWithValueメソッドに追加する
tracker.setBootTypeWithValue(Tracker.BOOT_SCHEMA, value:url)
let event = ExceptionBuilder()
tracker.send(event)
return true
}
アプリ独自のurlスキーマで外部からアプリを起動された時の例:
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
Tracker* tracker = [Tracker getInstance];
tracker.screenName = @"初期画面";
//固定値:BOOT_SCHEMAとurlオブジェクトを
// setBootTypeWithValueメソッドに追加する。
[tracker setBootTypeWithValue:Tracker.BOOT_SCHEMA value:url];
EventBuilder * event = [[EventBuilder alloc ] init];
[tracker send:event];
return YES;
IDFAを送信する
アプリケーション内でIDFAをすでに利用している場合で、広告などに利用されたい場合、IDFAを送信することで連携することができます。
// 省略
let tracker = Tracker.getInstance()
//IDFA紐付ける
tracker.idfa = "idfa"
let screenViewBuilder = ScreenViewBuilder()
tracker.send(screenViewBuilder)// ログ出力する
// 省略
// 省略
Tracker* tracker = [Tracker getInstance];
//IDFAを紐付ける
tracker.idfa= @"idfa";
ScreenViewBuilder* screenViewBuilder = [[ScreenViewBuilder alloc]init];
[tracker send:screenViewBuilder]; //ログ出力する。
// 省略
App Tracking Transparenvy(通称ATT) ダイアログを表示して、エンドユーザーに承諾を得ない限りIDFAを取得することができなくなります。
SDK側では IDFA を取得しておりませんのでSDKのアップデートは必要ありません。ご利用アプリ側での対応が必要となります。
会員IDなどの情報を紐付ける
b→dash SDKでは、独自の「会員ID」など貴社サービスで管理しているIDを紐付けることができます。
// 省略
let tracker = Tracker.getInstance()
//会員IDを紐づける
tracker.loginUserId = "loginId"
let screenViewBuilder = ScreenViewBuilder()
tracker.send(screenViewBuilder) //ログ出力する
// 省略
// 省略
Tracker* tracker = [Tracker getInstance];
//会員IDを紐付ける
tracker.loginUserId= @"loginId";
ScreenViewBuilder* screenViewBuilder = [[ScreenViewBuilder alloc]init];
[tracker send:screenViewBuilder]; //ログ出力する。
// 省略
スマホアプリのログを同期処理で送信する
ログが10件蓄積されたタイミングでまとめて送信する非同期処理ではなく、同期処理で取得したログを1件ずつb→dashに送信します。
未送信ログを送信する
未送信データの蓄積を防ぐために、Tracker.syncを使ってアプリ起動時に既に発生している「イベント成果」を送信する必要があります。下記の例ではアプリケーション起動時に組み込んでます。
func application(_ application: UIApplication, didFinishLaunchingWithOptions
launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
/*
トラッカーのインスタンス取得(UUIDを使用したい場合は
インスタンス生成時にuuidを引数に渡します。
*/
let tracker = Tracker.getInstance("UUID-XXXXX-XXXXX-XXXXX")
/*
syncメソッドをアプリケーション呼び出し時に呼び出す。
端末に保持してるトラッキング情報を一旦空にする。
*/
tracker.sync()
return true
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//トラッカーのインスタンス取得(UUIDを使用したい場合はインスタンス生成時にuuidを引数に渡します。
Tracker* tracker = [Tracker getInstance:@"UUID-XXXXX-XXXXXX-XXXXX"];
//syncメソッドをアプリケーション呼び出し時に呼び出す。端末に保持してるトラッキング情報を一旦空にする。
[tracker sync];
return YES;
}
WebViewの呼び出しについて
SDK 独自のURLパラメーターに値を設定することで、集計データなどが詳細に集計されたページ表示ができます。
パラメーター名 | iOSバリュー | 役割 |
_bdld | Tracker.visitorId | セッション判定が正しく集計される |
- パラメーターを付与することで、WebViewのコンテンツ上においても同一ユーザーとして識別することが可能となります。
- 本パラメーターは同一ドメイン内でのみ有効となる為、異なるドメインにアクセスする場合、再度付与する必要があります。
以下はWebViewでページを表示するときのサンプルコードです。
//viewDidAppear
//・View の表示が完了後に呼び出されるメソッド
//下記例では、webViewをロードしてます。
override func viewDidAppear(_ animated: Bool){
let webConfiguration = WKWebViewConfiguration()
webView = WKWebView(frame: rect, configuration: webConfiguration)
//WebViewで表示するURLを””の中に挿入
let webUrl = URL(string: " http://接続先?_bdld=%@(Tracker.getInstance().visitorId)")!
let myRequest = URLRequest(url: webUrl)
webView.load(myRequest)
// インスタンスをビューに追加する
self.view.addSubview(webView)
}
//viewDidAppear
//・View の表示が完了後に呼び出されるメソッド
//下記例では、webViewをロードしてます。
-(void)viewDidAppear:(BOOL)animated{
//webViewをロードする際、パラメーターに _bdldを渡すことで、セッションが厳密に測定されるようになります。
NSString *webUrl = [NSString stringWithFormat:@"http://接続先?_bdld=%@",[Tracker getInstance].visitorId];
NSURL *url = [NSURL URLWithString:webUrl];
NSURLRequest *req = [NSURLRequest requestWithURL:url];
[self.webView loadRequest:req];
}