로딩중입니다
애드브릭스 연동 : 안드로이드
3/2/2015 11:58:51 PM

애드브릭스 분석 연동하기 : 안드로이드 네이티브

애드브릭스는 광고성과 추적과 이용자 분석을 동시에 지원하는 서비스입니다.


본 가이드는 애드브릭스 사용을 위해 필요한 sdk 연동을 안내합니다.

애드브릭스 서비스 소개나 이용방법 안내는 아래의 아티클을 통해 확인할 수 있습니다.

[애드브릭스 서비스 이용 안내]


서비스 이용 중 도움이 필요한 경우에는 아래 메일 주소로 연락 부탁 드립니다.

1. 서비스 이용 문의 - 애드브릭스 사업팀(abx@igaworks.com)

2. 기술문의 - 기술지원팀 (tech_support@igaworks.com)



SDK 다운로드 및 설치

[SDK 다운로드 센터] 에서 최신 안드로이드 SDK 패키지를 다운로드 합니다.

다운로드 받은 .zip 파일을 압축해제하여 IgawCommon~*.jar 파일과 IgawAdbrix~*.jar 파일을 안드로이드 스튜디오 프로젝트로 복사하고 gradle을 업데이트합니다.






매니페스트 설정

애드브릭스를 이용하기 위한 내용을 AndroidManifest.xml 파일에 추가합니다.


앱키 & 해시키 추가

Igaworks 홈페이지에서 애드브릭스 앱 등록 후 발급받은 앱키, 해시키를 <application></application> 태그 안에 추가합니다.

<application>
...
    <meta-data android:name="igaworks_app_key" android:value="이곳에_앱키를_입력하세요" />
    <meta-data android:name="igaworks_hash_key" android:value="이곳에_해시키를_입력하세요" />
...
</application>


퍼미션 추가

<manifest></manifest> 태그 안에 필수 퍼미션을 추가합니다.

<manifest>
...
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
...
</manifest>


구글 인스톨 리시버 추가

<application></application> 태그 안에 IGAW 구글 인스톨 리시버를 추가합니다.

2개 이상의 리시버를 등록하여 사용해야 하는 경우에는 [APPENDIX : 커스텀 인스톨 리시버 등록] 안내를 참고하여 구성합니다.

<application>
...
    <receiver android:name="com.igaworks.IgawReceiver" android:exported="true">
        <intent-filter>
            <action android:name="com.android.vending.INSTALL_REFERRER"/>
        </intent-filter>
    </receiver>
...
</application>

 Caution!!!  인스톨 리시버는 트래킹링크 사용을 위해 반드시 필요하며 적용되지 않았을 때에는 광고트래킹이 올바르게 동작하지 않을 수 있습니다.


Google Play Install Referrer API 설정

Google Play Install Referrer API 는 애드브릭스 광고 트랙킹 시 부정 트래픽 방지를 목적으로 사용됩니다.

※ 본 기능은 IgawCommon v4.5.4a 버전 부터 사용할 수 있습니다.


1) 안드로이드 스튜디오

Google Play Install Referrer 를 사용하기 위해서는 build-gradle 에 아래 dependencies 를 추가합니다.

dependencies {
  ...  
  compile 'com.android.installreferrer:installreferrer:1.0'
  ...
}


추가로 프로젝트  build-gradle 에 아래와 같이 repositories 내 google() 설정을 추가합니다.

buildscript {
   repositories {
       jcenter()
   }
   dependencies {
       classpath 'com.android.tools.build:gradle:3.0.1'
   }
}

allprojects {
   repositories {
       jcenter()
       google()
   }
  }


2) 이클립스를 포함한 기타 툴

이클리스를 포함한 기타 툴에서 Google Play Install Referrer 를 적용하기 위해서는 Installer 라이브러리를 추가합니다. [다운로드]

라이브러리 추가 후 Androidmanifest.xml 에 아래 권한을 추가합니다.

<uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE"/>


