iOS SDK

1. 対応iOSバージョン

本SDKはiOS4.3以降の環境にて動作します。

2. iOSのProjectへのSDKの取り込み方法

Step1:SDKの取り込み

  • CocoaPods
  • マニュアル インストール

Podfileに以下の行を追加してください。

pod 'SmartBeat-bitcode'

※重複ユーザカウントの抑止設定を行う場合は、'SmartBeat-bitcode'の代わりに'SmartBeatPlus-bitcode'を記述してください。
※iOS6より前のバージョンをサポートする場合、bitcode無効版(SmartBeat, SmartBeatPlus)を指定して下さい。

その後、以下のコマンドを実行してください。

$ pod install
$ pod update

また、今後SDKのバージョンを更新する場合は、pod updateを実行するのみで、バージョンアップが実施できます。

下記からSmartBeatのSDKをダウンロードして、unzipしてください。
他形式のSDKは こちら からダウンロードしてください。

まず、SmartBeatFramework.frameworkを任意のフォルダにコピーする。
Xcodeを起動し、対象のTargetを選択。「General」 -> 「Linked Frameworks and Libraries」上で「+」をクリックし、Add OtherからSmartBeatFramework.frameworkを選択し、追加する。

例) Xcode 8.3.xの場合

次に、標準に含まれる以下のframeworkを追加してください。

  • SystemConfiguration.framework
  • CoreTelephony.framework
  • CoreGraphics.framework
  • OpenGLES.framework
  • AdSupport.framework(重複ユーザカウント排除機能を利用する場合に追加。デプロイターゲットとしてiOS6.0より前も対象とする場合には"Optional"で追加してください)
  • libz.tbdまたはlibz.dylib(SDKバージョン1.20以降)

Step2:APIキーの設定

Xcodeで対象のProjectのAppDelegate.mを開き以下のimport文を追加する

#import <SmartBeatFramework/SmartBeat.h>

SmartBeatの初期化APIを – application:didFinishLaunchingWithOptions: の最初に追加する
「APIキー」に関してはコンソールよりProject作成時に発行されるキーを設定する

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [SmartBeat startWithApiKey:@"APIキー"];
    //your code

※App Extensionの場合、ExtensionとContaining Appの両方に別のAPIキーを用いて実装する必要がある。Containing App側は通常のApp同様にAppDelegateに実装する。Extension側はAppDelegateが作成できないため、ViewControllerのinitWithCoderからSmartBeatの初期化を行う。initWithCoderが未実装の場合は下記のように実装を追加する。

//Extensionの場合のSmartBeat初期化
- (id)initWithCoder:(NSCoder *)coder
{
    self = [super initWithCoder:coder];
    [SmartBeat startWithApiKey:@"APIキー for Extension"];
    return self;
}

Step3:重複ユーザカウントの抑止設定

SDKバージョン1.18以降

ユーザ数の集計にIDFAを使用することで、同一ユーザの重複カウントを抑止します。これにより、アプリの再インストールを繰り返す行為(俗に言う「リセマラ」)があった場合でも、不要なMAU(Monthly Active Users)数の増加を抑えることができます。

※ 重複ユーザカウントの抑止設定を有効にすることでオーディエンス機能も有効となります。
※ 本機能はiOS 6.0以降を利用のユーザカウントにのみ有効です。
本機能を有効にしない場合には、以下の手順は不要です。

  • CocoaPods
  • マニュアル インストール

下記のように、Podfileに記述するパッケージ名を「SmartBeat-bitcode」から、「SmartBeatPlus-bitcode」へ変更してください。

# pod 'SmartBeat-bitcode'
pod 'SmartBeatPlus-bitcode'

続いて、設定反映のため、

$ pod install
$ pod update

を実行してください。
※bitcode無効版を利用する場合は、「-bitcode」なしのパッケージを指定してください。

また、SmartBeatのヘッダ読み込みを SmartBeatPlus/SmartBeat.h に変更してください。

//#import <SmartBeatFramework/SmartBeat.h>
#import <SmartBeatPlus/SmartBeat.h>
SmartBeatIdfa.frameworkの追加

Step1と同様にして、Xcodeで「General」 -> 「Linked Frameworks and Libraries」上で「+」をクリックし、Add OtherからSmartBeatIdfa.frameworkを選択してFrameworkを追加してください。

※ SmartBeatFramework.frameworkとSmartBeatIdfa.frameworkの両方が必要です。

sb_idfa_framework

リンカオプションの追加

Xcodeで対象のTargetを選択し、「Build Settings」の「Other Linker Flags」に以下を追加してください。

