Unity SDK

1. 対応Unityバージョン

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

Androidプラットフォームの場合
※ Android 2.2以降

iOSプラットフォームの場合
※ iOS 6.0以降(6.0より前をサポートする場合は、お問い合わせフォーム よりお問い合わせください)

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

既に、Unity SDK (ver1.10以前) をご利用の場合は、一旦以前のファイルを削除の上、以降の手順の実施を行ってください。
※削除対象のファイルはこちらを参照下さい。

Step1:SmartBeat.unitypackageのImport

下記からSmartBeatのSDKをダウンロードしてください。


他形式のSDKは こちら からダウンロードしてください。

SmartBeat-Unity.zipを展開し、SmartBeat.unitypackageを取り出す。
対象のUnityプロジェクトを開き、Assets > Import Package > Custom Package...から、SmartBeat.unitypackageを開き、Importを実行してください。

Step2:GameObjectへscriptのアタッチ

SmartBeatを起動するため、アプリ起動時にロードされるGameObjectを用意し、SmartBeatのスクリプトをアタッチしてください。
対象のGameObjectのに対して、Add Componentをクリックし、Scripts > Smart Beat > Smart Beat Behaviourを追加してください。
このスクリプトのAwake()時に、設定をロードし、SmartBeatを起動します。また、アタッチされたGameObjectに対して、DontDestroyOnLoad()が実行されます。

Step3:APIキーの設定

パッケージのImport後、メニューにSmartBeatのメニューが追加されます。
SmartBeat > Preferences を選択し、SmartBeatの設定を開いてください。

iOS/Androidの項目の下に、API Keyの項目があるので、SmartBeat Console(Unity上のメニューのSmartBeat > Open SmartBeat からアクセス可能)より取得したAPIキーを設定し、「Save」をクリックして保存してください。

※Unity(Android)の場合、コンソール上ではAndroid用のアプリケーション、Unity(iOS)の場合、コンソール上ではiOSのアプリケーションを作成してください。

Step4(Android):Permissionの定義

※こちらの項目はAndroid向けUnityプロジェクトへの組み込みに必要な項目です。

UnityのPlayerSettings (Android)でInternet Accessを Requireにする。
※Player Settingsは、UnityのメニューのEdit > Project Settings > Playerから編集可能です。

unity_2

これは、アプリ内で発生したクラッシュデータをSmartBeatサーバへ送信するため最低限必要なPermissionとなります。

Step5(Android):重複ユーザカウントの抑止設定

※こちらの項目はAndroid向けUnityプロジェクトへの組み込みに必要な項目です。

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

※ 重複ユーザカウントの抑止設定を有効にすることでオーディエンス機能も有効となります。
※ 本機能はGoogle Play services 4.0以降がイントールされた端末を使用するユーザカウントにのみ有効です(それ以外のユーザは従来通りカウントされます)。

本機能を有効にするためには、以下の手順でアプリにGoogle Play servicesを組み込んでください。本機能を有効にしない場合には、以下の手順は不要です。

  • Android Studio
  • Eclipse + ADT
Google Repositoryのダウンロード

Android SDK ManagerでGoogle Repositoryをインストールしてください。
install_google_repository

build.gradleの編集

