iOS SDK

1. 대응 OS버전

이 SDK는 iOS4.3 이후의 환경에서 동작했습니다.

2. iOS Project에 SDK를 임포트 하는 방법

Step1:SDK의 적용

  • CocoaPods
  • 매뉴얼 인스톨
Podfile에 아래의 행을 추가해 주세요.

pod 'SmartBeat-bitcode'

※중복 유저 카운트 방지설정을 하는 경우에,'SmartBeat-bitcode'의 대신하여 'SmartBeatPlus-bitcode'을 기재 해 주세요.
※iOS6 이전 버젼의 서포트 하는 경우에는 bitcode무효화 한 버전(SmartBeat, SmartBeatPlus)을 지정해 주세요.

그 이후 이하의 커맨드를 실행하여 주세요.

$ pod install
$ pod update

또한,이후SDK의 버전을 갱신하는 경우에는 pod update을 실행 하는 것 뿐이기 때문에 버전업이 실시 가능합니다.
또한 SmartBeat의 헤터를 읽어 들이는 것을 SmartBeatPlus/SmartBeat.h로 변경하여 주세요.

//#import <SmartBeatFramework/SmartBeat.h>
#import <SmartBeatPlus/SmartBeat.h>
아래에서 SmartBeat SDK를 다운로드하고 unzip하십시오.


다른 형식의 SDK는 여기 에서 다운로드하십시오.

먼저, SmartBeatFramework.framework를 임의의 폴더에 복사합니다.
Xcode를 기동하고, 대상의 Target을 선택합니다. [General]->
[Linked Frameworks and Libraries]상에서 [+]을 클릭하고,
Add Other에서 SmartBeatFramework.framework를 선택하고,
추가합니다.
주의: Xcode 5.0.2의경우

cocos_ios_1

또한, 표준으로 포함되어 있는 아래의 framework를 추가합니다.

  • SystemConfiguration.framework
  • CoreTelephony.framework
  • CoreGraphics.framework
  • OpenGLES.framework
  • AdSupport.framework(유저 카운트 수 중복방지 기능을 이용할 경우에 추가합니다. deploy타겟으로써 iOS6.0보다 이전 버전도 대상으로 하는 경우에는 “Optional”로 추가해 주세요.)
  • libz.tbd 또는 libz.dylib(SDK버전 1.20이후)

Step2:API키의 설정

Xcode의 대상에 Project의 AppDelegate.m을 열고 아래의 import문을 추가합니다.

#import <SmartBeatFramework/SmartBeat.h>

SmartBeat의 초기화 API를 -application:didFinishLaunchingWithOptions:의
처음에 추가합니다. [API키]에 관해서는 콘솔보다 Project 작성시에 발행된 키를 설정합니다.

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

※App Extension의 경우、Extension과 Containing App에 다른 API 키를 사용하여 구현할 필요가 있습니다. Containing App쪽에는 일반적인 App처럼 AppDelegate에 구현 합니다.
Extension쪽에는 AppDelegate를 작성할 수 없기 때문에, ViewController의 initWithCoder로부터 SmartBeat를 초기화 합니다.
initWithCoder가 구현되지 않았을 경우에는 아래와 같이 구현합니다.

//또한, 표준으로 포함되어 있는 아래의 framework를 추가합니다.
- (id)initWithCoder:(NSCoder *)coder
{
    self = [super initWithCoder:coder];
    [SmartBeat startWithApiKey:@"API키 for Extension"];
    return self;
}

Step3:유저 카운트 수 중복 방지

SDK버전 1.18이후

유저 수 집계에 IDFA를 사용하여 동일한 유저의 중복된 카운트를 방지합니다. 따라서 App의 재설치를 반복하더라도 불필요한 MAU(Monthly Active Users)수의 증가를 막을 수 있습니다.