-force_load /Frameworkを置いたフォルダのパス/SmartBeatIdfa.framework/SmartBeatIdfa

linker_flags

3. オプション機能

本節にて、追加機能に関して記述します。アプリケーションからAPIを呼び出すことでこれら追加機能を有効にすることが可能です。

メインスレッド以外のスレッドからのAPIの呼び出しについて

SDKバージョン1.22.6より前では、SBLog、leaveBreadcrumb、logExceptionのAPIをメインスレッド以外のスレッドから呼び出す場合は、スレッドが破棄されるまでAPI内部で使用したメモリが解放されずに溜まり続ける場合があります。長時間生存するスレッドから呼び出す場合は、@autoreleasepoolで囲うようにしてください。
※SDKバージョン1.22.6以降では、下記の対応は必要ありません。

- (void)threadfunc:(id)argument
{
    while (YES) {
        @autoreleasepool {
            ...
            SBLog(@"log message");
            ...
        }
    }
}

3.1 画面キャプチャ機能(非OpenGL ES)

本機能を有効にすることで、クラッシュ発生までの画面遷移が確認できるようになります。
SDKでは、アプリケーション表示中の最新画面を定期的キャプチャし、クラッシュ時に最新の1枚をSmartBeatサーバへ送信します。
※OpenGL ESで描画を行っている場合は、3.2章を参照ください。
※OpenGL ESで描画を行っている場合でもiOS7.0以降の端末は、本有効化方法でもキャプチャ可能です。
※App Extensionでは動作しません。

有効化方法

以下のコードをSmartBeat初期化後に呼び出すことで有効にできます。

[[SmartBeat shared] enableAutoScreenCapture];
キャプチャ対象外のViewを登録

ユーザ個人情報を表示するViewを含む場合など、画面をキャプチャしたくない場合、下記のようにViewのTagを登録することで、画面キャプチャの対象から外すことができます。指定したViewが含まれる画面自体のキャプチャが行われません。

[[SmartBeat shared] addSensitiveViewTag:sensitiveView.tag]

※対象のViewに予め任意のTagを設定しておく必要があります(0以外の値)
※また、指定を外す場合はremoveSensitiveViewTagが利用できます。

3.2 画面キャプチャ機能(OpenGL ES)

OpenGL ESで描画された画面をキャプチャする場合、描画ループの presentRenderbuffer:を呼ぶ前後に下記のようにコードを追加してください。

有効化方法

下記のようにpresentRenderbufferの前後でAPIを呼び出してください。
beforePresetnRenderbufferで渡す引数は、OpenGL ES描画先のUIViewを指定してください。

[[SmartBeat shared] beforePresentRenderbuffer:self];
[context_ presentRenderbuffer:GL_RENDERBUFFER];
[[SmartBeat shared] afterPresentRenderbuffer];

※現時点では、OpenGL ES 1.1はサポートしていません。呼出は無視されます。
※App Extensionでは動作しません。
※本機能はWhitelistに登録された端末のみで動作します。第5章参照。

追加API

任意のデバイスをwhitelistに追加する場合、以下のAPIを利用して追加可能です。

[[SmartBeat shared] whiteListModelForOpenGLES:モデル名];

「モデル名」はiOSのAPI(sysctlbyname関数にhw.machineを指定)から取得した値が設定できます。

3.3 CatchしたExceptionの保存

アプリケーションがCatchしたExceptionを記録することができます。

有効化方法
@try {
    [self doSometingAndThrow];
}
@catch (NSException *exception){
     [[SmartBeat shared] logException:exception];
}
@finally{
}

※メインスレッド以外のスレッドからの呼び出しに関する注意はこちらを参照。

3.4 ログ出力

SDKバージョン1.20以降

端末のログに出力すること無く、ログの収集をすることができます。
※iOS 10.0以降では3.5章のNSLog出力機能を有効にしてもログをクラッシュデータに含める
ことができません。代わりに本機能を使用することを推奨いたします。

※64KBに満たない場合は最大500行、それ以外は64KBに収まる範囲で最新のログを取得します。
※3.5章のNSLog出力機能を有効にした場合、iOS 10.0より前の端末では本機能によるログは
クラッシュデータに含まれず、NSLogによるログのみがクラッシュデータに含まれます。

有効化方法

以下のAPI呼び出しを実装することで、ログを保存できます。

SBLog("String: %@, Integer: %d", "text", 1);

または

va_list args;
va_start(args, format);
SBLogv(format, args);
va_end(args);

SwiftではgetVaListを使って以下のように呼び出してください。

SBLogv("String: %@, Integer: %d", getVaList(["text", 1]))

