MOBYLOG SDK - 株式会社セラン | CELLANT Corporation.

MOBYLOG SDK
for iOS
インストール設定マニュアル
version 2.11
MOBYLOG SDK for iOS インストール 設定 マニュアル
CONFIDENTIAL
改訂履歴
改訂日
Ver
改訂内容
改訂者
2011/01/11
1.00
MOBYLOG SDK for iOS リリース
株式会社セラン
2011/07/11
2.00
アプリダウンロード計測に対応。
株式会社セラン
SDK バージョン：2.0
2011/09/20
2.01
ROI 計測について追記
株式会社セラン
2011/10/05
2.02
SDK のログ通知に関して注意書きを追加
株式会社セラン
2011/10/18
2.03
ビーコン通知の SSL 対応
株式会社セラン
2011/12/14
2.10
オフライン計測に対応。
株式会社セラン
SDK バージョン：2.1
2012/05/28
2.11
SDK_DEFAULT_OPTIN 設定項目を追加。
株式会社セラン
これに伴い、ビーコン通知の記述方法を変更。
（初期化コードが必要となった）
イベント計測用のパラメタについて追記。
2
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
MOBYLOG SDK for iOS インストール 設定 マニュアル
CONFIDENTIAL
はじめに
この MOBYLOG SDK for iOS インストール設定マニュアル（以下『本説明書』）は、iPhone / iPad アプリケーション（以
下『アプリ』）計測用の SDK「MOBYLOG SDK for iOS（以下『MOBLOG SDK』）」のインストール設定マニュアルです。
本説明書に沿ってインストールおよび設定を行うことで、アプリのアクセス解析を『MOBYLOG』で計測することができ
ます。
著作権について
本説明書の文章・写真・イラスト・動画・プログラム等（以下コンテンツという）の著作権等は、弊社に帰属します。著
作権法が定める場合を除いて、著作権者の許諾なくコンテンツを複製、変造、第三者への貸与、配布等いかなる目
的にも利用することはできません。
免責事項
本説明書で提供している各種情報につきましては、お客さまに不測の損害・不利益等が発生しないよう適切に努力
し、最新かつ正確な情報を掲載するよう注意を払っておりますが、その内容の完全性、正確性、有用性等について
保証をするものではありません。したがいまして弊社は、お客さまが当該情報に基づいて起こされた行動によって生
じた損害・不利益等に対していかなる責任も負いません。
3
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
MOBYLOG SDK for iOS インストール 設定 マニュアル
CONFIDENTIAL
INDEX
１．MOBYLOG SDK について .......................................................................................................... 6
１．１．計測開始までの流れ ..................................................................................................................................... 6
１．２．MOBYLOG SDK の仕様 ............................................................................................................................... 6
１．２．１．通信方式 ............................................................................................................................................................................. 6
１．２．２．ユニークキーの生成ルール ........................................................................................................................................ 7
１．２．３．ログ送信情報 .................................................................................................................................................................... 7
１．２．４．MOGYLOG SDK のシステム要件 ............................................................................................................................. 8
１．３．MOBYLOG SDK を使った計測の概要 .................................................................................................... 8
１．３．１．MOBYLOG SDK 利用者側で決定すること ............................................................................................................ 8
１．３．２．利用できる管理画面の機能 ........................................................................................................................................ 8
２．MOBYLOG SDK の導入手順 .................................................................................................. 10
２．１．MOBYLOG SDK のダウンロード .............................................................................................................10
２．２．プロジェクトへ追加 ........................................................................................................................................10
２．３．ライブラリの追加............................................................................................................................................11
３．MOBYLOG SDK の設定............................................................................................................ 13
３．１．設定項目一覧 .................................................................................................................................................13
３．２．設定項目内容 .................................................................................................................................................13
４．ビーコン通知タグの記述 ........................................................................................................... 19
４．１．基本的な使い方 .............................................................................................................................................19
４．２．アプリダウンロード計測の実装方法......................................................................................................20
４．２．１．UIApplicationDelegate メソッドの追加 .................................................................................................................. 20
４．２．２．コンバージョン計測ページ URL の設定 .............................................................................................................. 22
４．２．３．URL Type の追加 ......................................................................................................................................................... 22
４．３．コンバージョン属性情報の設定 ..............................................................................................................23
４．３．１．ビーコン通知タグ拡張 ................................................................................................................................................ 24
４．３．２．属性データの計測方法 .............................................................................................................................................. 24
４．３．３．コンバージョン属性取得の注意事項 .................................................................................................................... 25
４．４．ROI の計測.......................................................................................................................................................25
４．４．１．月額課金用の ROI タグ設定 .................................................................................................................................... 25
４．４．２．従量課金用の ROI タグ設定 .................................................................................................................................... 26
４．５．イベント通知 ....................................................................................................................................................27
４．６．ビーコン通知パーミッションの管理 ........................................................................................................27
４．７．動作確認 ...........................................................................................................................................................28
５．トラブルシューティング ............................................................................................................... 29
５．１．ビルド時にリンクエラー ...............................................................................................................................29
５．２．その他のエラー ..............................................................................................................................................29
4
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
MOBYLOG SDK for iOS インストール 設定 マニュアル
CONFIDENTIAL
６．MOBYLOG SDK のビーコン通知停止について .............................................................. 30
７．MOBYLOG SDK の制約............................................................................................................ 30
5
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
１．MOBYLOG SDK について
MOBYLOG SDK はアプリから MOBYLOG サーバへビーコン通知するための API を提供します。
ビーコン通知とは HTTP リクエストを MOBYLOG サーバの所定の URL へ送信することを指します。
MOBYLOG サーバはビーコン通知を受信してログ解析に必要な集計処理を行います。アプリ開発者
は MOBYLOG SDK を Xcode プロジェクトへ組み込んで必要なコードを記述することで MOBYLOG
サーバへビーコン通知を行うことができます。
１．１．計測開始までの流れ
MOBYLOG SDK を利用して計測を行うまでの流れは以下の通りです。
No
内容
説明
1
MOBYLOG SDK の取得
Download Center から MOBYLOG SDK をダウンロードします。
2
プロジェクトへ追加
MOBYLOG SDK を Xcode のプロジェクトに追加します。
3
設定ファイルの編集
beacon.plist に計測に必要な情報を設定します。
4
ビーコン通知タグの記述
プログラム内にビーコン通知用のタグを記述します。
１．２．MOBYLOG SDK の仕様
１．２．１．通信方式
MOBYLOG SDK は、オンライン状態（3G 回線もしくは Wi-Fi のうち利用可能なネットワーク）を検出し、ログ受付
サーバに対して POST リクエストでログを送信します。オフライン時（どちらのネットワークも利用できない場合、
もしくはログ送信が失敗した場合）はログ情報をアプリ内のキューに蓄積し、オンライン状態になった場合にオフ
ラインログとして 10 件ずつログ送信を実行します。尚、通信は非同期で行われます。
技術メモ
ビーコン通知に利用する API
3G 回線/Wi-Fi のどの方法で接続可能かどうかのチェックにシ
ステム提供の API を利用。
システム API のタイムアウト時間
60 秒（実測値） この値は変更不可。尚、非同期で通信しているためアプリが落
ちることはない。 HTTP リクエストのタイムアウト時間
10 秒 ログ受付サーバが応答しない場合のタイムアウト時間。 非同期で通信しているため、アプリが落ちることはない。 6
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
１．２．２．ユニークキーの生成ルール
ユニークを識別するためのユニークキーの生成ルールとして、MOBYLOG SDK では２つの方法を提供していま
す。生成ルールの決定は beacon.plist の「SDK_UID_RULE」で行います。詳しくは「３．設定ファイルの編集」をご
覧下さい。
１．２．３．ログ送信情報
MOBYLOG SDK によってログ受付サーバ上に蓄積される情報
項目名
説明
備考
サイト ID
設定ファイルに指定したサイト ID
契約時に事務局から発行された ID を設定
(ktr_site)
する。
セッション ID
生成されたユニークキー
(ktr_sid)
ユニークキーの生成ルールに基づいて生
成されたユニークキー
端末識別番号
生成されたユニークキー
（ktr_uid）
ユニークキーの生成ルールに基づいて生
成されたユニークキー
ページ
メソッドをコールしたページを識別す
（ktr_url）
る文字列。
通信状況
通信状況の値。
(__trans)
0 : オフライン / 1: Wi-Fi / 2 : デー
Xcode 内で任意に指定する。
SDK 側で自動的に状況を取得した値。
タ通信
アプリのバージョン番号
SDK 側で設定ファイルから取得した値
操作日時
アプリを操作した日時
アプリが操作された日時。
(__timestamp)
yyyy-mm-dd hh24:mi:ss.msc+HI:MM
許諾フラグ
ビーコン通知の許諾フラグ
(__optflg)
0 : 拒否 / 1 : 許可
位置情報
緯度経度情報
現行バージョンでは利用しない。
ユーザーの利用言語情報
現行バージョンでは利用しない。
イベント計測用のパラメタ
Xcode 内で任意に指定する。
設定した拡張パラメタ
任意に指定したパラメタ。
アプリバージョン
(__appver)
ビーコン通知の許諾フラグ
( lat / lon )
言語情報
(lang)
イベント情報
(ktr_ev/ktr_evct/event)
その他
コンバージョン属性機能を利用する場合に
必要となる。
CAUTION
MOBYLOG SDK が組み込まれたアプリで且つビーコン通知のメソッドが呼ばれた時のみログ情報を通知します。
通常のビーコン通知は、個人情報に該当する情報を通知することはありませんが、アプリ開発者側で、拡張パラメタに
個人情報を含んだ値を設定した場合は MOBYLOG にその情報が通知されログ情報として記録されます。
7
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
１．２．４．MOGYLOG SDK のシステム要件
MOBYLOG SDK のシステム要件は以下の通りです。（2012 年 05 月現在）
開発環境
iOS 4.2 以上 / SDK 4.2 以上 / Xcode 4 以上
iPhone / iPad
iOS 4.0 以上
3G 回線もしくは Wi-Fi によるネットワークが利用可能なこと。
１．３．MOBYLOG SDK を使った計測の概要
MOBYLOG SDK を利用したアプリのアクセス解析は、Web サイトのページの計測とは構造的な違いがあります。
ここでは、MOBYLOG SDK を利用する際に決定すること、およびアプリ解析を行った場合に利用できる管理画
面の機能を説明します。
１．３．１．MOBYLOG SDK 利用者側で決定すること
ページ遷移が発生する Web サイトとは異なり、アプリは HTML ページを含んでいないため、ページビューとして
計測されるリクエストを「いつ」「どれくらい」「どの URL（ページ名）として」発生させるかを事前に決定する必要が
あります。
MOBYLOG SDK は、任意のポイントで呼び出すことができるため、例えばアプリを起動した時や、画面上をタッ
プした時など、画面遷移が伴わない操作でも計測することができます。
まずは解析を必要とするポイントの洗い出しと、MOBYLOG 上で URL として計測される文字列を決定してくださ
い。
１．３．２．利用できる管理画面の機能
アプリケーションの計測は、「Application」モードのレポート画面で確認することができます。
機能グループ
メニュー
パフォーマンス
サマリー
備考
ポートフォリオ
ユーザー
トレンド
タグを設定した計測ポイントの集計
デバイス
通信環境
アプリバージョン
コンテンツ
ページ
ダウンロード
サイト内検索
アプリ内で検索機能があり、検索キーワードを通知する
8
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
ようにタグを設置すれば可能。
イベント
行動分析
イベント計測用のパラメタを通知することで計測可能。
指定ページ
進入ページ
離脱ページ
シナリオ分析
効果測定
直接効果
リスティング
コンバージョン
ROI（β版）
ROI 測定ガイドラインに沿った設定が必要。
成果ページ
キャンペーン
メディア
間接効果
9
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
２．MOBYLOG SDK の導入手順
MOBYLOG SDK を利用するための手順を以下に説明します。開発ツールには Xcode4 を利用していま
す。
２．１．MOBYLOG SDK のダウンロード
ログイン後の Download Center から、「MOBYLOG SDK for iOS」をダウンロードします。
ダウンロードした ZIP ファイルを解凍すると、以下のフォルダとファイルが作成されます。
２．２．プロジェクトへ追加
ダウンロードしたファイルや必要なフレームワークを Xcode のプロジェクトへ追加します。
①フレームワークフォルダを Frameworks グループへ追
加します。
先ほど解凍してできた
MLBeacon.framework
フォルダ
を Xcode の Frameworks へドラッグ＆ドロップします。
②ドロップするとダイアログが表示されます。
Distination✓（チェック）をつけて「Finish」ボタンを押しま
す。
10
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
③これで MLBeacon.framework が Xcode のプロジェクトに
追加されます。
④ 続いて設定ファイル「beacon.plist」をプロジェクトへ追加し
ます。同様にファイルをドラッグ＆ドロップしてください。ドロ
ップ先は
Supporting Files
とします。
２．３．ライブラリの追加
以下のライブラリを追加します。
1
SystemConfiguration.framework
2
libsqlite3.0.dylib
3
CoreLocation.framework
①まず Xcode で開発しているターゲットを開き、 Build Phases
を選択します。
11
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
② Link Binary With Libraries
の内容を表示し、すぐ下の「＋」ボタンを押します。
ラ イ ブ ラ リ の 一 覧 が 表 示 さ れ る の で
SystemConfiguration.framework 、 libsqlite3.0.dylib 、
CoreLocation.Framework を選択します。
③選択後は以下のようになります。
12
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
３．MOBYLOG SDK の設定
MOBYLOG SDK の 各 種 設 定 項 目 と設 定 例 を説 明 します。MOBYLOG SDK の 設 定 は 、設 定 ファイル
「beacon.plist」で行います。beacon.plist を開くと、初期状態では以下の設定がされています。
３．１．設定項目一覧
■beacon.plist の設定項目一覧を以下に記します。
No
項目
説明
備考
1
SDK_SITE_ID
事務局から発行されたサイト ID
例）000100
2
SDK_LICENSE_KEY
事務局から発行されたライセンスキー
40 桁のライセンスキー
3
SDK_BEACON_URL
ログ受付サーバの URL
基本的には編集しない
4
SDK_UID_RULE
ユニークキーの生成ルールを決定
0 or 1 で指定
5
SDK_LOC_INFO
位置情報送信フラグ
0 or 1 で指定
6
SDK_OFFLINE_LOG
オフラインログの蓄積件数
0 ‒ 5000 で指定
7
SDK_CONVERSION_URL
アプリダウンロード計測で使用
8
SDK_DEFAULT_OPTIN
ビーコン通知のユーザー許諾設定
0 or 1 で指定
9
SDK_DEBUG
デバッグモード
YES or NO
SDK_ENGINE_VERSION
SDK のメジャーバージョン
2 固定
10
３．２．設定項目内容
MOBYLOG SDK の各種設定方法と設定例を説明します。
1. SDK_SITE_ID
MOBYLOG を利用するサイトを識別するための ID です。
MOBYLOG SDK 配布時には設定されていませんので、事務局から発行されたサイト ID を設定します。
CAUTION
この値を間違えて設定すると正確にアクセス解析ができなくなります。
13
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
2. SDK_LICENSE_KEY
事務局から発行されたライセンスキーを設定します。
LICENSE_KEY に仮ライセンスキーを設定している場合、MOBYLOG SDK はトライアル期間が経過するとビ
ーコン通知を停止するため、トライアル用の仮ライセンスキーを設定したまま AppStore で配信しないで下
さい。
CAUTION
この値を間違えて設定すると正確にアクセス解析ができなくなります。
尚、ライセンスキーのステータスはデバッガコンソールで確認することができます。
本ライセンスキー有効
SDK/2.0 [INFO ] Beacon is loaded successfully
仮ライセンスキー有効
SDK/2.0 [INFO ] Beacon is loaded successfully (using trial key, until 2030-01-31
15:00:00 +0000)
仮ライセンスキー期限切れ
SDK/2.0 [ERROR] The trial license key has been expired at 2010-12-31 15:00:00 +0000,
Please confirm SITE_ID and LICENSE_KEY.
ライセンスキー無効
SDK/2.0 [ERROR] The license key is invalid, Please confirm SITE_ID and LICENSE_KEY.
3. SDK_BEACON_URL
ログ受付サーバの URL です。
MOBYLOG SDK 配布時は以下の URL が設定されています。
Key
Type
Value
SDK_BEACON_URL
String
https://log1.mobylog.jp/al.php
CAUTION
① この値は変更しないで下さい。この値を変更すると正確にアクセス解析ができなくなります。
② ライセンス版をお使いの場合は、自社のログ受付サーバの URL を指定して下さい。
4. SDK_UID_RULE
MOBYLOG SDK が利用するユニークキーの生成ルールを決定します。
Key
Type
Value
SDK_UID_RULE
Number
0 or 1
CAUTION
① beacon.plist に SDK_UID_RULE がない場合や 0 と 1 以外の場合、UID_RULE=0 の動作となります。
② SDK_UID_RULE=0 で一旦アプリを動作した後、UID_RULE=1 に切り替えた場合、ktr_uid は SDK_UID_RULE=1 の
生成ルールが適用されます。アプリケーションの plist に SDK_UID_RULE=0 の時の値が保管されたままになり
ますが、これは利用しません。
③ アプリダウンロード計測で MOBYLOG SDK を利用している場合、HandloaD TAG 側で発行された cookie の値に
書き換えることができます。
書き換えが行われた場合、SDK_UID_RULE で生成されたユニークキーは利用されなくなります。
14
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
値
説明
0
独自発行のユニークキーを生成します。
1
mac アドレスと定数を組み合わせたユニークキーを生成します。
0
独自発行のユニークキー
UID_RULE=0 の場合、インストール後初回起動時に以下のルールに従い、その端末を一意に識別で
きるランダムなキーを生成し、その値をアプリケーションの「plist」へ保管します。
ユニークキーの生成ルール
MD5（乱数値）
このユニークキーは NSUserDefaults を使用してアプリケーションの設定ファイルに追加され、以後は
このキーがログ受付サーバへ送信されます。キーは
MOBYLOG_BEACON_UID
を使います。キー
名は MLBeaconManager.h で定義されています。
ユニークキーは UDID 等のデバイスの固有番号とは紐づきません。よって、一旦アプリを削除後、再
度インストールすると、同じ端末でも別のユニークキーとなりますので注意が必要です。
ただし、アプリを削除しなければ、一旦発行されたユニークキーは変更されることがなく、同じユーザ
として認識されます。
1
MAC アドレスと定数を組み合わせた ユニークキー
UID_RULE=1 の場合、以下のルールに従い、UDID を利用した値を利用します。アプリケーションの
plist は使いません。
ユニークキーの生成ルール
CAUTION
MD5（MAC アドレス + 定数）
MAC アドレスは個人情報となる可能性が高いため、定数を組み合わせてユニークキーとしています。
定数値は非公開です。
ユニークキーは mac アドレスを利用しているため、一旦アプリを削除後、再度インストールしても、同
じ端末である場合は同じユニークキーとなります。
5. SDK_LOC_INFO
位置情報を計測するための設定です。
Key
Type
Value
SDK_UID_RULE
Number
0 or 1
CAUTION
① 初期設定では「0」が設定されています。
15
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
値
説明
0
位置情報を送信しない
1
位置情報を送信する
位置情報送信設定をすると、位置情報を利用しないアプリでも位置情報（緯度経度）を iOS の API から取
得し、ログ通知を実行します。
iOS の場合、位置情報を取得する API をリクエストすると、端末側で位置情報取得のダイアログ（パーミッ
ション）が表示されます。アプリを利用しているユーザが「いいえ」を選択すると、送信フラグを「1」に設定し
ていても、位置情報が計測できませんのでご注意ください。
6. SDK_OFFLINE_LOG
オフライン時の操作ログを蓄積する件数を設定します。
Key
Type
Value
SDK_UID_RULE
Number
0 ‒ 5000
CAUTION
① 初期設定では「5000」が設定されています。
② 5000 以上を設定した場合でも、オフラインログの蓄積は 5000 件を上限として扱います。
③ 0 を指定した場合はオフラインログを蓄積しません。
③ 上限に達した場合は古いオフラインログから上書きされます。
値
説明
0
オフラインログを計測しない
1 以上
オフラインログを計測する
オフラインログを計測する設定にした場合、オフライン時のアプリ操作ログを SDK が扱うアプリ内 DB に蓄
積します。
オフラインログが蓄積されている場合、オンライン時で且つアプリが起動されている時に、10 件ずつ POST
でログデータを送出します。
送出されたオフラインログは、オフラインログのフラグが付いた形で MOBYLOG に送出されますが、
MOBYLOG レポート画面では過去に遡って集計されることはありません。「ユーザ -> 通信環境」メニュー
からオフラインで利用されたセッション数としてのみ計測されます。
7. SDK_CONVERSION_URL
アプリダウンロード計測を実施する場合に、アプリ初回起動時に遷移させるコンバージョン計測ページの
URL を指定します。
例）
Key
Type
Value
SDK_CONVERSION_URL
String
http://foo.jp/welcome/conversion.php
詳しくは「４．２．アプリダウンロード計測の実装方法」をご覧ください。
16
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
8. SDK_DEFAULT_OPTIN
アプリ側で、ユーザーに対するビーコン通知のパーミッション状態を管理する設定です。
Key
Type
Value
SDK_DEFAULT_OPTIN
Number
0 or 1
CAUTION
① 初期設定では「1:拒否」が設定されています。ビーコン通知のパーミッションをアプリ側で実装する場合は、必ず
0 を設定してください。
② 0/1 以外を設定した場合、0 とみなします。
値
説明
0
拒否（ビーコン通知しない）
1
許可（ビーコン通知する）
CAUTION
① 初期設定では「1:拒否」が設定されています。ビーコン通知のパーミッションをアプリ側で実装する場合は、必ず
0 を設定してください。
② 0/1 以外を設定した場合、0 とみなします。
尚、SDK では設定値をアプリ側から変更できるメソッドを用意しています。
詳しくは「４．５．ビーコン通知パーミッションの管理」をご覧ください。
9. SDK_DEBUG
DEBUG 設定項目にチェックを付けるとビーコン通知内容をデバッグコンソールで確認することができます。
例）
2011-05-20 11:59:27.559 Test [33227:207] SDK/2.0 [INFO ] Debug mode: on
2011-05-20 11:59:27.635 Test [33227:207] SDK/2.0 [INFO ] Beacon is loaded
successfully
2011-05-20 11:59:27.775 Test [33227:207] SDK/2.0 [INFO ] Connection mode changed:
WiFi
2011-05-20 11:59:27.776 Test [33227:207] SDK/2.0 [DEBUG] Background thread is
starting
2011-05-20 11:59:30.111 Test [33227:5f07] SDK/2.0 [DEBUG] did send request (sync). 10. SDK_ENGINE_VERSION
MOBYLOG SDK の動作を制御するための設定で、MOBYLOG SDK 配布時には「2」が指定されています。
この値は変更せずにご利用ください。変更すると正確に解析ができなくなります。
17
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
MOBYLOG SDK for iOS インストール 設定 マニュアル
CONFIDENTIAL
18
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
４．ビーコン通知タグの記述
MOBYLOG SDK の導入が完了しましたら、プログラム内にビーコン通知タグを設置します。
基本的に任意のポイントでビーコン通知タグを使ってビーコン通知をすることができます。
４．１．基本的な使い方
ここでは例として UIViewController が表示されたタイミングでビーコンを通知するコード（タグ）を取り上げて説明
します。
① ヘ ッダ の インポ ー ト
MLBeacon クラスを使用するファイル毎に下記の１行を追加します。
# import <MLBeacon/MLBeacon.h>
② 初 期 化 コー ドを 追 加
起動時に呼び出されるアプリケーションデリゲートに初期化の為のコードを追加します。
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
:
[MLBeacon setup];
// 初期化コード
:
③ ビー コン通 知 タグ を記 述
ビーコン通知したい箇所（画面表示、ボタンタップ時など）にビーコン通知コードを追加します。
[MLBeacon sendWithScreen:@”TopPage” parameters:nil];
この例では、MOBYLOG で集計されるページ URL として「TopPage」を指定しています。
④ ビル ド＆ 実 行
MOBYLOG SDK の組み込みに成功するとビーコン発信の初回に
SDK / <バージョン番号> [INFO]
Beacon is loaded successfully というメッセージがデバッグコンソールに実行毎初回のみ表示されます。
メッセージの例）
2010-12-24 14:22:56.781 <アプリ名称> [67124:207] SDK / <SDK バージョン番号>
[INFO] Beacon is loaded successfully
19
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
beacon.plist に設定した内容が正しくない場合はエラーメッセージが表示されます。
（詳しくは「トラブルシューティング」の章を参照下さい）
４．２．アプリダウンロード計測の実装方法
MOBYLOG SDK を利用してアプリダウンロード計測を行うと、ブラウザ側で HandloaD TAG により発行された
cookie の値をアプリ計測で利用するセッションとして利用することができます。これにより、クリック→コンバージ
ョン→アプリ内の解析を同じユーザとして繋げて計測することが可能となります。
MOBYLOG SDK のセッション置換概要図
MOBYLOG SDK は、初回起動時にコンバージョン計測ページへ遷移する際に SDK_UID_RULE に則ったユニーク
キーを発行し、key パラメタに格納して GET リクエストします。Welcome ページからブラウザ側で通知されたセッ
ション（ktr_sid）と key をアプリに渡します。MOBYLOG SDK は、初回発行した key パラメタと Welcome ページから
渡された key パラメタを比較し、値に違いがなければアプリ解析に利用するセッションを ktr_sid に置換してビーコ
ン通知を実行します。
この処理を行う場合、専用の設定とコードの追加が必要となります。
４．２．１．UIApplicationDelegate メソッドの追加
アプリケーションのデリゲートファイルに UIApplicationDelegate で定義されている下記２つのメソッドを修正しま
す。
20
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
- (BOOL)application:(UIApplication*)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions;
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
もしデリゲートファイルに上記メソッドが存在しない場合は追加してください。
これらのメソッド内に MLBeacon のメソッド呼び出しコードを追加します。
#import <MLBeacon/MLBeacon.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary
*)launchOptions {
[MLBeacon redirectToConversionURL]; ← 追加
:
return YES;
}
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
{
[MLBeacon handleOpenURL:url];
← 追加
:
return YES;
}
アプリケーションはダウンロード後の初回起動時に、ブラウザを起動し後述するコンバージョン URL を表示しま
す。２回目以降に起動した場合はブラウザを起動しません。
■非バックグラウンド動作のアプリケーションの場合の注意事項
バックグラウンド動作を行わないアプリケーション（UIApplicationExitsOnSuspend が YES のケース）でアプリダウ
ンロード計測を行う場合、-application:didFinishLaunchingWithOptions: メソッド内の記述を下記のようにします。
#import <MLBeacon/MLBeacon.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary
*)launchOptions {
追加ここから→
NSURL* url = [launchOptions objectForKey:UIApplicationLaunchOptionsURLKey];
if (url) {
[MLBeacon handleOpenURL:url];
} else {
if ([MLBeacon redirectToConversionURL]) {
return NO;
21
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
MOBYLOG SDK for iOS インストール 設定 マニュアル
CONFIDENTIAL
}
}
← 追加ここまで
:
return YES;
}
+redirectToConversionURL の戻り値は、コンバージョン URL を呼び出した場合は YES、そうでなければ NO と
なります。なおこの場合、-application:HandleURL: への追加は不要です。
４．２．２．コンバージョン計測ページ URL の設定
beacon.plist に、「アプリダウンロード計測ガイドライン」に従って用意したコンバージョン計測ページの URL を設
定します。
設定例）
CAUTION
SDK_CONVERSION_URL 設定項目に URL が設定されていない場合、UIApplicationDelegate でコードを追加してもコンバ
ージョン計測ページへ遷移はしません。
ここに指定されている URL に対して、key パラメタを GET リクエストします。
４．２．３．URL Type の追加
①
Xcode のターゲット設定画面を開きます。
22
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
②
「Info」タグを開いた状態で右下の「Add」ボタンから「Add URL Type」を選択します。
③
「Identifer」および「URL Schemes」に Info タブ内の「Bundle Identifier」と同じ値を設定します。
例えば「Bundle Identifier」が
jp.cellant.${PRODUCT_NAME:rfc1034identifier}
の場合は次のように設定
します。
PRODUCT_NAME にはビルド時にアプリケーションの名前が入ります。
ここで設定した値がブラウザから呼び出す時に使う URL スキームとなります。
４．３．コンバージョン属性情報の設定
MOBYLOG のデータ紐付け機能では、コンバージョン時に属性データを最大５つまで紐付けることができます。
この属性データを任意に設定することができます。コンバージョン属性データを計測するにはコンバージョンとな
るページで任意にパラメタを通知するようにビーコン通知タグを記述します。
■MOBYLOG データ紐付けができるパラメタ一覧
項目
カラムの型（サイズ）
備考
integer(8)
数値情報であれば、売上金額でなくても問題ありません。
明細パラメタ
varchar(512)
任意の文字列であれば売上明細でなくても問題ありません。
その他１
varchar(100)
その他２
varchar(100)
その他３
varchar(100)
合計金額パラメタ
必須
○
データ紐付け機能で集計できる情報は、５つのパラメタまでです。パラメタ名は任意に付けることができます。
MOBYLOG に通知する値のサイズがオーバーしている場合、最大長より後ろは切り取られます。
23
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
MOBYLOG SDK for iOS インストール 設定 マニュアル
CONFIDENTIAL
４．３．１．ビーコン通知タグ拡張
sendWithScreen:parameters: の第二引数へ NSDictionary を渡すことができます。NSDictionary 内に格納さ
れた Key/Value ペアのデータがビーコンに付加されてログ受付サーバへ送信されます。
例）
NSDictionary* params = [NSDictionary dictionaryWithObjectsAndKeys:
@”10500”,
@”price”,
@”JAN0000000001”,
@”jan_cd”,
@”MOBYLOG 太郎”,
@”user_name”,
@”東京都”,
@”area”,
@”代引き”,
@”pay”, nil];
[MLBeacon sendWithScreen:@”Conversion” parameters:params];
この例では、URL「Conversion」において、合計金額パラメタに「price」パラメタを利用し、値に売上金額（数値
情報）を設定。明細パラメタに「jan_cd」、その他１
３にそれぞれ「area」「user_name」「pay」パラメタを紐付
けるようにしています。
４．３．２．属性データの計測方法
MOBYLOG では、成果ページとして識別される URL に対して、データ紐付けパラメタが通知されている時にのみ、
コンバージョン属性として集計を行います。
MOBYLOG 管理画面のマスタ管理で各種設定を行います。
①
成果ページ設定
成果ページとみなす URL を登録します。成果ページ URL は任意に決めることができますが、MOBYLOG
SDK で通知する URL と同じ必要があります。
尚、ここでは４．３．１．の例に従い「Conversion」を登録します。
24
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
②
データ紐付け設定
成果ページでデータ紐付けを行う
パラメタの設定を行います。
ルールは上記に示した通りです。
４．３．３．コンバージョン属性取得の注意事項
MOBYLOG SDK は、80 ポートを利用して属性情報を通知するため、アプリ→MOBYLOG ログ受付サーバ間のセ
キュリティが担保されません。よって、コンバージョン属性で取得する情報は、個人情報を含めないようにしてく
ださい。
４．４．ROI の計測
MOBYLOG の ROI 計測機能では、広告別の ROI を計測することができます。
ROI もコンバージョン属性の計測同様に、ルールに従ったタグ設定行い MOBYLOG にビーコン通知することで、
計測を行うことができます。
４．４．１．月額課金用の ROI タグ設定
月額課金の ROI を計測するには、「新規会員登録」、「会員のコース変更」、「解約」の処理時にビーコン通知を
実行し、MOBYLOG 側にログを記録する必要があります。
尚、広告経由アプリダウンロード計測は HandloaD TAG を利用して計測を行いますが、その際に月額課金の通
知処理を行う場合は、MOBYLOG SDK で通知を行う必要はありません。
■月額課金用の ROI タグ
項目
パラメタ名
必須
最大サイズ
備考
コース
ktr_uflg
○
-
マスタ管理で設定したコースの値を指定。
課金金額
ktr_ufee
○
4 byte(数値)
課金額を指定。無料の場合は「0」を指定。
ユニークキー
ktr_umid
32 byte
アプリケーション側で管理しているユニークキーを指定。
ここに指定された ktr_umid はビーコン通知時に暗号化されない。
MOBYLOG で管理する端末識別番号以外で計測する際に指定。通常
は利用しない。
課金開始日
ktr_usd
YYYY-MM-DD
初月無料など、会員登録日と課金開始日が違う場合に指定。
25
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
設定例） 2010 年 7 月 8 日に初月無料の月額課金の 100 円コースで会員登録を実施したと仮定した場合
のタグ
NSMutableDictionary* params = [NSMutableDictionary dictionary];
[params setObject:@”1”
forKey:@”ktr_uflg”];
// ①
[params setObject:@”100”
forKey:@”ktr_ufee”];
// ②
[params setObject:@”2010-07-08”
forKey:@”ktr_usd”];
// ③
[params setObject:@”100”
forKey:@”price”];
// ④
[MLBeacon sendWithScreen:@”Conversion” parameters:params];
CAUTION
// ⑤
①
マスタ管理-ROI 設定で 100 円コースが「ktr_uflg=1」に設定されていると仮定しています。
②
100 円コースなので 100 を指定します。
解約通知がない限りここに指定された金額が毎月加算されて計測されます。
③
課金開始日を 2010 年 7 月 8 日に指定しています。
④
100 円コースなので 100 を指定しています。これはコンバージョン属性タグです。マスタ管理-データ紐付け設
定で売上金額パラメタに「price」が指定されており、また、HandloaD TAG の設定ファイル（ini ファイル）の
KtrackSendParams に「price」が指定されていると想定しています。
これにより、レポート画面の「コンバージョン」にコンバージョン属性データとして計測されます。ただし、コンバ
ージョン機能上には、翌月のコンバージョン属性データは反映されません。
尚、この設定は省いても月額課金の ROI 計測は可能です。
⑤
マスタ管理-成果ページに「Conversion」が登録されていることを前提としています。
４．４．２．従量課金用の ROI タグ設定
アプリ内課金等の従量課金もしくは EC サイトの受注金額の ROI を計測するには、コンバージョン時にビーコン
通知を実行し、MOBYLOG 側にログを記録する必要があります。
■従量課金用の ROI タグ
項目
パラメタ名
必須
最大サイズ
備考
コース
ktr_jflg
○
-
マスタ管理で設定したコースの値を指定。
ユニークキー
ktr_jmid
32 byte
アプリケーション側で管理しているユニークキーを指定。
ここに指定された ktr_jmid はビーコン通知時に暗号化されない。
MOBYLOG で管理する端末識別番号以外で計測する際に指定。通常
は利用しない。
従量課金（EC サイトの場合は受注金額）の場合は、属性タグを併用し、売上金額（およびその他の属性情報）を
MOBYLOG 側に通知するようにします。
設定例） 2010 年 7 月 8 日に従量課金の 300 円コースを契約したと仮定した場合のタグ
NSMutableDictionary* params = [NSMutableDictionary dictionary];
[params setObject:@”3”
forKey:@”ktr_jflg”];
// ①
[params setObject:@”300”
forKey:@”price”];
// ②
26
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
[MLBeacon sendWithScreen:@”Conversion” parameters:params];
CAUTION
// ③
①
マスタ管理-ROI 設定で従量課金の 300 円コースが「ktr_jflg=3」に設定されていると仮定しています。
②
300 円コースなので 300 を指定しています。これはコンバージョン属性タグです。ママスタ管理-データ紐付け
設定で売上金額パラメタに「price」が指定されていることを想定しています。
これにより、レポート画面の「コンバージョン」にコンバージョン属性データとして計測されます。
③
マスタ管理-成果ページに「Conversion」が登録されていることを前提としています。
※
従量課金の場合は、ビーコン通知された日時が CV 日時となり計測されます。
従量課金の場合は、必ずコンバージョン属性タグで金額パラメタを同時に通知するようにして下さい。この設定
をしないと金額を MOBYLOG 上に記録することできず、ROI 測定ができなくなります。
４．５．イベント通知
MOBYLOG 5.1 でイベント計測を行う場合、MOBYLOG にログ通知する際に、イベント計測用のパラメタを付与す
る必要があります。
以下は、イベントを発生させるページを「トップ画面」とし、イベント名を「ボタン A」、イベントカテゴリ名を「カテゴリ
A」とした場合のサンプルコードです。
イベント計測用パラメタの通知方法は、コンバージョン属性や ROI でパラメタを追加する方法と同様です。
NSMutableDictionary* params = [NSMutableDictionary dictionary];
[params setObject:@”1”
forKey:@”event”];
// ①
[params setObject:@”ボタン A”
forKey:@”ktr_ev”];
// ②
[params setObject:@”カテゴリ A”
forKey:@”ktr_evct”];
// ③
[MLBeacon sendWithScreen:@”トップ画面” parameters:params];
CAUTION
①
event パラメタは必須項目で、有効値は「1」のみです。
②
イベント名を指定します。
③
イベントカテゴリ名を指定します。
このようにすることで、このメソッドで通知されるログはイベントデータとして MOBYLOG 側で判断され、イベントメ
ニューでレポートを参照することができます。
４．６．ビーコン通知パーミッションの管理
MOBYLOG SDK はビーコン通知のパーミッション管理を行うことができます。
例えば、アプリ側で初回起動時に、ユーザーにビーコン通知のパーミッション画面を表示し、その返値によって
ビーコン通知の ON/OFF を制御することが可能です。また、現在のビーコン通知可否状態や、許諾結果の最終
更新日の管理をします。
27
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
①
SDK_DEFAULT_OPTIN の値を変更する
ユーザー許諾フラグの状態を変更します。
[MLBeacon setOptIn:YES];
setOptIn には「YES」もしくは「NO」を指定します。
②
SDK_DEFAULT_OPTIN の値を取得する
BOOL optin = [MLBeacon optIn];
戻り値は「YES」もしくは「NO」になります。
③
SDK_DEFAULT_OPTIN の最終更新日時を取得する
NSDate* date = [MLBeacon optInDate];
戻り値は NSDate 型です。
４．７．動作確認
MOBYLOG SDK の動作確認は以下の方法で実施することができます。
① beacon.plist の DEBUG モードを ON にします。
② MOBYLOG SDK を組み込んだアプリを iOS シミュレーターもしくは実機で起動します。
③ ビーコン通知タグを入れた画面にアクセスします。
④ デバッガコンソールでタグが正常に動作しているか確認します。
⑤ 正常に動作すると、MOBYLOG の管理画面にアクセス情報が反映されます。
時間帯にもよりますが、通常、30 分∼40 分遅れで画面からアクセス情報を確認することができます。
[ユーザー]-[トレンド]を参照し、計測情報が確認できれば正常に動作しています。
28
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
MOBYLOG SDK for iOS インストール 設定 マニュアル
CONFIDENTIAL
５．トラブルシューティング
５．１．ビルド時にリンクエラー
_SCNetworkReachability で始まる関数が見つからないエラーが出る場合。
SystemConfiguration.framework がプロジェクトに追加されていない可能性があります。導入手順を参考にし
てこのフレームワークを追加して下さい。
５．２．その他のエラー
① 設定ファイル「beacon.plist」の設定ミス
SDK/2.0 [ERROR] The license key is invalid, Please confirm SITE_ID and LICENSE_KEY.
実行時に上記エラーが表示される場合は beacon.plist の SITE_ID もしくは LICENSE_KEY が間違っ
ている可能性があります。両方の値を確認して再実行をして下さい。
29
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/
CONFIDENTIAL
MOBYLOG SDK for iOS インストール 設定 マニュアル
６．MOBYLOG SDK のビーコン通知停止について
MOBYLOG SDK ver 2.2 以降では、ビーコン通知処理を MOBYLOG サーバ側で制御することができます。
SDK はアプリ起動時に、前回のビーコン通知から 24 時間以上経過していた場合、MOBYLOG サーバにビーコン
通知許諾の問い合わせを実施します。
ビーコン通知許諾が OFF の場合は、SDK はビーコン通知許諾の問い合わせ処理以外、一切の処理を停止しま
す（ビーコン通知許諾が OFF の場合でも、アプリが起動されて、前回問い合わせから 24 時間以上経過されてい
た場合はビーコン通知許諾の問い合わせ処理は行います）。
ビーコン通知許諾のシステム設定は、MOBYLOG 事務局側で管理を行います。アプリ計測を一時的に停止した
い場合は、MOBYLOG 事務局にお問合せください。
尚、MOBYLOG を解約した場合は、ビーコン通知許諾は自動的に OFF に設定されます。
７．MOBYLOG SDK の制約
MOBYLOG SDK をお使い頂く場合、以下の制約があります。
①
MOBYLOG SDK を組み込んだアプリ配信の実績がありますが、Apple 社の規約変更により利用できなくな
る可能性があります。
② MOBYLOG SDK は十分にテストされた SDK となっておりますが、プログラム内に問題がある可能性があり
ます。
MOBYLOG SDK を組み込んだアプリの配信前には十分にテストをして頂くようお願い致します。
③
Xcode のバージョンアップにより、MOBYLOG SDK が使えなくなる可能性があります。その場合、弊社は可
及的速やかに対応版を提供するよう努めますが、対応版のご提供まで時間が掛かることがあります。
お問い合わせは MOBYLOG 事務局まで
メール
[email protected]
電話
03-5289-9577
（平日 10:00
18:00 土日祝祭日を除く）
30
Copyright © CELLANT Corp. All right Reserved.
http://www.cellant.jp/