※ 중복된 유저의 카운트를 막는 설정을 유효화하는 것으로 오디언스 기능도 유효화 됩니다.
※ 이 기능은 iOS 6.0이후 버전을 이용하는 유저 카운트에만 유효합니다.

이 기능을 유효화하지 않는 경우에는 아래의 순서가 불필요합니다.

  • CocoaPods
  • 매뉴얼 인스톨
하기 내용 처럼 Podfile에 기재하는 패키지명을「SmartBeat-bitcode」에서「SmartBeatPlus-bitcode」로 변경해 주세요.

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

이어서 , 설정 반영을 위해

$ pod install
$ pod update

을 실행해 주세요.
※bitcode무효 버전을 이용하는 경우에는 「-bitcode」가 없는 패키지를 지정해 주세요.

SmartBeatIdfa.framework를 추가

Step1과 동일한 상태에서 Xcode에서[General] -> [Linked Frameworks and Libraries]상에서 [+]를 클릭하고、Add Other로부터SmartBeatIdfa.framework를 선택해 Framework를 추가해 주세요.

※ SmartBeatFramework.framework와 SmartBeatIdfa.framework가 모두 필요합니다.

sb_idfa_framework

linker 옵션 추가

Xcode에서 대상이 되는 Target을 선택한 뒤, [Build Settings]의 [Other Linker Flags]에 아래의 내용을 추가해 주세요.

-force_load /Framework를 둔 폴더의 위치/SmartBeatIdfa.framework/SmartBeatIdfa

linker_flags

확인 방법
SDK버전 1.25이후

아래의 API를 호출하여 중복 사용자 계정 방지 설정이 정상적으로 적용되어 있는지 확인할 수 있습니다.

BOOL ok = [[SmartBeat shared] isReadyForDuplicateUserCountPrevention];

위의 API가 NO를 반환하는 경우, 필요한 Framework가 올바르게 적용되어 있지 않을 가능성이 있습니다. 자세한 내용은 SDK가 출력하는 에러 로그를 참조하시기 바랍니다("isReadyForDuplicateUserCountPrevention"이 포함된 로그가 NSLog로 출력됩니다).

3. 옵션 기능

이번 절에서는 추가 기능에 관해서 기술합니다. App으로부터 API를 호출하면 이러한 추가기능을 유효로 할 수 있습니다.

메인 쓰레드이외의 쓰레드로 부터 API 불러오기에 대해서

SDK버전1.22.6 보다 전 버전에서는 SBLog,leaveBreadcrumb,logException의API를 메인 쓰레드이외의 쓰레드로 부터 불러오는 경우에는 쓰레드가 파기될때까지 API내부에서 사용한
내부에서 사용한 메모리가 해방되지 않고 남아서 돌고 있는 경우가 있습니다.장시간 존재하는 쓰레드로 부터 불러오는 경우에는 @autoreleasepool로 감춰두도록 하여 주세요.
※SDK버전1.22.6 버젼이후에는 아래의 대응이 필요 없습니다.

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

3.1 화면캡쳐 기능(비OpenGL ES)

본 기능을 유효화하면 Crash가 발생되기 까지의 화면을 확인할 수 있습니다.
SDK에서는 App 표시중의 최신화면을 정기적으로 캐치하여, Crash 발생시에 최신 1장을 SmartBeat 서버로 보냅니다.
※OpenGL ES로 드로잉 할 경우, 3.2 장을 참고해 주세요.
※App Extension에서는 동작하지 않습니다.

유효화 방법

아래의 코드를 SmartBeat 초기화 후에 부르면 유효화 할 수 있습니다.

[[SmartBeat shared] enableAutoScreenCapture];
캡쳐 대상 외의 View를 등록

유저 개인 정보를 표시하는 View를 포함하는 경우 등, 화면을 캡쳐하고 싶지 않는 경우,
아래와 같이 View의 Tag를 등록하면 화면 캡쳐 대상에서 제외시킬 수 있습니다.
지정한 View를 포함하고 있는 화면은 캡쳐되지 않습니다.

