Unity SDK

1. SUPPORTED UNITY VERSION

SmartBeat SDK requires Unity4.2.1 and above.

Android Platform Requirements:
* Android 2.2 and above.

iOS Platform Requirements:
* iOS 6.0 and above. (Please use the contact form if you need support for Unity prior to version 6.)

2. INITIALIZE

Existing Unity SDK users (version 1.10 and prior), should delete the files from those integrations before following the procedure below.
*Refer to the instructions here for details of the files which must be deleted.

Step1:Import SmartBeat.unitypackage

Download SmartBeat SDK from below.

Uncompress SmartBeat-Unity.zip and locate SmartBeat.unitypackage.
Open the target Unity Project and choose from the menu, Assets > Import Package > Custom Package... In the File dialog, select SmartBeat.unitypackage and click Import.

When building Unity 5.x for Android

Because Unity 5.x doesn't support Android arm64 binaries, a build error may occur. To prevent this, on the Import dialog, uncheck the box for Plugins/Android/libs/arm64-v8a/libSmartBeatNdk.so.

Step2:Attach script to a GameObject

To enable SmartBeat, create a GameObject which will load when the application boots, and attach the SmartBeat script.
Select the target GameObject and click Add Component, then select Scripts > Smart Beat > Smart Beat Behavior.
When this script's Awake() method is called, it will load settings and activate SmartBeat. The script will also call DontDestroyOnLoad() from the object.

Step3:Set API key

After importing the package, a new SmartBeat menu will appear in the Unity Editor.
Select SmartBeat > Preferences to open the SmartBeat settings.

Beneath the iOS and Android titles, find the input box for API Key and input the keys exported from the SmartBeat Console's (From the Unity Top Menu select SmartBeat-> Open SmartBeat) Application Settings > API Key and click Save.

**If your Unity application is for Android, please create an application as Android one (not Unity) on the SmartBeat console and use API key in it.
If your Unity application is for iOS, please create an application as iOS one (not Unity) in SmartBeat console and use API key in it.

Step4(Only for Android):Set Permissions

Set Internet Access in PlayerSettings(Android) of Unity to “Require”.
※You can change PlayerSettings in Edit > Project Settings > Player.

unity_2

SmartBeat uses this permission to send the crash reports and performance metrics.

Step5(Only for Android):Duplicate user count prevention

Android SDK Version 1.12 and up

By enabling this feature, it is possible to identify a single user even if the user repeatedly uninstalls and re-installs (a.k.a "reset marathon"). That means it is possible to avoid unexpected increases of MAU.

The Audience feature is enabled by using the "Duplicate User Count Prevention" functionality.
※ This only works for the users whose device is using Google Play services 4.0 and above (Otherwise, users are counted as before).

In order to enable this feature, add Google Play services in the following way. If you don't enable this feature, you can skip the following steps.

  • Android Studio
  • Eclipse + ADT
Download Google Repository

Install Google Repository using Android SDK Manager.
install_google_repository

Edit build.gradle

Open build.gradle in your app's module, then add play-services into dependencies as bellow. Ensure the version number of play-services is the latest version (see https://developers.google.com/android/guides/releases).

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

After modifying build.gradle, apply the changes to the project by clicking the "Sync Project with Gradle Files" button in the toolbar in Android Studio.

Download Google Play services

Install Google Play services using Android SDK Manager.
install_google_play_services

Add project

Click "File" > "Import" in Eclipse, then select "Existing Android Code into Workspace" and import google-play-services_lib as a project. google-play-services_lib is in the following directory under Android SDK you installed.

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

Turn on the "Copy projects into workspace" checkbox.
import_google_play_services

Add library

Open your app's property and show "Android" setting, then click the "Add..." button in the "Library" part and add google-play-services_lib.
library_google_play_services

Edit manifest file

Open your app's manifest file and add the following tag into the <application> element.

<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
How to check
Unity SDK Version 1.18 and up

By using the API shown below, it's possible to check whether the duplicate user count prevention function has been successfully activated.

bool ok = SmartBeat.SmartBeat.isReadyForDuplicateUserCountPrevention();

If the above API returns false, Google Play services might not be successfully integrated.

Step6(Only for Android):Build Symbol Automatic Upload (IL2CPP builds only)

When doing IL2CPP builds, build symbols are automatically uploaded to the SmartBeat console, so when a native crash occurs the stack trace will be automatically symbolicated.
Select SmartBeat > Build Preferences to open the SmartBeat build settings.
Find the input box for API Key and API Token and input the keys exported from the SmartBeat Console's (From the Unity Top Menu select SmartBeat-> Open SmartBeat) Application Settings > API Key, check the Enable Symbol Upload checkbox and click Save.
*After setting, builds will automatically upload symbol files
*This function supports Unity 5.3.4 and later versions

Step4(Only for iOS):Copy Library for iOS

Download and unzip "iOS SDK (static lib)", then both SmartBeat.h and libSmartBeat.a should be located in the "Assets/Plugins/iOS" .

In addition, start the Xcode and select a target you want to use. And in the Build Phases tab, expand the Link Binary With Libraries section, press the “+ button”, then add following standard frameworks.

  • libz.tbd or libz.dylib (SDK Version 1.20 and up)

The following frameworks are not added by older versions of Unity and must be added manually.

  • SystemConfiguration.framework
  • CoreTelephony.framework
  • AdSupport.framework (Add if you use the duplicate user count prevention. Add by "Optional" if your application supports before iOS 6.0 as deploy target.)

Step5(Only for iOS):Duplicate user count prevention

iOS SDK Version 1.18 and up

By enabling this feature, it is possible to identify a single user even if the user repeatedly uninstalls and re-installs (a.k.a "reset marathon"). That means it is possible to avoid unexpected increases of MAU.