프로가드 설정

안드로이드 스튜디오의 app/proguard-rules.pro 파일에 애드브릭스 SDK에 대한 난독화 예외설정을 추가합니다.

##---------------Begin: proguard configuration for Igaworks Common  ----------
-keep class com.igaworks.** { *; }
-dontwarn com.igaworks.**
##---------------End: proguard configuration for Igaworks Common   ----------

##---------------Begin: proguard configuration for Gson  ----------
# Gson uses generic type information stored in a class file when working with fields. Proguard
# removes such information by default, so configure it to keep all of it.
-keepattributes Signature

# For using GSON @Expose annotation
-keepattributes *Annotation*

# Gson specific classes
-keep class sun.misc.Unsafe { *; }
-keep class com.igaworks.gson.stream.** { *; }

# Application classes that will be serialized/deserialized over Gson
-keep class com.igaworks.adbrix.model.** { *; }

##---------------End: proguard configuration for Gson  ----------

 Caution!!!  이클립스 프로젝트의 경우에는 Project/proguard-project.txt 파일을 수정합니다.



기본 연동

세션 트래킹 : 자동

애드브릭스에서 제공하는 기본 분석을 위한 연동입니다.
연동하는 앱이 안드로이드 4.0.4 이상만을 지원한다면 autoSessionTracking 을 사용하여 세션 트래킹을 합니다.

AndroidManifest.xml에 아래의 내용을 추가하여 autoSessionTracking 기능을 활성화합니다.
<application
    android:name="com.igaworks.IgawDefaultApplication"
    ... 중략 ...
>
</application>

자체 application 클래스를 사용하고 있는 경우
아래 예시와 같이 이미 application 클래스를 사용하고 있는 경우에는 application class의 onCreate()에 autoSessionTracking api를 추가합니다.
<!-- AndroidManifest.xml -->
<application
    android:name="PACKAGE_NAME.YourCustomApplication"
    ... 중략 ...
>
</application>
/* YourCustomApplication.java */
public class YourCustomApplication extends Application{
    @Override
    public void onCreate(){
        super.onCreate();
        IgawCommon.autoSessionTracking(YourCustomApplication.this);
        // 어플리케이션 클래스에서는 autoSessionTracking API 외의 어떤 애드브릭스 API도 호출해서는 안됩니다.
    }
}
 Caution!!!  Application 클래스에서는 autoSessionTracking API 외 어떠한 애드브릭스 분석용 API도 호출해서는 안됩니다.
 Caution!!!  autoSessionTracking 은 서비스 형태로 동작하는 앱의 경우에는 적용을 하지 않습니다.


세션 트래킹 : 수동

애드브릭스에서 제공하는 기본 분석을 위한 연동입니다.
연동하는 앱이 안드로이드 4.0.4 이하까지 지원을 하거나 수동으로 세션 트래킹을 하고자 할때에 startSession, endSession api를 이용하여 연동을 합니다.
@Override
protected void onResume() {
    super.onResume();
    IgawCommon.startSession(MainActivity.this);
}

@Override
protected void onPause() {
    super.onPause();
    IgawCommon.endSession();
}
 Caution!!!  startSession, endSession은 반드시 짝을 이루어 호출되도록 연동하여야 합니다.
 Caution!!!  앱이 시작되는 액티비티에는 반드시 startSession, endSession이 연동되어야 합니다.
 Caution!!!  고급분석 api를 연동한 액티비티에는 반드시 startSession, endSession이 연동되어야 합니다.
 Caution!!!  processKill 을 사용하여 앱 종료를 처리하는 방식에서는 [APPENDIX : ProcessKill 사용 시 session 처리] 를 참고하여 endSession을 처리합니다.

GDPR 설정

