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.

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.

Add build dependencies

The configuration UI and provided embedding methods may differ depending on the version of Unity and the build pipeline of your project. For this reason, we will use Unity's "custom build.gradle template" as an example here. For more information about "custom build.gradle template", please refer to the Unity manual (https://docs.unity3d.com/ja/2020.2/Manual/android-gradle-overview.html).

Reference: Unity2020.1 "custom build.gradle template" configuration screen

In your app's mainTemplate.gradle, add play-services-ads-identifier to the dependencies as shown below. The version of play-services-ads-identifier to be added must be the latest version (see https://developers.google.com/android/guides/releases).

dependencies {
      implementation fileTree(dir: 'libs', include: ['*.jar'])
      implementation 'com.google.android.gms:play-services-ads-identifier:17.+'
**DEPS**}

If you are using Android Gradle Plugin 2.3 or earlier for building, specify the following instead of the above.

dependencies {
      compile fileTree(dir: 'libs', include: ['*.jar'])
      compile 'com.google.android.gms:play-services-ads:10.0.+'
**DEPS**}
AndroidX Migration

If you are using Android Gradle Plugin 3.6 (default from Unity2020.1) or later for your build, please follow the steps below to migrate your project to AndroidX and make play-services-ads-identifier available.

[Procedure]
Add the following settings to the app's gradleTemplate.properties.

android.useAndroidX=true
**ADDITIONAL_PROPERTIES**
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(Android):Audience feature settings

By using the Advertising ID, it's possible to understand the gender and age distribution of your users.
On Android, use of the duplicate user count prevention feature also enables the audience feature. Check here for details on how to enable the duplicate user count prevention feature.

Step7(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 (Must be present when using the audience function)

Step5(Only for iOS):Duplicate user count prevention

iOS SDK Version 1.21.2 and up

No additional steps are necessary for iOS when using SDK Versions 1.21.2 and later. Duplicate users are determined automatically. Because of this, unwanted increases in MAU(Monthly Active Users) will be suppressed even if an applications is repeatedly re-installed. (Commonly referred to as a "reset marathon")

Step6(iOS):Audience feature settings

By using IDFA, it's possible to understand the gender and age distribution of your users.

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

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

Open the 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.
* When using Unity SDK 1.9 or later, even if this feature is not enabled, if the SmartBeat Setting "Log Redirect Prefix" is set, logs will be saved internally by the SDK and sent with crash reports.

How to activate

Open the 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.7 Automatic breadcrumb

Normal operations and status change events will be automatically recorded as breadcrumbs.
Combined with breadcrumbs dropped using leaveBreadcrumb(), the most recent 128 breadcrumbs will be sent with crash data to the SmartBeat servers.

How to activate

Open SmartBeat Settings and check the Auto Breadcrumb checkbox. (Enabled by default)

3.8 How to set up Unity error grouping exclusions

Although SmartBeat groups errors by their cause, if device specific information is included in the username, errors with the same cause may be put into separate groups. For this, please consider the following cases

How to set up Unity error grouping exclusions

3.9 Using signal handlers other than SmartBeat (Android)

Normally, SmartBeat terminates the process immediately after processing a signal crash, but if you want handlers registered before SmartBeat processing to also process signals, enable Call other SIGNAL Handlers. (e.g., if you want to check the SIGNAL error information in logcat, etc.)

How to activate

In the Unity menu bar, go to SmartBeat > Preferenece > Android and enable “Call other SIGNAL handlers[?].”

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) Combined with automatic breadcrumbs, the most recent 128 breadcrumbs will be sent with crash data to the SmartBeat servers.
void leaveBreadcrumb(string breadcrumb, Dictionary<string, string> metas)
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.