iOS SDK (Cocos2d-x)

1. 들어가며

이 도큐멘트는 iOS용 SmartBeat를 Cocos2d-x에 도입하기 위한 방법을 적었습니다.
동작이 검증된 Cocos2d-x(C/C++)버전은 2.1.4, 2.1.5, 2.2, 2.2.3, 3.1.1, 3.2이고, Cocos2d-JS 버전은 3.7, 3.8, 3.13.1입니다.

이 SDK가 대응하고 있는 Cocos2d-x상의 언어는 C/C++ 및 JavaScript입니다.
동작대상 iOS는 4.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 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의 iOS아래에 AppController.mm을 열어 아래의 import문을 추가합니다.

#import <SmartBeatFramework/SmartBeat.h>

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

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

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

3. Cocos2d-JS의 에러 취득

SDK버전 1.21이후

아래의 순서대로 JavaScript바인딩을 유효화 하는 것으로 Cocos2d-JS의 JavaScript쪽 에러를 취득할 수 있습니다.
※ 2장에 있는 내용을 따라하여 프로젝트에 SDK를 넣은 후, 아래의 순서를 따라해 주세요.
※ JavaScript 에러 취득은 Cocos2d-x v3.7 이상에서 대응하고 있습니다.
※ JavaScript를 사용하지 않는 앱은 아래의 순서가 필요하지 않습니다.

  • CocoaPods
  • 매뉴얼 인스톨

Podfile에서 SmartBeatJSBinding의 추가

Podfile에 아래의 행을 추가해 주세요.

pod 'SmartBeatJSBinding-bitcode'

이어서 , 설정 반영을 위해

$ pod install
$ pod update

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

SmartBeatJSBinding.framework의 추가

먼저, SmartBeatJSBinding.framework를 임의의 폴더에 복사합니다.
Xcode를 기동해서, 대상의 Target을 선택합니다. [General] → [Linked Frameworks and Libraries]상에서 [+]을 클릭하고, Add Other로부터 SmartBeatJSBinding.framework를 선택해 추가합니다.

SmartBeat JavaScript 바인딩 등록

프로젝트 폴더의 frameworks/runtime-src/Classes/AppDelegate.cpp를 열고、아래의 include문을 추가해 주세요.

#include <SmartBeatJSBinding/SmartBeatJSBinding.h>

AppDelegate::applicationDidFinishLaunching()안의、sc->start()를 부르기 전에 아래의 1행을 추가합니다.

bool AppDelegate::applicationDidFinishLaunching()
{
    ...
    sc->addRegisterCallback(...);
    sc->addRegisterCallback(...);
    ...
    sc->addRegisterCallback(SmartBeat::registerSmartBeatJSBinding); //이 부분을 추가
    sc->start();
    ...
}

4. 옵션기능

4.1 화면캡쳐 기능

이 기능을 유효화 하면 Crash발생시까지의 화면 이동을 확인할 수 있습니다.
SDK에서는 App표시중의 최신 화면을 정기적으로 캐치하여, Crash가 발생했을 때, 최신의 1장을 SmartBeat 서버에 보냅니다.
※이 기능은 Whitelist에 등록된 단말만이 동작합니다. 5장 참조

유효화 방법

Cocos2d-x에서 화면캡쳐 할 경우, 먼저 cocos2dx의 워크스페이스로부터
SmartBeatFramework를 참조할 수 있도록 설정합니다.
<2.x의 경우>
Xcode상에서、cocos2dx.xcodeproj의 워크스페이스 안의 cocos2dx의 타겟을 선택하고、
「Build Settings」의 탭을 선택한 후, [Search Paths]에 포함된 [Framework Search Paths]
에Step1에서 추가한 SmartBeatFramework.framework을 추가합니다.
<3.x의 경우>
Xcode상에서、cocos2d_libs.xcodeproj의 워크스페이스 안의 cocos2dx iOS의 타겟을 선택하고
[Build Settings]의 탭을 선택한 뒤, [Search Paths]에 포함된[Framework Search Paths]
에 Step1에서 추가한 SmartBeatFramework.framework을 추가합니다.

cocos_ios_2

<2.x의 경우>

예를 들면、cocos2dx의 루트 폴더 아래、external아래의 서브 폴더에
SmartBeatFramework.framework를 복사하고 있는 경우, 패스에
[$(SRCROOT)/../../external]를 설정하고、recursive합니다.

