Unity SDK

1. 대응 Unity 버전

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

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

iOS플랫폼의 경우
※ iOS 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를 넣어 주세요. 본 기능을 유효화 하지 않는 경우에는 아래의 순서가 불필요합니다.

빌드 의존 관계 추가

Unity 버전 및 프로젝트의 빌드 파이프라인에 따라 설정 UI와 제공되는 적용 방법이 다르기 때문에, 여기에서는 Unity의 「커스텀 build.gradle 템플릿」에 의한 적용 방법을 예로 듭니다. 「커스텀 build.gradle 템플릿」에 대해서는 Unity 매뉴얼(https://docs.unity3d.com/ja/2020.2/Manual/android-gradle-overview.html) 을 참고 바랍니다.

참고: Unity2020.1의 「커스텀 build.gradle 템플릿」 설정 화면

앱의 mainTemplate.gradle에 모듈의 build.gradle을 열고, 아래와 같이 dependencies에 play-services-ads-identifier를 추가하십시오. 추가하는 play-services-ads-identifier의 버전은 최신 버전 (https://developers.google.com/android/guides/releases 를 참고)을 지정해 주십시오.

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'com.google.android.gms:play-services-ads-identifier:17.+'
**DEPS**}

Android Gradle Plugin 2.3 이하를 빌드로 사용하고 있을 경우에는 위의 내용 대신에 다음을 지정해 주십시오.

dependencies {
	compile fileTree(dir: 'libs', include: ['*.jar'])
	compile 'com.google.android.gms:play-services-ads:10.0.+'
**DEPS**}
AndroidX 마이그레이션

Android Gradle Plugin 3.6 (Unity2020.1부터의 디폴트) 이상을 빌드로 사용하고 있을 경우에는 다음 순서에 따라 프로젝트를 AndroidX로 마이그레이션하여 play-services-ads-identifier를 이용 가능한 상태로 만드십시오.

【순서】
앱의 gradleTemplate.properties에 다음의 설정값을 추가하십시오.

android.useAndroidX=true
**ADDITIONAL_PROPERTIES**
확인 방법
Unity SDK버전 1.18이후

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

bool ok = SmartBeat.SmartBeat.isReadyForDuplicateUserCountPrevention();

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

Step6(Android):오디언스 기능 설정

Advertising ID를 사용하여 애플리케이션을 이용하는 사용자의 남녀 비와 연령분포를 확인할 수 있게 됩니다.

Android에서는 중복 사용자 계정 방지 설정을 유효로 하면 오디언스 기능도 유효하게 됩니다. 중복 사용자 계정의 방지 설정에 대해서는 이곳을 참조하시기 바랍니다.

Step7(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(오디언스 기능을 유효화하는 경우에 추가)

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

iOS SDK버전 1.21.2이후

Unity SDK 1.21.2의 이후 버전을 이용하시는 경우, iOS에서 추가적인 조치는 필요 없습니다. 자동으로 같은 사용자의 중복 계정을 방지합니다. 그로 인해 앱의 재설치를 반복하는 행위(소위 '반복 리셋')가 있다 하더라도, 불필요한 MAU(Monthly Active Users) 수의 증가를 방지할 수 있습니다.

Step6(iOS):오디언스 기능 설정

IDFA를 사용하여 애플리케이션을 이용하는 사용자의 남녀 비와 연령분포를 확인할 수 있게 됩니다.
Xcode에서 대상이 되는 Target를 선택하고 [Build Settings]의 [Other Linker Flags]에 아래의 내용을 추가해 주세요.

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

linker_flags_unity

3. 옵션 기능

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

3.1 화면 캡쳐 기능

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

유효화 방법

SmartBeat의 설정을 열어 "Auto 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 이후에서는 본 기능을 활성화하지 않아도 SmartBeat의 설정에서 ”Log Redirect Prefix”에 임의의 문자열을 설정하면 로그가 SDK 내부에 저장되므로, 크래시 데이터에 로그가 포함되게 됩니다.

유효화 방법

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.7 자동 브레드크럼

일반적인 동작이나 스테이터스 변화 등의 이벤트를 자동으로 브레드크럼으로 기록합니다.
leaveBreadcrumb( )를 이용하여 기록된 브레드크럼에 더하여 최신 브레드크럼이 최대 128개 저장되며, 남은 브레드크럼은 충돌 데이터와 함께 SmartBeat 서버에 저장됩니다.

유효화 방법

SmartBeat의 설정을 열어 "Auto Breadcrumb"에 체크하십시오. (초기 설정에서는 켜져 있습니다)

3.8 오류를 그룹화할 때 제외 데이터의 설정 방법

SmartBeat는 오류를 원인별로 그룹화하고 있지만, 오류명에 앱 이용 상황이나 단말기 고윳값 등이 삽입되어 있는 경우, 동일한 원인의 오류라고 해도 다른 오류로 표시되는 경우가 있습니다.
그러한 경우에는 아래의 대응방법을 검토하여 주십시오.

오류를 그룹화할 때 제외 데이터의 설정 방법

3.9 SmartBeat 이외에서의 시그널 핸들러 이용(Android)

통상적으로 SmartBeat는 시그널 크래시의 처리 직후에 프로세스를 종료시키지만, SmartBeat의 처리를 실행하기 전에 등록한 핸들러에게도 시그널을 처리시키고 싶을 경우에는 CallOtherSignalHandlers를 유효화하세요. (예: logcat 등에서 SIGNAL 오류 정보를 확인하고 싶을 때)

유효화 방법

Unity 메뉴의 SmartBeat > Preferenece > Android에서
Call other SIGNAL handlers[?] 를 유효화하세요.

4. 그 외 API

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

API 설명
void leaveBreadcrumb(string breadcrumb) 브레드크럼 남기기. 자동 브레드크럼에 더하여 최신 브레드크럼이 최대 128개 저장되며, 남은 브레드크럼은 충돌 데이터와 함께 SmartBeat 서버에 저장됩니다.
void leaveBreadcrumb(string breadcrumb, Dictionary<string, string> metas)
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): 중복 유저 카운트 방지]을 변경
2019년10월29일 [4. 그 외 API]의 브레드크럼 내용을 업데이트
2019년11월xx일 [4. 그 외 API]의 브레드크럼 내용을 업데이트
2020년8월18일 [3.8 오류를 그룹화할 때 제외 데이터의 설정 방법]의 브레드크럼 내용을 업데이트
2020년9월15일 중복 사용자 계정 방지 설정(iOS)' 도입 방법 업데이트
2021년1월14일 [3.9 SmartBeat 이외에서의 시그널 핸들러 이용(Android)] 를 추가
2021년1월27일 [Step5(Android): 중복 유저 카운트 방지]을 변경