Android SDK

1. Supported OS versions

The SmartBeat SDK supports Android 2.2 and above.
※ Crash reporting for the Android NDK(C/C++)works on Android 2.3 and above.
※ OpenGL ES screenshot function works on Android4.0 and above.

2. Initialize

Step1:Import Libraries

Download SmartBeat SDK from below and unzip it.


Download SDKs in other formats here .

  • Android Studio
  • Eclipse + ADT
Copy the smartbeat-android-<version>.jar to your Project’s libs folder.
If this folder does not exist, you need to manually create it.

Open build.gradle in your project, and add the following line to the dependencies section.

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}
Copy the smartbeat-android-<version>.jar to your Project’s libs folder.
If this folder does not exist, you need to manually create it.

Step2:Set Permissions

Add the following line

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

to your app’s AndroidManifest.xml file. If this permission already exists, you don’t need to add it.
SmartBeat uses this permission to send the crash reports and performance metrics.

Step3:Set API Key

Add below codes in your inherited class from the Application class. If there is no inherited class, create and declare it in a manifest file.

In order to use SmartBeat’s API, import com.smrtbeat.SmartBeat class:

import com.smrtbeat.SmartBeat;

Add SmartBeat’s initialization API in onCreat() of Application.You can get API key in your SmartBeat console (>Settings > General Settings > API key for this app)

public class MyApplication extends Application {
    @Override
    public void onCreate () {
        SmartBeat.initAndStartSession(this, "API key");
    }
}

Step4:Duplicate user count prevention

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-ads-identifier into dependencies as below. Ensure the version number of play-services-ads-identifier is 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.+'
}

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
SDK Version 1.21 and up

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

boolean ok = SmartBeat.isReadyForDuplicateUserCountPrevention();

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

Step5:Set the SmartBeatHandler in your each activity(you can skip this step if your target is only for Android4.0(API level 13) and above)

Add the following code in onResume(), onPause() in your each activity.

import com.smrtbeat.SmartBeat;

@Override
protected void onResume(){
    super.onResume();
    SmartBeat.notifyOnResume(this);
    //your code
}

@Override
protected void onPause(){
    super.onPause();
    SmartBeat.notifyOnPause(this);
    //your code
}

Step6:ProGuard Symbolication(only for users who use ProGuard)

If you use ProGuard, add the following lines to your ProGuard configuration file.

-dontwarn com.smrtbeat.**
-keep class com.smrtbeat.** { *; }

Typically this is the proguard-project.txt or proguard-rules.pro file in your project's root directory.

Add the following if you enabled duplicate user count prevention as described in Step4.

-dontwarn com.google.android.gms.**

※ The mapping.txt file may be uploaded via the console or via script.

3. Extra functions

3.1 Screenshots function (non OpenGL ES)

When this function is activated, you can get some application’s screenshots just before the crash. SmartBeat SDK keeps latest screenshot and send them to SmartBeat Server when a crash occurs.
You can skip this section if it’s rendered by OpenGL ES. Please see section 3.2.

How to activate
Usage only for Android4.0(API level ver14) and above.

You only need to add this code in onCreate() method of Application class.

SmartBeat.enableAutoScreenCapture();

Screen shots will be captured between onResume and onPause of Activity. You can call this API before API Level 13, but it doesn't work.

Usage for Android 2.2 and above.

You need to add this code in onCreate() method of Application class,

SmartBeat.enableAutoScreenCapture();

and also add this code in onResume() and onPause() of your each activity.

@Override
protected void onResume(){
    super.onResume();
    SmartBeat.notifyOnResume(this);
    //your code
}

@Override
protected void onPause(){
    super.onPause();
    SmartBeat.notifyOnPause(this);
    //your code
}

SmartBeat SDK’s functions mainly works on internally created new thread except for taking screenshot’s function which goes on UI thread. Screen capturing of SurfaceView is not supported at present.

Set a specific view forbidden to capture

If your application has a specific view(activity) which is not suited to be captured (ex. Entering page of users’ personal information), you can set it “forbidden” to be captured.
Example: Set “MyActivity” forbidden to be captured.

SmartBeat.setActivityAsSensitive(MyActivity.class.getName());

3.2 Screenshots function (OpenGL ES)

