Unity SDK

1. 대응 Unity 버전

이 SDK는 Unity4.2.1 이후의 환경에서 동작합니다.

Android플랫폼의 경우
※ Android 2.2이상

iOS플랫폼의 경우
※ iOS 6.0이상 (6.0보다 전 버전을 서포트 하는 경우에는 문의 폼 에서 문의를 부탁드립니다.)

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

이미 Unity SDK (ver1.10이전)을 이용하는 경우에는 일단 이전의 파일을 삭제 한 후에 이후 프로세스를 적용 해주세요.
※삭제대상 파일은 이쪽을 참고 부탁드리겠습니다.

Step1:SmartBeat.unitypackage의 Import

아래에서 SmartBeat SDK를 다운로드하십시오.

SmartBeat-Unity.zip의 압축을 풀어 SmartBeat.unitypackage을 추출
대상의 Unity 프로젝트를 열어 Assets > Import Package > Custom Package...에서 SmartBeat.unitypackage을 열어서 Import를 실행해주세요.

Unity 5.x로 Android용 빌드를 하는 경우

Unity 5.x에서는 Android의 arm64를 지원하지 않으므로 빌드 에러가 발생할 수 있습니다. Import 다이얼로그에서 Plugins/Android/libs/arm64-v8a/libSmartBeatNdk.so의 체크를 해제하고 Import해 주시기 바랍니다.

Step2:GameObject에 script를 첨부

SmartBeat을 기동하기 위해 어플리 기동시에 로드된 GameObject을 준비하여 SmartBeat의 스크립트를 첨부(붙이기)를 해주세요.
대상의 GameObject에 대해서 Add Component을 클릭하고 Scripts > Smart Beat > Smart Beat Behaviour를 추가해 주세요.
이 스크립트의 Awake()때 설정을 로드하여 SmartBeat을 기동합니다. 또한 첨부 된 GameObject에 대해서 DontDestroyOnLoad()가 실행됩니다.

Step3:API키 설정

패키지의 Import후에 메뉴에 SmartBeat의 메뉴가 추가 됩니다.
SmartBeat > Preferences을 선택하고 SmartBeat의 설정을 열어 주세요.

iOS/Android의 항목 밑에 API Key의 항목이 있는데 SmartBeat Console(Unity상의 메뉴의 SmartBeat > Open SmartBeat부터 엑세스 가능)에서 취득한 API키를 설정하고 「Save」을 클릭하여 저장 해주세요.

※ Unity(Android)의 경우、콘솔 상에서는 Android용의 App、Unity(iOS)의 경우、콘솔 상에서는 iOS의 App을 작성해 주세요.

Step4(Android): Permission의 정의

※ 이 항목은 Android용 Unity프로젝트 도입에 필요한 항목입니다.

Unity의 PlayerSettings(Android)에서 Internet Access을 Require로 합니다.
※ Player Settings은 Unity 메뉴의 Edit > Project Settings > Player에서 편집 가능합니다.

unity_2

이것은 App안에서 발생한 Crash데이터를 SmartBeat 서버에 보내기 위해 최소로 필요한 Permission 입니다.

Step5(Android): 중복 유저 카운트 방지

※이 항목은 Android용 Unity프로젝트의 도입에 필요한 항목입니다.

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

※ 중복된 유저의 카운트를 막는 설정을 유효화하는 것으로 오디언스 기능도 유효화 됩니다.
※ 본 기능은 Google Play services 4.0이후 버젼이 설치된 단말을 사용하는 유저 카운트에만 유효합니다. (그 외의 유저는 기존대로 카운트됩니다.)

본 기능을 유효화 하기 위해서는 아래의 순서대로 App에 Google Play services를 넣어 주세요. 본 기능을 유효화 하지 않는 경우에는 아래의 순서가 불필요합니다.

  • Android Studio
  • Eclipse + ADT
Google Repository를 다운로드

Android SDK Manager에서 Google Repository를 설치해 주세요.
install_google_repository

build.gradle의 편집

