iOS SDK

1. Supported OS version

SmartBeat SDK supports iOS6.0 and above.

2. Initialize

Step1:SDK Installation

  • CocoaPods
  • Manual Installation
Add the Podfile using the command below.

pod 'SmartBeat-bitcode'

* In the event you are using duplicate user count prevention, please use 'SmartBeatPlus-bitcode' instead of 'SmartBeat-bitcode'.
* If you have disabled bitcode, please use the bitcode free version. (SmartBeat, SmartBeatPlus)

Next, execute the following commands:

$ pod install
$ pod update

When necessary, the 'pod update' command may be used to update the SDK to the latest version.

Also, When loading the SmartBeat header file, use SmartBeatPlus/SmartBeat.h in place of SmartBeatFramework/SmartBeat.h

//#import <SmartBeatFramework/SmartBeat.h>
#import <SmartBeatPlus/SmartBeat.h>
Download SmartBeat SDK from below and unzip it.

Download SDKs in other formats here .

Copy SmartBeatFramework.framework to any folder.
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 press “Add Other....” In the dialog box that appears, go to the framework's location and select SmartBeatFramework.framework.

Example: Xcode 5.0.2

cocos_ios_1

In addition, you will need to add the following standard frameworks.

  • SystemConfiguration.framework
  • CoreTelephony.framework
  • CoreGraphics.framework
  • OpenGLES.framework (Only needed if you are using OpenGL ES screen capture functionality)
  • AdSupport.framework (Add if you use duplicate user count prevention. Add by "Optional" if your application supports before iOS 6.0 as deploy target.)
  • libz.tbd or libz.dylib (SDK Version 1.20 and up)

Step2:Set API key

Import the SmartBeat header in your application delegate's implementation file (AppDelegate.m):

#import <SmartBeatFramework/SmartBeat.h>

Start SmartBeat in your AppDelegate's application:didFinishLaunchingWithOptions: method.
You can get API key in your SmartBeat web console (>Settings > General Settings > API key for this app)

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

*In case of "App Extension", Api keys shall be issued for each Extension and Containing App and implemented in each. In an Extension, you can use the Extension's view controller's initWithCoder method instead. If it is not implemented yet, it can be implemented as follows:

//Initialize for App Extension
- (id)initWithCoder:(NSCoder *)coder
{
    self = [super initWithCoder:coder];
    [SmartBeat startWithApiKey:@"API Key for Extension"];
    return self;
}

Step3:Duplicate user count prevention

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.

  • CocoaPods
  • Manual Install
As shown below, change the Podfile package name from "SmartBeat-bitcode" to "SmartBeatPlus-bitcode".

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

Next, apply the settings using the following commands.

$ pod install
$ pod update

* If you do not use bitcode, you may use SmartBeatPlus instead of SmartBeatPlus-bitcode.

Add SmartBeatIdfa.framework

Like Step1, in the Build Phases tab in the Xcode, expand the Link Binary With Libraries section, press the “+ button”, then press “Add Other....” in the dialog box that appears, go to the framework's location and select SmartBeatIdfa.framework.

* Both SmartBeatFramework.framework and SmartBeatIdfa.framework should be added.

sb_idfa_framework

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 /PathToParentDirOfFramework/SmartBeatIdfa.framework/SmartBeatIdfa

linker_flags

How to check
SDK Version 1.25 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 shared] isReadyForDuplicateUserCountPrevention];

If the above API returns NO, 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.

Calling the API from the non-main thread

On SDK Versions prior to 1.22.6, when calling the SBLog, leaveBreadcrumb and logException APIs from non-main threads would cause memory allocations within the SmartBeat API to not be released until thread termination. For long running threads, please surround such calls with an @autoreleasepool.
*SDK Versions 1.22.6 and later do not require this step.

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

3.1 Screenshots function (non-OpenGL ES)

When this function is activated, you can get some application’s screenshots just before crash occurs. SmartBeat SDK keeps latest screenshot and send them to SmartBeat Server when a crash occurs.
If you render using OpenGL ES, you can skip this section and see section 3.2.

How to activate

Add this code after SmartBeat initialization.

[[SmartBeat shared] enableAutoScreenCapture];
Adding view tag as sensitive view

If your application has sensitive view e.g. displaying personal information, taking screen capture can be skipped by registering its view's tag as following.

[[SmartBeat shared] addSensitiveViewTag:sensitiveView.tag]

*Any value except for zero shall be set as tag of sensitive view.
*removeSensitiveViewTag can be used to unregister as sensitive view.

Notes
SDK Version 1.26 and later
  • Screen capture on App Extension is not supported
  • Capturing screens drawn with OpenGL ES is not supported. Please see the section "Screenshots function (OpenGL ES)" for instructions when using OpenGL ES.
  • This function only operates when using a Whitelisted device and iOS version.
  • Screen capture processing may be skipped if, for example, the screen structure is very complex.