GDPR 이벤트를 호출하여 호출 시점 이후부터 SDK 동작을 막을 수 있습니다.
본 이벤트 호출 이후 Adbrix 데이터 전송 / LiveOps 푸시 / LiveOps 공지팝업 / 애드팝콘 광고 참여 가 불가능합니다.
본 기능은 사용자기 앱을 삭제 후 재설치 하기 전까지 되돌릴 수 없습니다.
IgawCommon.gdprForgetMe(MainActivity.this);



고급 연동 : 커스텀 액티비티
앱 이용자의 액티비티(행동)을 분석하고 이 정보를 포스트백에 활용할 수 있습니다.


FirstTimeExperience (FTE)

애드브릭스 리포트 내 확인 : Advanced analytics - New User session
목적 : firstTimeExperience API는 앱을 최초로 실행한 이용자의 이탈 시점을 파악하기 위해 사용합니다. 
특징 : 최초로 앱을 실행한 일자 당일의 데이터만을 제공합니다.  (예: 1월 1일 유입된 유저가 1월 2일 레벨 10 달성 시 1월 2일의 레벨 10 달성은 분석하지 않음)

//IgawAdbrix.firstTimeExperience(String userActivity);
IgawAdbrix.firstTimeExperience("loginComplete");
IgawAdbrix.firstTimeExperience("CharacterCreate");
IgawAdbrix.firstTimeExperience("TutorialComplete");
IgawAdbrix.firstTimeExperience("Level5Complete");

위 샘플은 게임으로 가정하여 작성되었습니다.

userActivity 파라미터에는 영어와 숫자로 된 공백없는 문자열을 사용하시는 것을 권장합니다.

 Caution!!!  유저가 유입 당일 도달이 가능한 액션까지만을 연동해야 합니다. 이후 액션은 분석에서 제공되지 않습니다.



Purchase (In App Purchasing)

애드브릭스 리포트 내 확인 : RevenueAdvanced analytics - First - time purchaseROAS Reporting

목적 : 모든 유저의 인앱 구매 행동을 일자별로 분석하고, 재설치/재실행 유저의 매출 분석이 가능합니다. 

특징 : 애드브릭스에 노출되는 매출은 'price x quantity' 로 계산됩니다.

//상품 추가 속성 정의  
IgawCommerceProductAttrModel attrModel;

HashMap attrModel1 = new HashMap<>();
   attrModel1.put("att1", "value1");
   attrModel1.put("att2", "value2");
   attrModel1.put("att3", "value3");
            
attrModel = new IgawCommerceProductAttrModel(attrModel1);
            
//상품 구매 API 호출            
IgawAdbrix.purchase(MainActivity.this,
                   "orerdID_1",                                                  //String orderID
                   IgawCommerceProductModel.create(                              //구매상품정의
                                "productID_1",                                   //String productID
                                "ProudctName_1",                                 //String productName
                                10000.00,                                        //double price
                                0.00,                                            //double discount
                                1,                                               //int quantity
                                IgawCommerce.Currency.KR_KRW,                    //Currency
                                IgawCommerceProductCategoryModel.create("cat1"), //상품 카테고리 정의
                                attrModel),                                      // Attr 카테고리 정의
                   IgawCommerce.IgawPaymentMethod.MobilePayment);                //PaymentMethod
+ orderID : 주문 아이디 
+ productID : 상품 아이디
+ productName  : 상품명 (Buy api를 사용했던 앱을 업데이트 하는 경우, productName에 기존 사용하셨던 buy api의 purchaseItemName을 입력합니다.)
price  : 상품단가
+ discount : 할인가. 없을 경우 0 으로 표시
quantity  : 구매 수량
+ currency : 구매 통화 단위 (IgawCommerce.Currency 사용)
+ ProductCategoryModel : 최대 5단계의 상품 카테고리, 각 단계는 마침표(.)으로 구분
+ ProductAttrModel : 상품 추가 속성. 없을 경우 null 표시
 Caution!!!  Purchase API를 통해서 매출 지표가 분석되어 리포트됩니다. 실제 구매에 대하여 사용하는 것을 권장합니다.



Retention (RET)