[[SmartBeat shared] addSensitiveViewTag:sensitiveView.tag]

※대상의 View에 미리 임의의 Tag를 설정해둘 필요가 있습니다.(0 이외의 값)
※또한, 제외시킬 경우에는 removeSensitiveViewTag를 이용할 수 있습니다.

참고
SDK 버전 1.26 이후
  • ※App Extension에서는 동작하지 않습니다.
  • OpenGL ES에서 표시된 화면 캡처가 불가합니다. OpenGL ES를 사용하실 때는 화면 캡쳐 기능(OpenGL ES) 방법을 사용해 주십시오.
  • 본 기능은 Whitelist 에 등록된 단말기 및 iOS 버전에서만 사용할 수 있습니다.
  • 화면 구성이 복잡한 경우 등에는, 캡처 처리가 스킵될 수 있습니다.

3.2 화면 캡쳐 기능(OpenGL ES)

OpenGL ES로 드로잉한 화면을 캡쳐 하는 경우、드로잉 루프의 presentRenderbuffer:를
부른 직후에 아래와 같이 코드에 추가해 주세요.

유효화 방법

아래와 같이 presentRenderbuffer의 전 후에 API를 불러 주세요.
beforePresentRenderbuffer로 보낼 인수는 OpenGL ES 드로잉을 보낼 UIView 를 지정해 주세요.

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

※현 시점에서는, OpenGL ES 1.1은 서포트 되지 않습니다. 호출하면 무시 됩니다.
※이 기능은 Whitelist에 등록된 단말만 동작합니다. 5장 참조

추가 API

임의의 디바이스를 whitelist에 추가할 경우, 아래의 API를 이용하면 추가가능합니다.

[[SmartBeat shared] whiteListModelForOpenGLES:모델명];

[모델명]은 iOS의API(sysctlbyname함수에 hw.machine를 지정)로부터 취득한 값을 설정할 수 있습니다.

3.3 Catch한 Exception의 보존

App이 캐치한 Exception을 기록할 수 있습니다.

유효화 방법
@try {
    [self doSometingAndThrow];
}
@catch (NSException *exception){
     [[SmartBeat shared] logException:exception];
}
@finally{
}

3.4 로그 출력

SDK버전 1.20이후

단말 로그에 출력하지 않고、로그를 수집할 수 있습니다.
※iOS 10.0이후에서는 3.5장의 NSLog출력 기능을 유효로 하더라도 로그를 크래시 데이터에 포함시킬 수 없습니다. 대신에 이 기능을 사용할 것을 추천합니다.
※64KB 미만일 경우에는 최대 500행、그 외의 경우에는 64KB까지 최신 로그를 취득합니다.
※3.5장의 NSLog출력 기능을 유효로 할 경우、iOS 10.0보다 이 전의 단말에서는 이 기능에 의한 로그는 크래시 데이터에 포함되지 않고, NSLog에 의한 로그만이 크래시 데이터에 포함됩니다.

유효화 방법

아래의 API호출을 구현하여 로그를 보존할 수 있습니다.

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

또는

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

Swift에서는 getVaList를 사용해 아래와 같이 호출해 주세요.

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

앱의 Prefix.pch에 아래와 같은 매크로를 정의하면 기존의 NSLog호출 장소에서 SBLog에도 로그를 전송할 수 있습니다.

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

3.5 NSLog출력

NSLog의 출력을 Crash 데이터에 포함시킬 경우에는, NSLog출력기능을 유효화해 주세요.
※iOS 10.0이후에서는 이 기능을 유효로 하더라도 NSLog를 크래시 데이터에 포함시킬 수 없습니다.
대신에 3.4장의 로그 출력 API를 사용할 것을 추천합니다.