<3.x의 경우>

예를 들면、<App의 프로젝트 폴더>/cocos2d/external/ 아래,
SmartBeatFramework.framework를 복사하고 있는 경우, 패스에
[$(SRCROOT)/../external]를 설정하고、recursive합니다.

cocos_ios_2

계속해서 presentRenderbuffer의 호출 전후에 코드를 추가합니다.
<2.x의 경우>
/cocos2dx/platform/ios/EAGLView.mm을 열어서 아래와 같이 수정해 주세요.
<3.x의 경우>
/cocos/platform/ios/CCEAGLView.mm을 열어서 아래와 같이 수정해 주세요.

먼저、아래의 Import문을 추가해 주세요.

#import <SmartBeatFramework/SmartBeat.h>

계속해서、아래와 같이 presentRenderbuffer의 전후에 API
(beforePresentRenderbuffer / afterPresentRenderbuffer)를 불러 주세요.

cocos_ios_4

또한 , Xcode6 이후에 빌드할 경우, /cocos2dx/platform/ios/CCES2Render.m의「resizeFromLayer:layer」에 아래의 코드를 추가해 주세요. ※Xcode5로 빌드하는 경우이더라도 추가하여도 문제는 없습니다.

- (BOOL)resizeFromLayer:(CAEAGLLayer *)layer
{
    //Xcode6 + iOS8대응 추가코드
    glBindFramebuffer(GL_FRAMEBUFFER, defaultFramebuffer_);
    // Allocate color buffer backing based on the current layer size
    glBindRenderbuffer(GL_RENDERBUFFER, colorRenderbuffer_);

Cocos2d-x 3.7이상일 경우, /cocos/renderer/CCFrameBuffer.cppのFrameBuffer::clearAllFBOs()에 아래의 코드를 추가해 주세요.

void FrameBuffer::clearAllFBOs()
{
    //Cocos2d-x 3.7이상의 버전을 대응할 추가 코드 
    GLint currentFrameBuffer;
    glGetIntegerv(GL_FRAMEBUFFER_BINDING, ¤tFrameBuffer);
    for (auto fbo : _frameBuffers)
    {
        //Cocos2d-x 3.7이상의 버전을 대응할 추가 코드 
        fbo->_fbo = currentFrameBuffer;
        fbo->clearFBO();
    }
}
추가 API

임의의 디바이스를 whitelist에 추가하고 싶은 경우, 아래의 API를 이용해 주세요.

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

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

4.2 로그 출력

SDK버전 1.20이후

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

유효화 방법

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

■Objective-C
SBLog("String: %@, Integer: %d", "text", 1);

또는

va_list args;
va_start(args, format);
SBLogv(format, args);
va_end(args);
■ JavaScript
SmartBeat.log('message');

4.3 NSLog 출력

NSLog의 출력을 Crash 데이터에 포함시킬 경우에, NSLog출력 기능을 유효로 해 주세요.
(이 API 호출은 2장 Step2에서 편집한 AppController.mm에서 해 주세요.)
※iOS 10.0이후에서는 이 기능을 유효로 하더라도 NSLog를 크래시 데이터에 포함시킬 수 없습니다. 대신에 4.2장의 로그 출력 API를 사용할 것을 추천합니다.
※ 64KB미만일 경우 최대 500행, 그 외의 경우에는 64KB까지 최신 로그를 취득합니다.
※ 이 기능을 유효로 한 경우, iOS 10.0보다 이전의 단말에서는 4.2장의 로그 출력 API에 의한 로그는 크래시 데이터에 포함되지 않고, NSLog에 의한 로그만이 크래시 데이터에 포함됩니다.

유효화 방법
■ Objective-C
[[SmartBeat shared] enableNSLog];
■ JavaScript

JavaScript에서 해당하는 함수는 없습니다.

4.4 사용자ID 설정

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

유효화 방법

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

■ Objective-C
[[SmartBeat shared] setUserId:@"user001"];
■ JavaScript
SmartBeat.setUserId('user001');

4.5 확장정보

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

유효화 방법

아래의 API 호출을 구현하면 임의의 키 이름과 값을 세트로 Crash 데이터와 함께 보존할 수 있습니다.
값을 변경하고 싶은 경우에는 동일한 키 이름으로 추가하면, 새로운 값으로 덮어 씌워집니다.

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

데이터는 NSString형만 설정할 수 있습니다.

■ JavaScript
SmartBeat.addExtraData('key1', 'value1');
SmartBeat.addExtraData('key2', 'value2');

4.6 breadcrumb기능

임의의 포인트에 breadcrumb을 남기면 에러 발생시까지 유저가 행한 조작과 화면이동 등을 수집할 수 있습니다.

유효화 방법

breadcrumb을 남기고(기록을 남기고 싶은) 장소에서 아래의 API를 호출해 주세요.
breadcrumb은 가장 마지막에 기록되어진 것부터 최대 16개가 보존됩니다.
예를 들면,「맵 화면」→「게임 화면」→「설정 화면」등과、키가 되는 화면의 이동시에 남길 경우, 에러직전에 유저가 어떻게 화면이동을 했는지를 알 수 있습니다.

■ Objective-C
[[SmartBeat shared] leaveBreadcrumb:@"game scene 1"];
■ JavaScript
SmartBeat.leaveBreadcrumb('game scene 1');

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

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 startWithApiKey: withEnabled: 에서 설정해 주세요.

■ Objective-C

유효화

[[SmartBeat shared] enable];

무효화

[[SmartBeat shared] disable];

상태 취득

BOOL enabled = [[SmartBeat shared] isEnabled];
■ JavaScript

유효화

SmartBeat.enable();

무효화

SmartBeat.disable();

상태 취득

var enabled = SmartBeat.isEnabled();

4.8 Catch한 JavaScript에러를 보존

SDK버전 1.21이후

Cocos2d-JS에서 앱이 Catch한 JavaScript에러를 기록할 수 있습니다.

유효화 방법
try {
    throw new Error();
} catch (e) {
    SmartBeat.logException(e);
}

4.9 dSYM자동 업로드

dSYM자동 업로드 스크립트를 Xcode의 Run Script에 넣으면, 매번 빌드시에 자동으로 dSYM를 자동으로 업로드 할 수 있습니다.
상세한 도입 방법 및 스크립트는여기로부터 다운로드해 주세요.

4.10 오디언스 기능

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

유효화 방법

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

5. 리소스 소비

아래는 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의 부하 증가

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

7. 개정 이력

개정일 변경 사항
2014년 6월 2일 초판 발행
2014년 9월 11일 Xcode6으로 빌드할 때 필요한 수정 추가(4.1 화면캡쳐 기능)
2014년 11월 20일 Cocos2d-x 3.x에서 구현 방법의 주석 추가
2016년 1월 6일 [Step3:IDFA에 의한 유저 카운트의 유효화]를 추가(SDK버전 1.18이후)
2016년 3월 14일 [6.OpenGL ES 화면캡쳐대상 단말]을 추가
2016년 4월 20일 [4.10 오디언스 기능]을 추가
2016년 11월 21일 [2. iOS의 Project에 SDK를 포함시키는 방법]에 필요한 라이브러리를 추가
[4.1 화면 캡쳐 기능(OpenGL ES)]Cococs2d-x 3.7이상의 버전에서 유효화 하는 방법을 추가로 기입
[4.1 화면 캡쳐 기능(OpenGL ES)]을 추가하는 API를 추가
[4.2 로그 출력]을 추가(SDK버전 1.20이후)
[4.3 NSLog출력]의 보충 설명을 추가
[6. OpenGL ES화면캡쳐대상 단말]의 리스트를 갱신
2016년 12월 22일 [1. 들어가며]에서 Cocos2d-x의 동작 검증버전과 대응 언어 갱신
[3. Cocos2d-JS의 에러 취득]를 추가(SDK버전 1.21이후)
[4. 옵션 기능]의 악장에 JavaScript API를 추가
[4.6 breadcrumb기능]을 추가
[4.7 에러 수집 유효화・무효화 변경]을 추가
[4.8. Catch한 JavaScript에러 보존]을 추가
[4.9 dSYM자동 업로드]를 추가
2017년 4월 13일 [3. Cocos2d-JS의 에러 취득]을 갱신
2018년 5월 16일 [6. OpenGL ES화면 캡쳐 대상 단말]의 리스트 갱신