애드브릭스 리포트 내 확인 : Advanced Analytics - In-app activities 
목적 : 모든 유저가 앱내에서 일으키는 행동 (예: 로그인, 레벨달성, 상점 방문, 회원가입 등)의 일자별 분석이 가능합니다. 
특징 : 일자별 액티비티 실행 수와 실행 유저수를 제공하며, 하위 파라미터를 사용할 수 있습니다.
//IgawAdbrix.retention(String inAppActivity);
IgawAdbrix.retention("openStore");
IgawAdbrix.retention("stageClear");
IgawAdbrix.retention("purchaseItemWithVirtualCurrency");
IgawAdbrix.retention("inviteFriends");
 Caution!!!  inAppActivity 파라미터에는 영어와 숫자로 된 공백없는 문자열을 사용하시는 것을 권장합니다.

Sub Activity 설정

Sub activity 설정 가능한 API : retention API는 하위 액티비티 설정 가능 
애드브릭스 리포트 내 확인 : Advanced Analytics - In-app activities
목적 : 유저의 특정 행동을 하위로 세분화하여 분석하실 수 있습니다. (예: 로그인 - 카카오톡 / 네이버 / 페이스북)

//IgawAdbrix.retention(String inAppActivity, String subActivity);
IgawAdbrix.retention("login","kakaotalk");




고급연동 : 코호트
코호트 분석에서는 유저 그룹을 총 3개까지 생성하여 그룹 별로 분석할 수 있습니다.
코호트 분석 지표에 대한 설명과 사용법은 아래 아티클에서 확인할 수 있습니다.


SetCustomCohort 

애드브릭스 리포트 내 확인 : 애드브릭스 모든 리포트 상단 (일부 리포트 제외) 

목적 :특정한 유저 그룹으로 필터링 해 애드브릭스 리포트를 별도 확인 가능합니다.  (예: 성별, 나이, 구매금액 등)

특징 : 커스텀 코호트는 3가지 그룹을 지정하실 수 있습니다. 

//IgawAdbrix.setCustomCohort(CohortVariable cohortFilter, String inAppActivity);

//커스텀코호트 그룹 1 --> 레벨 달성 정보
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_1, "level_1");
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_1, "level_5");
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_1, "level_10");

//커스텀코호트 그룹 2 --> 방문 횟수 정보
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_2, "visit_10_times");
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_2, "visit_20_times");
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_2, "visit_30_times");

//커스텀코호트 그룹 3 --> 과금 금액 구간 정보
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_3, "under_10000_won");
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_3, "under_50000_won");
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_3, "over_50000_won");

+ CohortVariable에 미리 정의된 필터는 CohortVariable.COHORT_1~3 까지, 총 3개가 제공됩니다.

+ 애드브릭스 리포트 내 코호트 미적용 메뉴는 다음과 같습니다. 

  1. Tracking Link - Reporting, ROAS Reporting
  2. Analytics - Retention, Active Users
  3. Advanced Analytics - New User Session
  4. Revenue - Revenue by Install date



고급연동 : 유저분석
유저의 성별, 나이에 대한 분석을 할 수 있습니다.

SetAge

유저 나이를 1~99 사이의 정수로 입력합니다.

IgawCommon.setAge(20);



SetGender

유저 성별을 IgawCommon.Gender 에 정의된 설정값을 이용하여 입력합니다.

IgawCommon.setGender(IgawCommon.Gender.MALE);




고급연동 : 커머스 이벤트

애드브릭스에서는 커머스 앱에서 발생하는 다양한 이벤트를 분석하기 위한 추가 연동을 제공하고 있습니다.

오픈 마켓, o2o, 쇼핑몰, 홈쇼핑 등과 같은 커머스 앱의 "유저로그인, 딥링크 오픈, 장바구니 담기, 상품 상세보기, 구매하기" 등의 유저 행동을 분석합니다.

분석 대상이 되는 이벤트 종류가 다양하여 별도의 가이드로 제공하고 있으며, 아래 링크를 통해 확인할 수 있습니다.