App의 모듈의 build.gradle를 열고 아래와 같이 dependencies에 play-services를 추가해 주세요. 추가한 play-services의 버젼은 최신 버전(https://developers.google.com/android/guides/releases를 참조)을 지정해 주세요.

dependencies {
    compile 'com.google.android.gms:play-services:8.4.0'
}

build.gradle편집후에는 Android Studio툴바의 [Sync Project with Gradle Files]버튼에서 편집결과를 프로젝트에 동기화해 주세요.

Google Play services 다운로드

Android SDK Manager에서 Google Play services를 설치해 주세요.
install_google_play_services

프로젝트의 추가

Eclipse에서 [File] -> [Import]로부터 [Existing Android Code into Workspace]를 선택、google-play-services_lib를 프로젝트에 임포트해주세요. google-play-services_lib는 Android SDK의 설치 폴더 바로 아래의 폴더에 있습니다.

<android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib

[Copy projects into workspace]의 체크는 ON으로 해 주세요.
import_google_play_services

라이브러리의 추가

App의 프로젝트의 프로퍼티를 열고 [Android]설정의 [Library]항목에 있는 [Add...]버튼을 클릭하여 google-play-services_lib를 추가해 주세요.
library_google_play_services

manifest파일의 편집

App의 manifest파일을 열고 <application>요소에 아래의 내용을 추가해 주세요.

<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
확인 방법
Unity SDK버전 1.18이후

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

bool ok = SmartBeat.SmartBeat.isReadyForDuplicateUserCountPrevention();

위의 API가 false를 반환하는 경우, Google Play services가 올바르게 적용되어 있지 않을 가능성이 있습니다.

Step6(Android): 빌드 심볼 자동 업로드(IL2CPP 빌드 한정)

Android IL2CPP 빌드의 경우, 빌드 심볼을 자동으로 SmartBeat 콘솔에 업로드하고, 발생한 NativeCrash의 스택 트레이스를 자동으로 심볼화할 수 있습니다.
Unity 메뉴에 추가된 SmartBeat > Build Preferences를 선택하여 빌드 설정을 여십시오.
Console(Unity 상의 메뉴 SmartBeat > Open SmartBeat에서 접근 가능)에서 취득한 API 키와 API Token을 설정하고, Enable Symbol Upload에 체크해서 [Save]를 클릭하여 저장하십시오.
※이후 빌드 시에 자동으로 심볼이 업로드됩니다.
※본 기능은 Unity 5.3.4 이상만 지원됩니다.

Step4(iOS):iOS용 Library를 복사

※ 이 항목은 iOS용 Unity 프로젝트의 도입에 필요한 항목입니다.

「iOS SDK (static lib)」를 다운로드하여 전개한 후、SmartBeat.h와 libSmartBeat.a를 Unity프로젝트의 Assets/Plugins/iOS 바로 아래에 복사합니다.

다음으로 Xcode를 기동하여 대상이 되는 Target을 선택 「General」 -> 「Linked Frameworks and Libraries」상에서 「+」를 클릭하고 표준에 포함되어있는 아래의 framework를 추가합니다.

  • libz.tbd또는 libz.dylib(iOS SDK버전 1.20이후)

하기의 framework는 오래된 Unity을 이용하고 있을 때만 자동적으로 추가되지 않기 때문에 추가가 필요합니다.

  • SystemConfiguration.framework
  • CoreTelephony.framework
  • AdSupport.framework(중복 유저 카운트 배제기능을 이용하는 경우에 추가 deploy대상으로 iOS6.0보다 이전 버젼도 대상으로 할 경우에는 "Optional"에서 추가해 주세요.)

Step5(iOS):중복 유저 카운트의 방지 설정

iOS SDK버전 1.18이후

※ 이 항목은 iOS용 Unity 프로젝트의 도입에 필요한 항목입니다.

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

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

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

linker 옵션의 추가

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

-force_load $(SRCROOT)/Libraries/Plugins/iOS/libSmartBeatIdfa.a

linker_flags_unity

확인 방법
Unity SDK버전 1.18이후

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

bool ok = SmartBeat.SmartBeat.isReadyForDuplicateUserCountPrevention();

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

3. 옵션 기능

이번 절에서는 추가 기능에 관해서 기술합니다. App으로부터 API를 호출하면 이러한 추가기능을 유효로 할 수 있습니다.
또한 SmartBeat의 각종 API는 SmartBeat 네임스페이스 아래에 선언 되어져 있기에
using SmartBeat;”를 추가하면、이후 기술 된 코드 샘플 안의 처음의 [SmartBeat.]를 생략할 수 있습니다.

3.1 화면 캡쳐 기능

본 기능을 유효로 한 경우, 에러 발생 시의 스크린 샷을 보존하고, 에러 정보와 함께 SmartBeat 서버에 보내집니다.

유효화 방법

Unity의 메뉴에서 SmartBeat > Preferences을 선택하고 SmartBeat의 설정을 열어서 Enable Screenshot에 체크를 넣어주세요.
스크린 샷의 화면은 일시적으로 [/smartbeat_screenshot_nn.png]이라는 파일 명(nn은 임의의 정수)으로 보존 됩니다.
변경할 필요가 있을 경우, [SmartBeat.cs]를 열고 해당 장소를 편집하면 변경 가능합니다.
파일은 SmartBeat서버에 보내진 후、자동적으로 삭제 됩니다."

3.2 LogCat/NSLog 출력

Logcat/NSLog의 출력을 크래시 데이터에 포함시킬 경우, Log출력기능을 유효화 해 주세요.
※ iOS 10.0 이후에서는 이 기능을 유효화 하더라도 NSLog를 크래시 데이터에 포함시킬 수 없습니다.
※ Unity SDK버전 1.9이후에서는 이 기능을 유효화 하지 않더라도 enableLogRedirect()를 유효화 하면 로그가 SDK내부에 보존되기에 크래시 데이터에 로그가 포함됩니다.

유효화 방법

Unity의 메뉴로 부터 SmartBeat > Preferences을 선택하고 SmartBeat이 설정을 열어서 Enable Log에 체크를 넣어 주세요.
또한 Android4.1보다 전(API레벨 15이전)에는 LogCat의 출력을 위해、아래의 Permission이 필요합니다.
Android4.1이후에는 Permission의 설정은 불필요하지만、자신의 App이 출력한 Log만 출력 가능합니다.

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

3.3 유저 ID 설정

대상의 App이 관리하는 유저를 식별할 ID가 이미 있는 경우、그것을 설정할 수 있습니다.
설정 된 유저ID는 Crash와 함께 SmartBeat서버에 보내집니다.
어떤 유저로 Crash가 발생 되었는지 등 관리 콘솔 상에서 확인 가능합니다.

유효화 방법

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

SmartBeat.SmartBeat.setUserId(“user001”);

3.4 확장 정보

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

유효화 방법

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

SmartBeat.SmartBeat.addExtraData("key1", "value1");
SmartBeat.SmartBeat.addExtraData("area", "Tokyo");

값을 변경하고 싶을 경우에는 같은 키 이름으로 추가하면 새로운 값으로 덮어씌워 집니다.

3.5 에러 수집 유효・무효 변경

Unity SDK버전 1.5이후

초기상태를 에러 수집 무효로 하였으나 도중에서 부터 에러 수집을 유효로 하고 싶을때 SmartBeatBehaviour.cs을 첨부한 GameObject의 생성을 늦추는 것이 가능하게 됩니다.
유효로 하고 싶은 타이밍에서 대상의 GameObject의 생성을 해주세요.

3.6 오디언스 기능

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

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

4. 그 외 API

또한、그 외의 API를 기술합니다. API는 SmartBeat.cs에 구현 되어 있습니다.

API 설명
void leaveBreadcrumb(string breadcrumb) breadcrumb을 남깁니다. API에서 설정된 breadcrumb를 최대 16개 보존 합니다.
남겨진 breadcrumb는 Crash데이터와 함께 SmartBeat서버에 보존 됩니다.
void enableScreenshot() 스크린샷 보존 기능을 유효로 합니다. 설정에서 유효가 되어 있어 유효 및 무효를 변경 할 수 없는 경우에는 본API는 이용할 필요가 없습니다.disableScreenshot()에서 무효를 한 후에 다시 유효로 돌렸을 경우등에 이용이 가능합니다.
void disableScreenshot() 스크린샷 보존 기능을 무효로 합니다. 이후의 크래쉬에서 스크린 샷이 보존 되지 않습니다. 보존하고 싶지 않은 화면 표시전 등에서 불러와 주세요. 디폴트에서는 스크린샷 보존기능은 무효로 되어 있기 때문에 설정을 유효로 하거나 또는 enableScreenshot()을 불러오지 않는 한 본 API를 불러올 필요가 없습니다.
bool HandleLog(string logString, string stackTrace, LogType type) 통상적으로 SmartBeat에서 Unity의 에러를 핸들링 하고 있기 때문에 이 API를 불러 올 필요는 없습니다. 단말 로그에 출력하지 않고 SmartBeat만 로그를 보존하려는 목적으로 독자적인 Logger를 적용하는 경우등에 사용됩니다.
인수:
logString : 로그
stackTrace : 스택 트레이스
(빈 문자의 경우 System.Diagnostics을 이용하여 취득합니다.)
LogType : 대상의 LogType
복귀값:
LogType가 기록 대상 또는 빈도가 높은(1회/2초 이상)의 경우 false를 표시 합니다.그외에는 true를 표시 합니다.

5. 그 외의 Permission

SmartBeat는、Crash로그 수집시에 해석에 필요한 단말 상태 등 주변 정보도 같이 기록합니다.
그러한 정보 안에는 Permission의 부여가 필요한 것이 있습니다. SmartBeat는 Permission이 없어
정보를 취득할 수 없을 경우、”no permission”이라고 기록하지만 Permission을 부여하면 아래의 정보도 취득할 수 있습니다.

Permission 명 취득 가능 정보
android.permission.ACCESS_NETWORK_STATE NW 접속 상태

6. 리소스 소비

SDK도입에 따른 리소스 소비량 계측 결과를 아래에 표시합니다.

Android의 경우

단말 항목 SDK 도입시
Nexus7 (2012)
Android 4.4.2
메모리 소비량
CPU 부하
약 1.7MB 증가
증감 없음
Xperia AX
Android 4.1.2
메모리 소비량
CPU 부하
약 0.6MB 증가
증감 없음
Xperia Ray
Android 2.3.4
메모리 소비량
CPU 부하
약 1.1MB 증가
증감 없음

iOS의 경우

단말 항목 SDK 도입 시
iPhone5S
iOS7.0.4
메모리 소비량
CPU 부하
약 1.0MB 증가
증감 없음
iPhone4
iOS6.0.1
메모리 소비량
CPU 부하
약 1.0MB 증가
증감 없음

정기적으로 화면 캡쳐를 취득하고 있지 않기에 화면 캡쳐 기능 ON/OFF에 관계 없이 에러가 발생하지 않는 상황에서는 CPU리소스 소비량은 없습니다.

Unity에서의 화면 캡쳐 기능을 ON으로 할 경우、예외 발생 시에 화면 취득 처리가 메인 스레드로부터 불려 질 경우가 있기에 예외가 연속으로 발생할 경우 등 다소 움직임에 영향을 줄 수 있습니다.

단、한 번 취득하면 2초간은 취득하지 않도록 했기 때문에 연속으로 발생한 경우의 움직임에 영향은 최소한으로 줄였습니다.

7. 개정 이력

개정일 변경 사항
2014년 2월 4일 초판 릴리즈
2014년 3월 24일 추가 한 Framework(iOS)로부터 CoreLocation.framework를 삭제
그 외의 Permission(Android만)로부터 ACCESS_FINE_LOCATION를 삭제
2014년 6월 16일 리소스 소비의 항목을 추가
2014년 6월 27일 [3.5 에러 수집 유효・무효 변경]을 추가 기입(Unity SDK버전 1.5이후)
Unity로그의 NSLog에 전송에 관한 기술을 추가 기입
2014년 10월 23일 [Step3(Android): Android용 Library의 복사]를 변경
2016년 1월 6일 [Step5(Android): 중복 유저 카운트의 방지]를 추가(Android SDK버전 1.12이후)
[Step4(iOS): IDFA에 따른 유저 카운트의 유효화]를 추가(iOS SDK버전 1.18이후)
2016년 1월 13일 iOS용의 설명을 프레임워크판 SDK를 사용한 것으로부터 라이브러리판 SDK를 사용한 것으로 변경
2016년 4월 20일 [3.6 오디언스 기능]을 추가
2016년 11월 21일 [Step3(iOS): iOS용 Library 복사]에 필요한 라이브러리를 추가
[3.2 LogCat/NSLog출력]의 보충설명을 추가
[4. 그 외의 API]에 enableLogRedirect()의 설명을 변경
2017년10월17일 SDK의 배포형식을 unitypackage로 변경하여 연동 방법을 갱신
2018년3월4일 [Step5(Android): 중복 유저 카운트 방지]을 변경
[Step5(iOS): 중복 유저 카운트 방지]을 변경