アプリケーションのPrefix.pchに以下のようなマクロを定義することで、既存のNSLog呼び出し箇所でSBLogにもログを送ることができます。

#define NSLog(...) (NSLog(__VA_ARGS__), SBLog(__VA_ARGS__))

※メインスレッド以外のスレッドからの呼び出しに関する注意はこちらを参照。

3.5 NSLog出力

NSLogの出力をクラッシュデータに含める場合は、NSLog出力機能を有効にしてください。
※iOS 10.0以降では本機能を有効にしてもNSLogをクラッシュデータに含めることはできません。
代わりに3.4章のログ出力APIを使用することを推奨いたします。

※64KBに満たない場合は最大500行、それ以外は64KBに収まる範囲で最新のログを取得します。
※本機能を有効にした場合、iOS 10.0より前の端末では3.4章のログ出力APIによるログは
クラッシュデータに含まれず、NSLogによるログのみがクラッシュデータに含まれます。

有効化方法
[[SmartBeat shared] enableNSLog];

3.6 ユーザID設定

対象のアプリケーションが管理するユーザを識別するIDが既にある場合、それを設定することができます。
設定されたユーザIDはクラッシュとともにSmartBeatサーバへ送信されます。どのユーザでクラッシュが発生したかなど管理コンソール上で確認が可能です。

有効化方法

以下のAPI呼び出しを実装することで、設定可能です。

[[SmartBeat shared] setUserId:@"user001"];

3.7 拡張情報

クラッシュ情報に拡張情報を付与することができます。アプリケーションによっては、ユーザが設定した情報や、アプリケーションが内部に保持している情報が、クラッシュ解析に役立ちます。

有効化方法

以下のAPI呼び出しを実装することで、任意のキー名と値のセットをクラッシュデータと共に保存することが可能です。

NSMutableDictionary *extraData = [NSMutableDictionary dictionary];
[extraData setObject:@"value1" forKey:@"key1"];
[extraData setObject:@"value2" forKey:@"key2"];
[[SmartBeat shared] setExtraData:extraData];

データはNSObjectを継承した任意のデータが設定でき、NSObjectのdescriptionメソッドにより取得できるデータが保存されます。(SDK version 1.8以降)また、値を変更したい場合は、同じキー名で追加すると、新しい値で上書きされます。

3.8 パンくず(breadcrumb)機能

任意のポイントでパンくずを残すことにより、エラー発生までにユーザが行った操作や画面遷移などを収集することができます。

有効化方法

パンくずを落とす(記録を残したい)場所で以下のAPIを呼び出して下さい。

[[SmartBeat shared] leaveBreadcrumb:@"game scene 1"];

パンくずは最後に記録されたものから最大16個保存されます。
例えば、「マップ画面」→「ゲーム画面」→「設定画面」などと、キーとなる画面の遷移時に残した場合、エラー直前にユーザがどのような画面遷移を行ったかを知ることができます。
※メインスレッド以外のスレッドからの呼び出しに関する注意はこちらを参照。

3.9 エラー収集有効・無効切り替え

SDKバージョン1.6以降

初期状態をエラー収集無効とし、途中からエラーの収集を有効にしたい場合に利用できます。

有効化方法

APIキーの設定(上記Step2)で記述したAPIの代わりに以下のAPIで起動時に有効とするか、無効とするか設定してください。

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    BOOL enableSmartBeat = NO; //無効状態で起動する場合はNO
    [SmartBeat startWithApiKey:@"APIキー" withEnabled:enableSmartBeat];
    //your code

その後、有効にしたい場合は、任意の箇所で以下のコードを呼び出してください。呼び出された以降に発生したエラーの収集を行います。

[[SmartBeat shared] enable];

なお、有効・無効の設定は毎起動時に SmartBeat startWithApiKey: withEnabled: で設定してください。

3.10 バックグラウンドアプリの起動の通知

SDKバージョン1.22以降

SmartBeatでは、画面の表示(UIApplicationDidBecomeActiveNotification)をアプリ起動としています。その為、バックグラウンド動作が主となるアプリでは、ユニークユーザが少なくカウントされたり、クラッシュ率が高くなってしまいます。
本APIをアプリのバックグラウンドタスクの処理開始のタイミングで呼び出すことで、ユニークユーザ数をより正確に集計することが可能となります。

[[SmartBeat shared] notifyRunning];

3.11 dSYM自動アップロード

dSYM自動アップロードスクリプトをXcodeのRun Scriptに組み込むことで、毎ビルド自動でdSYMをアップロードすることができます。

詳細な組込み方及びスクリプトはこちらからダウンロードして下さい。

3.12 オーディエンス機能