[애드브릭스 커머스 이벤트 연동 : 안드로이드]




APPENDIX : 커스텀 인스톨 리시버 등록

여러 개의 ThirdParty 툴을 사용하는 경우 구글 인스톨 리퍼러를 각각의 ThirdParty 리시버로 전달되도록 처리하여야 합니다.

이 경우에는 아래 예시와 같이 별도의 리시버 클래스를 생성하여 사용하는 것을 권장합니다.

<!-- AndroidManifest.xml -->
<receiver android:name="my_app_package.MultipleInstallReceiver" android:exported="true">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER"/>
    </intent-filter>
</receiver>
/* MultipleInstallReceiver.java */
public class MultipleInstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceiver(Context context, Intent intent) {
        //IGAW 구글 인스톨 리시버 등록
        IgawReceiver igawReceiver = new IgawReceiver();
        igawReceiver.onReceive(context, intent);
        //INSTALL_REFERRER 를 전달받아야 하는 다른 리시버들을 등록합니다.
    }
}




APPENDIX : 딥링크 트래킹

애드브릭스의 딥링크 트래킹 기능을 이용하기 위해서는 앱에서 딥링크를 지원해야 합니다.


딥링크 세팅

AndroidManifest.xml 파일에서 딥링크로 오픈될 액티비티의 설정에 아래와 같이 intent-filter 를 추가합니다.

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="YOUR_SCHEME_NAME_HERE" />
</intent-filter>

scheme 값을 정하지 못하셨다면, 애드브릭스 앱키를 이용하셔도 됩니다.

애드브릭스 앱키가 123456이라면 아래 예시처럼 AndroidManifest.xml 파일을 수정하시면 되겠습니다.

<activity android:label="@string/app_name" ...... >
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="adbrix123456"/>
    </intent-filter>
</activity>

 Caution!!!  deeplink scheme은 소문자로만 구성하는 것을 권장합니다. [구글 개발자 가이드 참고]



딥링크 오픈 트래킹

애드브릭스는 트래킹 링크를 통한 딥링크 오픈 기능을 제공하고 있습니다.

트래킹링크를 통해 딥링크 오픈 리포팅을 위해 안드로이드 개발환경에서는 몇 가지 예외적인 케이스들에 대해 주의해야 합니다.

다음 아티클의 체크리스트를 참고하여 적절하게 구현을 합니다.

[How to set Deeplink??]




APPENDIX : ProcessKill 사용 시 session 처리

애드브릭스의 트래킹 데이터는 onPause()에서 호출하는 endSession api 에서 서버로 전송됩니다.

하지만 ProcessKill 등의 강제종료 방식을 사용하는 앱의 경우에는 애드브릭스 트래킹 데이터가 유실될 가능성이 있습니다.

안드로이드 뒤로가기 버튼의 이벤트 액션에 다음과 같은 처리를 하여 endSession API가 정상적으로 호출되도록 처리하시는 것을 권장합니다.


ProtectSessionTracking

processKill 을 처리하기 전에 protectSessionTracking api를 호출하여 데이터 유실을 방지합니다.

public boolean onKeyDown(int keyCode, KeyEvent event){
	switch(keyCode){
	case KeyEvent.KEYCODE_BACK:

		IgawCommon.protectSessionTracking(this);

		new AlertDialog.Builder(this)
		.setTitle("종료확인")
		.setMessage("종료하겠습니까?")
		.setPositiveButton("예", new DialogInterface.OnClickListener(){
    			public void onClick(DialogInterface dialog, int which){

				// 해당 어플의 프로세스를 강제 Kill시킨다.
				android.os.Process.killProcess(android.os.Process.myPid());
 			}
    		}).setNegativeButton("아니오", new DialogInterface.OnClickListener(){
    			public void onClick(DialogInterface dialog, int which){
			}
    		}).show();
	}
   	return true;
}