※64KB 미만일 경우에는 최대 500행、그 외의 경우에는 64KB까지 최신 로그를 취득합니다.
※이 기능을 유효로 한 경우, iOS 10.0보다 이전의 단말에서는 3.4장의 로그 출력API에 의한 로그는 크래시 데이터에 포함되지 않고, NSLog에 의한 로그만이 크래시 데이터에 포함됩니다.

유효화 방법
[[SmartBeat shared] enableNSLog];

3.6 유저ID 설정

대상의 App이 관리하는 사용자를 식별할 수 있는 ID가 이미 있는 경우, 기존의 것을 이용하여 설정할 수 있습니다.
설정된 사용자 ID는 Crash와 함께 SmartBeat서버에 보내집니다.
어떤 유저의 Crash가 발생했는지 등 관리콘솔상에서 확인할 수 있습니다.

유효화 방법

아래의 API호출을 구현하면 설정 가능합니다.

[[SmartBeat shared] setUserId:@"user001"];

3.7 확장 정보

Crash정보로 확장 정보를 부여할 수 있습니다. App에 따라서는 사용자가 설정한 정보와
App이 내부에 보존하고 있는 정보가 Crash해석에 도움이 됩니다.

유효화 방법

아래의 API호출을 구현하면, 임의의 키 이름과 값을 세트로 Crash 데이터와 함께 보존할 수 있습니다.

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

데이터는 NSObject를 계승한 임의의 데이터를 설정할 수 있고, NSObject의 description 메소드로 취득할 수 있는 데이터가 보존 됩니다. (SDK version 1.8이후) 또는 값을 변경하고 싶은 경우에는 같은 키 이름을 추가하면, 새로운 값으로 덮어씌워 집니다.

3.8 breadcrumb기능

임의의 포인트로 breadcrumb를 남기면 에러가 발생할 때까지 사용자가 조작한 내용과 화면 이동내역을 수집할 수 있습니다.

유효화 방법

기록을 남기고 싶은 장소에 아래의 API를 호출해 주세요.

[[SmartBeat shared] leaveBreadcrumb:@"game scene 1"];

breadcrumb는 마지막에 기록되어진 것을 포함하여 최대 16개까지 보존할 수 있습니다.
예를 들면, [맵 화면]→[게임 화면]→[설정 화면]등과, 키가 되는 화면의 이동 시점에
남길 경우, 에러 직전에 사용자가 어떻게 화면을 이동했는지 알 수 있습니다.

3.9 에러 수집 유효화・무효화 변경

SDK버전 1.6이후

초기상태를 에러수집 무효화하고, 도중에 에러 수집을 유효화로 변경하고싶을 경우에 이용할 수 있습니다.

유효화 방법

API키 설정(위의 Step2)에서 쓴 API 대신 아래의 API를 기동 시 유효화할 지 무효화할 지 설정해 주세요.

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    BOOL enableSmartBeat = NO; //무효화한 상태로 기동할 경우에는 NO
    [SmartBeat startWithApiKey:@"API키" withEnabled:enableSmartBeat];
    //your code

나중에 유효로 하고 싶을 경우, 임의의 장소에 아래의 코드를 호출 해 주세요. 호출 되어진 이후에 발생한 에러를 수집할 수 있습니다.

[[SmartBeat shared] enable];

또한, 유효화・무효화의 설정은 매 기동시에 SmartBeat startWithApiKey: withEnabled: 로 설정해 주세요.

3.10 백그라운드 어플리의 기동시 통지에 대해

SDK버전 1.22이후

SmartBeat에서는 화면의 표시(Activity.onResume())을 어플리 기동으로 하고 있습니다.이 때문에 백 그라운드 동작이 메인이 되는 어플리에서는 유니크 유저가 적게 카운트 되어 크래쉬 율이 높게 표시되고 맙니다.
본API을 어플리 백 그라운드 테스크의 처리개시의 타이밍에서 불러 오는 것으로 유니크 유저 수를 좀 더 정확하게 집계하는게 가능하게 됩니다.

3.11 dSYM 자동업로드