When this function is activated, you can get some application’s screenshots rendered by OpenGL ES just before the crash. SmartBeat SDK keeps latest screenshot and send them to SmartBeat Server when a crash occurs.
*1 Android 4.0 and above are supported. (Nothing is happen if it is implemented in your application run on less android os version.)
*2 OpenGL ES2.0 and above are supported.
*3 This feature works on supported hardware platforms that are listed in whitelist. See section 6 as reference.

How to activate

You can activate this feature after implementing 3 APIs as following;

Set OpenGL ES version.

Set OpenGL ES version as 1st argument. This must be the same as the version initialized by GLSurfaceView.setEGLContextClientVersion(). It must be called from Renderer.onDrawFrame(GL10 gl) that is subclass of GLSurfaceView.Renderer.
Also set true as 2nd argument if StencilBuffer is used. If it is true, capture function is available on Android 4.3 and above.

SmartBeat.onSurfaceCreated(version, useStencilBuffer);
Call APIs before/after drawing frame.

Implement following code in onDrawFrame(final GL10 gl) in your class extends GLSurfaceView.Render.

@Override
public void onDrawFrame(final GL10 gl) {
    SmartBeat.beginOnDrawFrame();
    //draw currrent frame.
    SmartBeat.endOnDrawFrame();
}
Additional API

Also you can add board name into whitelist. Call following API to enable this feature on additional device. Board names can be acquired by using Build.BOARD.

SmartBeat.whiteListBoardForOpenGLES(board name);

If board name is added, sdk will try to take OpenGL ES screenshot. It means it might fail by some reasons. You can also check by return value of beginOnDrawFrame() whether if it can be started successfully.

3.3 Log Handled Exceptions

SmartBeat supports handed exceptions logging.

How to activate
try{
    doSometingAndThrow();
} catch(MyException e){
    SmartBeat.logHandledException(getApplicationContext(), e);
}

If you cannot get an application context, it can be set to null as a first parameter. In this case, you cannot get some parts of information(ex. network circumstance) included in Context.

3.4 Logging

SDK Version 1.16 and up

Logs will be gathered internally, and not output to the device log.
*The most recent 64KB or 500 lines of log will be included in crash reports.
*If the Section 3.5 LogCat support feature is enabled, the data from this feature will not be used, and LogCat data will be included in the crash report.

How to use

Output logs using the following API calls.

SmartBeat.log("message");

To output logs from NDK(C/C++)use the following code to send logs to the API using JNI. An example cpp file is included in the SDK.

void SmartBeat_log(JNIEnv* env, const char* msg)
{
    jclass cls = env->FindClass("com/smrtbeat/SmartBeat");
    if (cls == NULL)
        return;
    jmethodID method = env->GetStaticMethodID(cls, "log", "(Ljava/lang/String;)V");
    if (method == NULL) {
        env->DeleteLocalRef(cls);
        return;
    }
    jstring str = env->NewStringUTF(msg);
    if (str == NULL) {
        env->DeleteLocalRef(cls);
        return;
    }
    env->CallStaticVoidMethod(cls, method, str);
    env->DeleteLocalRef(str);
    env->DeleteLocalRef(cls);
}

3.5 LogCat support

SmartBeat can also include LogCat with crash/exception data.
*The most recent 64KB or 500 lines of log will be included in crash reports.
*If the this feature is enabled, the data from section 3.4 Logging will not be used, and only LogCat data will be included in the crash report.

How to activate
SmartBeat.enableLogCat();

If you set argument, you can get filtered log.

SmartBeat.enableLogCat(“*:W”);

You can find the detail of filtering rule in the following android site.
http://developer.android.com/tools/debugging/debugging-log.html#filteringOutput

If you want to support LogCat feature with Android prior to version 4.1, add this line:

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

in your app's AndroidManifest.xml.

3.6 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.setUserId("user001");

3.7 Add Extra data

You have another option to add extra custom information into the crash/expection 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.addExtraData("key1", "value1");
SmartBeat.addExtraData("area", "Tokyo");

If you want to add your custom map data, you can use HashMap class:

Map<String, String> map = new HashMap<String, String>();
map.put("key1", "value1");
map.put("area", "Tokyo");
SmartBeat.addExtraData(map);

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

3.8 Breadcrumb function