3.2 Screenshots function (OpenGL ES)

How to activate

To begin, install SmartBeatGLESCapture using the instructions below.

  • CocoaPods
  • Manual Install
Add SmartBeatGLESCapture-bitcode to your Podfile as shown below

pod 'SmartBeat-bitcode'
pod 'SmartBeatGLESCapture-bitcode'

* When using SmartBeatPlus-bitcode, add SmartBeatPlusGLESCapture-bitcode.
* If you are not using bitcode, you may use SmartBeatGLESCapture instead of SmartBeatGLESCapture-bitcode.

Next, apply the settings using the following commands.

$ pod install
$ pod update
Add SmartBeatGLESCapture.framework

Like Step1, in the Build Phases tab in the Xcode, expand the Link Binary With Libraries section, press the “+ button”, then press “Add Other....” in the dialog box that appears, go to the framework's location and select SmartBeatGLESCapture.framework.

* Both SmartBeatFramework.framework and SmartBeatGLESCapture.framework should be added.

If you want to capture a view drawn by OpenGL ES, you need to call following API before and after presentRenderbuffer: method. In addition, set the UIview which OpenGL ES uses as a parameter of beforePresetnRenderbuffer: method.

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

*OpenGL ES 1.1 is not supported.
*Screen capture on App Extension is not supported
*This feature is only supported on devices registered in the whitelist. See section 5.

Additional API

Devices may be arbitrarily added to the whitelist using the API below.

[[SmartBeat shared] whiteListModelForOpenGLES:@"Model Name"];

Where Model Name is the string extracted from sysctlbyname when specifying hw.machine.

3.3 Log Handled Exceptions

SmartBeat supports handed exceptions logging.

How to activate
@try {
    [self doSometingAndThrow];
}
@catch (NSException *exception){
    [[SmartBeat shared] logException:exception];
}
@finally{
}

3.4 Logging

SDK Version 1.20 and up

Logs will be gathered internally, and not output to the device log.
*As of iOS 10, even if enabled, the section 3.5 Include NSLog feature will not function. This feature is recommended as an alternative.
*The most recent 64KB or 500 lines of log will be included in crash reports.
*If the Section 3.5 Include NSLog feature is enabled, on iOS prior to version 10, the data from this feature will not be used, and NSLog data will be included in the crash report.

How to use

Output logs using the following API calls.

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

Alternatively,

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

For swift, use getVaList as shown below.

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

By including the following fragment in your Prefix.pch, you can rewrite NSLog calls into SBLog calls.

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

3.5 Include NSLog

SmartBeat can also include LogCat with crash/exception data.
*As of iOS 10, even if enabled, this section's NSLog feature will not function. Section 3.4 Logging is recommended as an alternative.
*The most recent 64KB or 500 lines of log will be included in crash reports.
*If this feature is enabled, on iOS prior to version 10, the data from the section 3.4 Logging feature will not be used, and NSLog data will be included in the crash report.

How to activate
[[SmartBeat shared] enableNSLog];

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 shared] setUserId:@"user001"];

3.7 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:

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

*A string presented by description method will be saved.
*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 shared] leaveBreadcrumb:@"game scene 1"];

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

NSDictionary *metas = @{@"key":@"value"};
[[SmartBeat shared] leaveBreadcrumb:@"game scene 1" withMetas:metas];

*Cautions for calling this API from threads other than the main thread may be found here.

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 initializing by SmartBeat startWithApiKey: .

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    BOOL enableSmartBeat = NO; //NO if it should be disabled by default, YES otherwise.
    [SmartBeat startWithApiKey:@"API Key" withEnabled:enableSmartBeat];
    //your code

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

[[SmartBeat shared] 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.22 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 task processing, so a more accurate unique user count, and as a result, more accurate statistical data can be computed.

[[SmartBeat shared] notifyRunning];

3.11 Auto upload dSYMs

You can automatically upload dSYMs every build by using dSYM upload script in the Run Script section.

For more details on the script and how to use it, download the archive from here.

3.12 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. Resource usage

Resource requirements of the SmartBeat SDK:

Device Items Resource usage
w/o Screenshot function
Resource usage
w/ Screenshot function
iPhone5S
iOS7.0.4
Mem. usage
CPU usage
about 1.0MB up
no change
about 1.7MB up
ave. 2.3% up
iPhone4
iOS6.0.1
Mem. usage
CPU usage
about 1.0MB up
no change
about 1.3MB up
ave. 4.8% up

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.

5. Supports devices for OpenGL ES screenshot

Following devices are supported to take screenshot for OpenGL ES

Device name hw.machine SDK version
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 -