dSYM자동업로드 스크립트를 Xcode의 Run Script에 도입하면, 매 빌드 시 자동으로 dSYM을 업로드할 수 있습니다.

상세한 도입방법 및 스크립트는 여기로부터 다운로드 해 주세요.

3.12 오디언스 기능

유저 식별자로서 Advertising ID for Android 또는 IDFA for iOS를 사용하여
애플리케이션을 이용하는 유저의 남여비와 연령분포를 확인할 수 있습니다.

중복된 유저의 카운트를 막는 설정을 유효화하는 것으로 오디언스 기능도 유효화 됩니다.
중복된 유저의 카운트를 막는 설정에 대해서는 여기를 참조해 주세요.

4. 리소스 소비

아래는 SDK도입에 의한 리소스 소비계측 결과입니다.

단말 항목 SDK 도입 시
(화면 캡쳐 무효)
SDK도입 시
(화면 캡쳐 유효)
iPhone5S
iOS7.0.4
메모리 소비량
CPU 부하
약1.0MB증가
증감 없음
약1.7MB증가
평균 약2.3%증가
iPhone4
iOS6.0.1
메모리 소비량
CPU 부하
약1.0MB증가
증감 없음
약1.3MB증가
평균 약4.8%증가

※화면캡쳐를 유효로 하고 싶은 경우, 화면의 화소수에 따른 메모리 소비량이 증가
※화면캡쳐를 유효로 하고 싶은 경우, 화면 취득, 인코딩 처리, 보존 처리가 들어가기 때문에 CPU 부하가 증가

5. OpenGL ES 화면캡쳐대상 단말

OpenGL ES 화면캡쳐기능의 지원대상을 기술 합니다.

디바이스명 hw.machine SDK버전
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 -

6. 변경 내용

개정일 변경 사항
2014년 2월 4일 초판 발행
2014년 3월 17일 추가한 Framework으로부터 CoreLocation.framework를 삭제
화면캡쳐 최대보존수를 3장으로 변경
2014년 4월 4일 추가할 Framework에、CoreGraphis.framework및、OpenGLES.framework를 추가
OpenGL ES2.0로 드로잉한 화면캡쳐를 지원(SDK버전 1.3이후)
2014년 5월 7일 3.1 화면캡쳐기능의 보충설명 추가
2014년 5월 19일 대상 OS버전을 iOS4.3으로 변경(SDK버전 1.4이후)
2014년 6월 27일 [3.9 에러 수집 유효화・무효화 변경]을 추가(SDK버전1.6 이후)
2014년 7월 19일 [3.10 dSYM 자동업로드]를 추가
2014년 8월 4일 [3.7 확장정보]의 보충내용을 변경
2014년 8월 29일 [3.8 breadcrumb기능]을 추가
2015년 1월 26일 [Step2:API 키 설정]에서 App Extension의 경우, 초기화에 관한 설명 추가
2016년 1월 6일 [Step3:IDFA에 의한 유저 카운트의 유효화]를 추가(SDK버전 1.18이후)
2016년 3월 14일 [5. OpenGL ES 화면캡쳐대상 단말]을 추가
2016년 4월 20일 [3.12 오디언스 기능]을 추가
2016년 11월 21일 [2. iOS의 Project로의 SDK 삽입 방법]에 필요한 라이브러리 추가
[3.2 화면 캡쳐 기능(OpenGL ES)]을 추가하는 API를 추가
[3.4 로그 출력]을 추가(SDK버전 1.20이후)
[3.5 NSLog출력]의 보충 설명을 추가
[5. OpenGL ES화면 캡쳐 대상 단말]의 리스트 갱신
2017년 4월 18일 [3.10 백그라운드 어플리의 기동시 통지에 대해]을 추가
2018년 5월 16일 [5. OpenGL ES화면 캡쳐 대상 단말]의 리스트 갱신
2019년 3월 4일 [Step3:유저 카운트 수 중복 방지]을 변경