The Audience feature is enabled by using the "Duplicate User Count Prevention" functionality.
※ This only works for iOS 6.0 and above users

If you don't enable this feature, you can skip the following steps.

Add linker flags

Select a suitable target in the Xcode, and in the Build Phases tab, add the following into the Other Linker Flags list.

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

linker_flags_unity

How to check
Unity SDK Version 1.18 and up

By using the API shown below, it's possible to check whether the duplicate user count prevention function has been successfully activated.

bool ok = SmartBeat.SmartBeat.isReadyForDuplicateUserCountPrevention();

If the above API returns false, the requisite frameworks might not be successfully integrated. For details, check the error log emitted by the SDK. (the log entry will contain "isReadyForDuplicateUserCountPrevention")

3. EXTRA FUNCTIONS

You can activate extra functions by calling APIs in Application.

3.1 Screenshots function

When this function is activated, you can get some application’s screenshots just before exception occurs.

How to activate

From the Unity Top Menu select SmartBeat > Preferences and check the Enable Screenshot checkbox.
The screenshot is temporarily saved as /smartbeat_screenshot_nn.png(nn: any integer). It will be automatically deleted after sending it SmartBeat server.

3.2 Include LogCat/NSLog

SmartBeat can also include LogCat or NSLog with crash/exception data.
*As of iOS 10, even if enabled, this section's NSLog feature will not function.
*Unity 1.9 and later versions may use enableLogRedirect to save logs within the SDK for sending with crash reports.

How to activate

From the Unity Top Menu select SmartBeat > Preferences and check the Enable Log checkbox.
If you want send LogCat data for device with Android 4.1 and below, you should add this line:

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

to your app's AndroidManifest.xml file.

3.3 Set user identifier

If your application provides a user ID for each user, you can include it with crash/exception data. That help you find specific user’s errors by using this user ID on the SmartBeat web console.

How to activate

In order to set user ID, call the API below:

SmartBeat.SmartBeat.setUserId(“user001”);

3.4 Add Extra data

You have another option to add extra custom information into the crash/exception reports. This will help you reproduce and fix errors. (e.g. user’s entering parameters, API return values etc.)

How to activate

In order to set a couple of a key and a value with crash data, call the API below:

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

The values will be overwritten by new one which has the same key.

3.5 Disabling crash/exception report by default

Unity SDK Version 1.5 and up

If you would like to start with error capture disabled, and only enable SmartBeat at a later time, it's possible to create a GameObject with SmartBeatBehavior.cs attached at a later time. When you want to enable error capture, create the GameObject.

3.6 Audience function

By using the Advertising ID for Android or IDFA for iOS, it's possible to understand the gender and age distribution of your users.

The Audience feature is enabled by using the "Duplicate User Prevention" functionality. Please see details regarding the settings for Duplicate User prevention here( android / iOS ).

4. OTHER APIS

You can also use APIs below in your application. These APIs is packaged in SmartBeat.cs.

API Instruction
void leaveBreadcrumb(string breadcrumb) It leaves Breadcrumbs. Breadcrumbs set by API are retained to 128.
Typical actions and status changes are automatically recorded as breadcrumbs. Please see here for details of what is recorded.
It will be sent to SmartBeat server with crash data.
void enableScreenshot() Enables the screenshot function. When the screenshot feature is enabled, it is unnecessary to use this feature unless you have explicitly disabled the screenshot feature. It is only necessary to use this feature after you have disabled screenshots with the disableScreenshot() method.
void disableScreenshot() Disables the screenshot function. Crashes after this point will not preserve a screenshot. Call this method before displaying a screen, etc with content you don't want captured. By default, the screenshot function is disabled, so calling this method is unnecessary unless you have explicitly enabled screenshots by settings, or using the enableScreenshot() method.
bool HandleLog(string logString, string stackTrace, LogType type) Normally, Unity errors will automatically call the SmartBeat error handler, so using this API is not necessary. Instead, use this API to avoid outputting logs to the device logger, when using a custom logger, etc, so the logs can be sent when an error occurs.
Parameters:
  logString : Log Message
  stackTrace : Stack Trace
    (When blank, System.Diagnostics is used)
  LogType : The LogType of the message
Return Value:
If the LogType isn't being saved, or frequency of the exception report is too high (once every 2 seconds or more), false is returned. Otherwise true is returned.

5. OTHER PERMISSIONS (ONLY FOR ANDROID)

Some of the data which the SmartBeat SDK collects requires extra permissions.

Permission Data
android.permission.ACCESS_NETWORK_STATE Status of network

If there is no permission to access this data, it will be displayed as “no permission” in Device Information in the SmartBeat console.

6. RESOURCE USAGE

The resource usage of SmartBeat SDK is as follows:

Android

Device Items Resource usage
Nexus7 (2012)
Android 4.4.2
Mem. usage
CPU usage
about 1.7MB up
no change
Xperia AX
Android 4.1.2
Mem. usage
CPU usage
about 0.6MB up
no change
Xperia Ray
Android 2.3.4
Mem. usage
CPU usage
about 1.1MB up
no change

iOS

Device Items Resource usage
iPhone5S
iOS7.0.4
Mem. usage
CPU usage
about 1.0MB up
no change
iPhone4
iOS6.0.1
Mem. usage
CPU usage
about 1.0MB up
no change

Because the SmartBeat SDK for not take screen shots continuously, the screenshots function will not consume CPU resource until an error occurs.

If the screenshots function is enabled, consecutive exceptions may somewhat affect your application's performance, as the processing of Screenshots function will be called on the main thread when an exception occurs. To minimise this, once an exception is caught, SmartBeat SDK does not take subsequent screenshots for two minutes, so to minimise the impact to the application.