Use of the breadcrumb feature makes it possible to know what status changes and operations occured leading up to an error.
Typical operations and status change events are automatically recorded Also, using an API from the app side allows recording of app specific status changes and operations.
Additionally, breadcrumb text can be up to 140 characters in length, with additional metadata, and the most recent 128 will be retained.
*In the event more than 140 characters are supplied, only the leading 140 characters will be retained.
*In the event the total size of the breadcrumb exceeds 1KB, it will be recorded without the specified meta-data.

How to active

To drop an additional breadcrumb (Leave a record of it) location, call the API shown below.

SmartBeat.leaveBreadcrumbs("game scene 1");

Alternatively, metadata may also be attached using the API shown below.

Map<String, String> meta = new HashMap<String, String>();
meta.put("key", "value");
SmartBeat.leaveBreadcrumbs("game scene 1", meta);

3.9 Disabling crash/exception report by default

SDK Version 1.6 and up

You can disable reporting crash/exception by default using following API.

How to

Initialize using following api instead.

public class MyApplication extends Application {
    @Override
    public void onCreate () {
        boolean enable = false; //false if it should be disabled by default, true otherwise.
        SmartBeat.initAndStartSession(this, "API Key", enable);
    }
}

Use following API to enable reporting crash/exception anytime it should be enabled.

SmartBeat.enable();

Because this setting is not persistent, you will need to set this flag every time the application is launched.

3.10 Background operation notification

SDK Version 1.18 and up

SmartBeat considers an application active when it is displayed on the screen (Activity.onResume()). For this reason, apps which primarily operate in the background have a decreased unique user count, and as a result, an abnormally high crash rate.
This API allows the app to notify the SmartBeat SDK of background operation, so a more accurate unique user count, and as a result, more accurate statistical data can be computed.

SmartBeat.notifyRunning();

3.11 Auto upload symbol files

By embedding the provided “.so Upload script” or “.so Upload Jenkins plugin” in your build environment, a symbol file for C/C++ will be automatically uploaded for every build.

For more details, please check the provided readme file.

What to upload
  • NDK
  • CMake
Upload the libs folder in your application's project.
Upload the build/intermediates/cmake/{debug|release}/obj folder (choose debug or release situationally) in your application's module.

3.12 Auto upload mapping.txt

By integrating the ProGuard mapping upload script into your build script, it's possible to upload mapping information automatically.

※The script is a sample. Please modify it to suit the needs of your build environment. For details, please view the readme file in the script archive.

3.13 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.

4. Other Permissions

Some of the data which the SmartBeat SDK collects requires extra permissions.
If there is no permission to access this data, it will be displayed as “no permission” in Device Information in the SmartBeat console.

Permission Data
android.permission.ACCESS_NETWORK_STATE Status of network

5. Resource usage

The resource usage of SmartBeat SDK is as follows:

Device Items Resource usage
w/o Screenshot function
Resource usage
w/ non-OpenGL
Screenshot function
Resource usage
w/ OpenGL
Screenshot function
Nexus7 (2012)
Android 4.4.2
Mem. usage
CPU usage
about 1.7MB up
no change
about 4.3MB up
ave. 6.4% up
about 5.3MB up
ave. 4.4% up
Xperia AX
Android 4.1.2
Mem. usage
CPU usage
about 0.6MB up
no change
about 5.0MB up
ave. 3.0% up
about 5.9MB up
ave. 4.1% up
Xperia Ray
Android 2.3.4
Mem. usage
CPU usage
about 1.1MB up
no change
about 3.4MB up
ave. 9.0% up
not supported

When screenshots function is active,
- memory usage increases based on pixels of screenshots.
- CPU usage increases due to processes of getting, encoding and sending screenshots.

6. Supports devices for OpenGL ES screenshot

Following devices/platforms are supported to take screenshot for OpenGL ES

Device name Build.MODEL Tested OS
version
SDK
version
NEXUS 5 Nexus 5 4.4 1.8 -
AQUOS PAD SH-06F SH-06F 4.4.2 1.8 -
AQUOS ZETA SH-04F SH-04F 4.4.2 1.8 -
Xperia ZL2 SOL25 SOL25 4.4.2 1.8 -
Xperia Z1 SOL23 SOL23 4.4.2 1.13 -
Xperia Z1 f SO-02F SO-02F 4.4.2 1.13 -
HTC J butterfly HTL23 HTL23 4.4.4 1.13 -
isai LGL22 4.4.2 1.13 -
Galaxy S5 SM-G900K 5.0 1.14 -