アプリのモジュールのbuild.gradleを開き、以下のようにdependenciesにplay-servicesを追加してください。追加するplay-servicesのバージョンは最新バージョン(https://developers.google.com/android/guides/releases を参照)を指定してください。

dependencies {
    compile 'com.google.android.gms:play-services:8.4.0'
}

build.gradle編集後はAndroid Studioのツールバーの「Sync Project with Gradle Files」ボタンで編集結果をプロジェクトに同期してください。

Google Play servicesのダウンロード

Android SDK ManagerでGoogle Play servicesをインストールしてください。
install_google_play_services

プロジェクトの追加

Eclipseで「File」 -> 「Import」から「Existing Android Code into Workspace」を選び、google-play-services_libをプロジェクトにインポートしてください。google-play-services_libはAndroid SDKのインストールディレクトリ配下の以下のディレクトリにあります。

<android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib

「Copy projects into workspace」のチェックはオンにしてください。
import_google_play_services

ライブラリの追加

アプリのプロジェクトのプロパティを開き、「Android」の設定の「Library」の項目にある「Add...」ボタンをクリックしてgoogle-play-services_libを追加してください。
library_google_play_services

マニフェストファイルの編集

アプリのマニフェストファイルを開き、<application>要素に以下を追加してください。

<meta-data android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Step6(Android):ビルドシンボルの自動アップロード(IL2CPPビルドのみ)

AndroidのIL2CPPビルドの場合、ビルドシンボルを自動的にSmartBeatコンソールにアップロードし、発生したNativeCrashのスタックトレースを自動的にシンボリケートすることができます。
Unityのメニューに追加された、SmartBeat > Build Preferencesを選択し、ビルド設定を開いてください。
Console(Unity上のメニューのSmartBeat > Open SmartBeat からアクセス可能)より取得したAPIキーとAPI Tokenを設定し、Enable Symbol Uploadにチェックを入れて「Save」をクリックして保存してください。
※以降のビルド時に自動的にシンボルがアップロードされます。
※本機能はUnity5.3.4以降のみでサポートされます。

Step4(iOS):Framework/Libraryの追加

※こちらの項目はiOS向けUnityプロジェクトへの組み込みに必要な項目です。

Xcodeを起動し、対象のTargetを選択。「General」 -> 「Linked Frameworks and Libraries」上で「+」をクリックし、標準に含まれる以下のframework/Libraryを追加する。

  • libz.tbdまたはlibz.dylib(iOS SDKバージョン1.20以降)

下記frameworkは、古いUnityを利用している場合にのみ、自動で追加されないので、追加する

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

Step5(iOS):重複ユーザカウントの抑止設定

iOS SDKバージョン1.18以降

※こちらの項目はiOS向けUnityプロジェクトへの組み込みに必要な項目です。

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

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

本機能を有効にしない場合には、以下の手順は不要です。

リンカオプションの追加

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

-force_load $(SRCROOT)/Libraries/Plugins/iOS/libSmartBeatIdfa.a

linker_flags_unity

3. オプション機能

本節にて、追加機能に関して記述します。アプリケーションからAPIを呼び出すことでこれら追加機能を有効にすることが可能です。
また、SmartBeatの各種APIはSmartBeatネームスペース配下に宣言されていますので、”using SmartBeat;”を追加すると、以降記述されるコードサンプル内の最初の「SmartBeat.」を省略することが可能です。

3.1 画面キャプチャ機能

本機能を有効にした場合、エラー発生時のスクリーンショットを保存し、エラー情報と共にSmartBeatサーバへ送信します。

有効化方法

UnityのメニューからSmartBeat > Preferences を選択し、SmartBeatの設定を開き、Enable Screenshotにチェックを入れてください。
スクリーンショットの画像は、一時的に「/smartbeat_screenshot_nn.png」というファイル名(nnは任意の整数)で保存されます。
変更する必要がある場合は、「SmartBeat.cs」を開き該当箇所を編集することで変更可能です。ファイルはSmartBeatサーバへ送信後、自動的に削除されます。

3.2 LogCat/NSLog出力

LogCat/NSLogの出力をクラッシュデータに含める場合は、Log出力機能を有効にしてください。
※iOS 10.0以降では本機能を有効にしてもNSLogをクラッシュデータに含めることはできません。
※Unity SDKバージョン1.9以降では本機能を有効にしなくてもenableLogRedirect()を有効にすれば
ログがSDK内部に保存されるのでクラッシュデータにログが含まれるようになります。

有効化方法

UnityのメニューからSmartBeat > Preferences を選択し、SmartBeatの設定を開き、Enable Logにチェックを入れてください。
なお、Android4.1より前(APIレベル15以前)においては、LogCatの出力のため、下記Permissionが必要となります。
Android4.1以降においては、Permissionの設定は不要ですが、自身のアプリが出力したLogのみが取得可能です。

<uses-permission android:name="android.permission.READ_LOGS"/>

3.3 ユーザID設定

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

有効化方法

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

SmartBeat.SmartBeat.setUserId(“user001”);

3.4 拡張情報

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

有効化方法

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

SmartBeat.SmartBeat.addExtraData("key1", "value1");
SmartBeat.SmartBeat.addExtraData("area", "Tokyo");

値を変更したい場合は、同じキー名で追加すると、新しい値で上書きされます。

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

Unity SDKバージョン1.5以降

初期状態をエラー収集無効とし、途中からエラーの収集を有効にしたい場合、SmartBeatBehaviour.csをアタッチしたGameObjectの生成を遅らせることで対応可能となります。
有効にしたいタイミングで対象のGameObjectの生成を行ってください。

3.6 オーディエンス機能

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

有効化方法

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

4. その他API

また、その他のAPIを記述します。APIはSmartBeat.csに実装されています。

API 説明
void leaveBreadcrumb(string breadcrumb) パンくずを残す。APIで設定されたパンくずを最大16個保存します。残されたパンくずはクラッシュデータとともにSmartBeatサーバへ保存されます。
void enableScreenshot() スクリーンショット保存機能を有効にします。設定で有効にされており、有効・無効を切り替えない場合は、本APIは利用する必要はありません。disableScreenshot()で無効にした後、再度有効に戻す場合などに、ご利用いただけます。
void disableScreenshot() スクリーンショット保存機能を無効にします。以降のクラッシュではスクリーンショットは保存されません。保存したくない画面表示前などに呼び出してください。デフォルトではスクリーンショット保存機能は無効になっているので、設定で有効にする。あるいは、enableScreenshot()を呼びださない限り本APIを呼び出す必要はありません。
bool HandleLog(string logString, string stackTrace, LogType type) 通常、SmartBeatでUnityのエラーをハンドルしているのでこのAPIを呼び出す必要はありません。端末ログに出力せずにSmartBeatのみにログを保存する目的で、独自にLoggerを実装している場合などに、ご利用いただけます。
引数:
  logString : ログ
  stackTrace : スタックトレース
    (空文字の場合、System.Diagnosticsを利用して取得します)
  LogType : 対象のログのLogType
戻り値:
  LogTypeが記録対象外あるいは、頻度が高い(1回/2秒以上)の場合、falseを返します。それ以外はtrueを返します。

5. その他Permission

SmartBeatは、クラッシュログ収集時に解析に必要な端末の状態など周辺情報も一緒に記録します。
それら情報の中にはPermissionの付与が必要な物があります。SmartBeatはPermissionがなく、情報の取得ができない場合、”no permission”と記録しますが、Permissionを付与することで以下の情報も取得することができます。

Permission名 取得可能情報
android.permission.ACCESS_NETWORK_STATE NW接続状態

6. リソース消費

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

Androidの場合

端末 項目 SDK組込み時
Nexus7 (2012)
Android 4.4.2
メモリ消費量
CPU負荷
約1.7MB増加
増減なし
Xperia AX
Android 4.1.2
メモリ消費量
CPU負荷
約0.6MB増加
増減なし
Xperia Ray
Android 2.3.4
メモリ消費量
CPU負荷
約1.1MB増加
増減なし

iOSの場合

端末 項目 SDK組込み時
iPhone5S
iOS7.0.4
メモリ消費量
CPU負荷
約1.0MB増加
増減なし
iPhone4
iOS6.0.1
メモリ消費量
CPU負荷
約1.0MB増加
増減なし

定常的に画面キャプチャを取得していないため、画面キャプチャ機能のオン/オフにかかわらず、エラーが発生しない状況ではCPUリソースの消費はありません。

Unityでの画面キャプチャ機能をONにされていた場合、例外発生時に画面の取得の処理がメインスレッドから呼び出される場合があり、例外が連続で発生した場合など多少挙動に影響を与えることがあります。
ただし、1度取得すると2秒間は取得しないようにしておりますので、連続で発生した際の挙動への影響は最低限に抑えるようにしております。

7. 改版履歴

改版日 変更内容
2014年2月4日 初版リリース
2014年3月24日 追加するFramework(iOS)からCoreLocation.frameworkを削除
その他Permission(Androidのみ)からACCESS_FINE_LOCATIONを削除
2014年6月16日 リソース消費の項目を追加
2014年6月27日 「3.5 エラー収集有効・無効切り替え」を追記(Unity SDKバージョン1.5以降)
UnityログのNSLogへの転送に関する記述を追記
2014年10月23日 「Step3(Android):Android向けLibraryのコピー」を変更
2016年1月6日 「Step5(Android):重複ユーザカウントの抑止」を追加(Android SDKバージョン1.12以降)
「Step4(iOS):IDFAによるユーザカウントの有効化」を追加(iOS SDKバージョン1.18以降)
2016年1月13日 iOS向けの説明をフレームワーク版SDKを使ったものからライブラリ版SDKを使ったものに変更
2016年4月20日 「3.6 オーディエンス機能」を追加
2016年11月21日 「Step3(iOS):iOS向けLibraryのコピー」の必要ライブラリを追加
「3.2 LogCat/NSLog出力」の補足説明を追加
「4. その他API」のenableLogRedirect()の説明を変更
2017年10月17日 SDKの配布形式をunitypackageに変更し、組込み方法を更新