ユーザ識別子として IDFA を使用することで、アプリケーションを利用するユーザの男女比や年齢分布を確認できるようになります。

有効化方法

重複ユーザカウントの抑止設定を有効にすることでオーディエンス機能も有効となります。重複ユーザカウントの抑止設定についてはこちらを参照ください。

4. リソース消費

SDK組込みによるリソースの消費計測結果を以下に示す。

端末 項目 SDK組込み時
画面キャプチャ無効
SDK組込み時
画面キャプチャ有効
iPhone5S
iOS7.0.4
メモリ消費量
CPU負荷
約1.0MB増加
増減なし
約1.7MB増加
平均 約2.3%増加
iPhone4
iOS6.0.1
メモリ消費量
CPU負荷
約1.0MB増加
増減なし
約1.3MB増加
平均 約4.8%増加

※画面キャプチャを有効にした場合は、画面の画素数に応じてメモリ消費量が増加
※画面キャプチャを有効にした場合は、画面取得、エンコード処理、保存処理が入るため、CPU負荷が増加

5. OpenGL ES画面キャプチャ対象端末

OpenGL ES画面キャプチャ機能のサポート対象を記述する

デバイス名 hw.machine SDKバージョン
iPhone 4 iPhone3,1 iPhone3,2 iPhone3,3 1.19 -
iPhone 4S iPhone4,1 1.19 -
iPhone 5 iPhone5,1 iPhone5,2 1.19 -
iPhone 5C iPhone5,3 iPhone5,4 1.19 -
iPhone 5S iPhone6,1 iPhone6,2 1.19 -
iPhone 6S iPhone8,1 1.19 -
iPhone 6S Plus iPhone8,2 1.19 -
iPhone SE iPhone8,4 1.20 -
iPhone 7 iPhone9,1 iPhone9,3 1.23 -
iPhone 8 iPhone10,1 iPhone10,4 1.23 -
iPhone 8 Plus iPhone10,2 iPhone10,5 1.23 -
iPhone X iPhone10,3 iPhone10,6 1.23 -
iPad 2 iPad2,1 iPad2,2 iPad2,3 iPad2,4 1.19 -
iPad Mini (1st) iPad2,5 iPad2,6 iPad2,7 1.19 -
iPod Touch (5th) iPod5,1 1.19 -
iPod Touch (6th) iPod7,1 1.23 -

6. 改版履歴

改版日 変更内容
2014年2月4日 初版リリース
2014年3月17日 追加するFrameworkからCoreLocation.frameworkを削除
画面キャプチャの最大保存枚数を3枚に変更
2014年4月4日 追加するFrameworkに、CoreGraphis.framework及び、OpenGLES.frameworkを追加
OpenGL ES2.0で描画された画面のキャプチャをサポート(SDK Version 1.3以降)
2014年5月7日 3.1 画面キャプチャ機能の補足説明追記
2014年5月19日 対象OSバージョンをiOS4.3に変更(SDKバージョン1.4以降)
2014年6月27日 「3.9 エラー収集有効・無効切り替え」を追記(SDKバージョン1.6以降)
2014年7月19日 「3.11 dSYM自動アップロード」を追記
2014年8月4日 「3.7 拡張情報」の補足を変更
2014年8月29日 「3.8 パンくず(breadcrumb)機能」を追記
2015年1月26日 「Step2:APIキーの設定」でApp Extensionの場合の初期化に関する記述追加
2016年1月6日 「Step3:IDFAによるユーザカウントの有効化」を追加(SDKバージョン1.18以降)
2016年3月14日 「5. OpenGL ES画面キャプチャ対象端末」を追加
2016年4月20日 「3.12 オーディエンス機能」を追加
2016年11月21日 「2. iOSのProjectへのSDKの取り込み方法」の必要ライブラリを追加
「3.2 画面キャプチャ機能(OpenGL ES)」の追加APIを追加
「3.4 ログ出力」を追加(SDKバージョン1.20以降)
「3.5 NSLog出力」の補足説明を追加
「5. OpenGL ES画面キャプチャ対象端末」のリストを更新
2017年4月13日 「3.10 バックグラウンドアプリの起動の通知」を追加
2017年11月2日 「2. iOSのProjectへのSDKの取り込み方法」にCocoaPodsによる手順を追加
2017年12月28日 「3. オプション機能」にメインスレッド以外のスレッドからのAPI呼び出しについての説明を追加
2018年2月19日 「3. オプション機能」のメインスレッド以外のスレッドからのAPI呼び出しについての説明を更新
2018年5月16日 「5. OpenGL ES画面キャプチャ対象端末」のリストを更新