로딩중입니다
[AOS] adbrix 集成 : Native Android
8/26/2015 10:26:47 AM

[高级分析] adbrix 对接 : Native Android

adbrix 是同时支持 '监测广告效果' 和 '应用内用户行为分析' 的一种服务。


本文介绍详情的 adbrix SDK 对接所步骤。

若想要理解关于 adbrix 的服务介绍及适用方式时,请参考 [adbrix 服务介绍] 文档。


adbrix 服务上所需要帮忙的话,请联系至如下邮件地址。

1. 服务及对接相关咨询 - 中国事业部 (china@igaworks.com)



SDK 下载及安装

[SDK 下载中心] 文档里下载最新版本的 Android SDK Package。

已下载的 .zip 文件解压之后,把 IgawCommon~*.jar 和 IgawAdbrix~*.jar 文件复制到 Android Studio Project 后更新 gradle。



*若按 Eclipse 造成应用时,请参考 [SDK 安装 : Android] 文档进行安装 SDK。



AndroidManifest 设置

为了使用 adbrix 支持的服务,需在 AndroidManifest.xml 上添加如下内容。


添加 App Key & Hash Key

IGAWorks 官网上注册并登录应用完成后,在 <application></application> 标签上输入相应的 App Key & Hash Key。

<application>
...
    <meta-data android:name="igaworks_app_key" android:value="请输入官网上确认的 App_Key" />
    <meta-data android:name="igaworks_hash_key" android:value="请输入官网上确认的 Hash_Key" />
...
</application>


添加 Permission

在 <manifest></manifest> 标签上添加如下必备 Permission。(*其他 Permission 不需再添加)

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



添加 Google Install Receiver

在 <application></application> 上添加如下 IGAW Google Install Receiver。

若需要使用两个以上的 Receiver 的话,请参考如下 [附录 : Custom Install Receiver 登录] 内容。

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

 注意!!!  为了使用 ‘监测广告效果’ 服务时,需要设置上述 Install Receiver 相关内容。若在应用上未添加代码时,监测广告效果功能会运行异常。


Google Play Install Referrer API 设置

Google Play Install Referrer API 是以 "在 adbrix 上监测广告效果时,预防异常流量" 为目的。

※ 本功能是从 IgawCommon v4.5.4a 以上版本支持。


1) Android Studio

为了使用 Google Play Install Referrer,在 build-gradle 上添加如下 dependencies。

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


在 Project build-gradle 上添加如下 repositories 内的 google() 设置。

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

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


2) 其他开发工具(包含 Eclipse)

为了在其他开发工具(包含 Eclipse) 上使用 Google Play Install Referrer,需添加如下 Install Library。[下载]

Library 添加之后,在 Androidmanifest.xml 上添加如下权限。

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


设置 Proguard

在 Android Studio 里的 app/proguard-rules.pro 文件上添加 IGAW 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  ----------

 注意!!!  Eclipse Project 上需要混淆处理时,在 Project/proguard-project.txt 文件上直接修改相应内容。



基本分析

Session Tracking : 自动

为了使用 IGAWorks 支持的基本分析,请参考如对接内容。
目前应用支持 Android 4.0.4 版本以上的话,请使用如下 autoSessionTracking 代码来进行对接。

请在 AndroidManifest.xml 上添加如下代码后激活 autoSessionTracking 功能。
<application
    android:name="com.igaworks.IgawDefaultApplication"
    ... 中略 ...
>
</application>

使用自己的 application class 情况时,
按如下示例一样已在使用 application class 时,在 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);
        // 在 application class 上除了 autoSessionTracking API 外,不需调用任何 adbrix API。
    }
}
 注意!!!  Application class 上除了 autoSessionTracking API 外,不需调用任何 adbrix 分析用 API。
 注意!!!  autoSessionTracking 是无法运营服务形式的应用。(比如背景上运行的时间应用等)


Session Tracking : 手动

为了使用 IGAWorks 支持的基本分析,请参考如下对接内容。
目前应用支持 Android 4.0.4 以下都能包含的话,使用 StartSession、endSession API 来进行对接。
@Override
protected void onResume() {
    super.onResume();
    IgawCommon.startSession(MainActivity.this);
}

@Override
protected void onPause() {
    super.onPause();
    IgawCommon.endSession();
}
 注意!!!  startSession, endSession 对接时必须要配置。
 注意!!!  应用里的各 Activity 上需要对接 startSessionendSession。
 注意!!!  高级分析 API 对接时也需要设置完成 startSessionendSession 代码。
 注意!!!  若需使用 processKill 来处理应用结束情况时,参考 [附录 : ProcessKill 使用时,处理 Session] 内容来处理 endSession。




高级分析 : 自定义事件分析 (Custom Activity)
对接如下 API 可以分析用户的各种行为,甚至适用于回传(Post-back)功能。


FirstTimeExperience (FTE)

菜单 : 高级应用分析(Advanced analytics) > 新增用户事件分析(New User session)
目的 : firstTimeExperience API 是为了监测首次启动应用用户的流失时点。 
特征 : 仅提供首次启动应用当日的数据。(例 : 1月1日流入的用户在1月2日达成 'Lv10' 的话,1月2日的数据不含 Lv10)

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

以上示例是以游戏应用为编制的内容。

同时建议 userActivity 参数设置时,请使用无空白的英文及数字的字符串。

 注意!!!  对接上述 API 时,设置为 '用户流入当时能达到的阶段'。以后阶段的分析数据无法提供。



Purchase (In App Purchasing)

菜单 : 收入分析报告(Revenue)、高级应用分析(Advanced analytics) > 首次付费(First - time purchase)、ROAS Reporting

目的 : 按日期分析所有用户的购买行为及再次安装/再次启动用户的销售。 

特征 : adbrix 后台上统计的销售是以 '价格(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 : 订单 ID 
+ productID : 商品 ID
+ productName  : 商品名称 (Buy api 的应用需更新的话在 ProductName上设置 Buy api 的 purchaseItemName)
price  : 商品单价
+ discount : 折扣。若没有折扣的话,请显示 ‘0’
quantity  : 购买数量
+ currency : 货币单位 (使用 IgawCommerce.Currency)
+ ProductCategoryModel : 最多设置5个阶段的商品分类。各阶段用句号(.)隔开
+ ProductAttrModel : 追加商品属性。若没有属性的话,请显示 ‘null’
 注意!!!  若传达同样的 orderID 时,会排重重复数据并统计。对接时请注意 orderID 是否重复设置。
 注意!!!  通过 Purchase API 统计销售指标。我方推荐实际购买的时点上设置该 API。



Retention (RET)

菜单 : 高级应用分析(Advanced Analytics) > 应用内活动分析(In-app activities) 
目的 : 统计应用内用户所发生的行为。(例 : 登录、达成等级、访问商店、注册等可以按日分析。) 
特征 : 提供按日 Activity 调用的启动数及用户数,同时可以使用 sub Activity。
//IgawAdbrix.retention(String inAppActivity);
IgawAdbrix.retention("openStore");
IgawAdbrix.retention("stageClear");
IgawAdbrix.retention("purchaseItemWithVirtualCurrency");
IgawAdbrix.retention("inviteFriends");
 注意!!!  建议 inAppActivity 参数设置时,请使用无空白的英文及数字的字符串。

Sub Activity 设置

可以设置 Sub activity 的 API : retention API 可以设置 sub activity 
菜单 : 高级应用分析(Advanced Analytics) > 应用内活动分析(In-app activities)
目的 : 可以再详细分析用户的某行为。(例 : 登录 - KakaoTalk / Naver / Facebook)

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




高级分析 : 群组分析 (Cohort)
群组分析上可以生成最多3个用户群,同时按生成的用户群进行分析。
关于群组分析指标的说明及适用方式,请参考 [应用用户分析 : 群组分析 (Cohort)] 文档。


自定义群组设置

菜单 : adbrix 发布的所有分析报告上端 (一些报告不提供) 

目的 : 筛选用户群后,在 adbrix 上可以确认报告。(例 : 性别、年龄、购买金额等)

特征 : Custom Cohort 最多设置3个用户群。 

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

//Custom Cohort Group 1 --> 等级达成信息
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_1, "level_1");
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_1, "level_5");
IgawAdbrix.setCustomCohort(CohortVariable.COHORT_1, "level_10");

//Custom Cohort Group 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");

//Custom Cohort Group 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个群。

+ 在 adbrix 后台上可以使用群组分析功能的菜单为 

  1. 跟踪链接 > 跟踪链接报告、ROAS Reporting
  2. 基本应用分析 > 留存、活跃用户
  3. 高级应用分析 > 新增用户事件分析
  4. 收入分析报告 > 每日新增用户收入详情



高级分析 : 用户分析 (User Info)
使用如下 API,可以统计用户年龄及性别。

年龄设置

输入 1~99的用户年龄。

IgawCommon.setAge(20);



性别设置

使用 IgawCommon.Gender 上定义的内容来设置用户性别。

IgawCommon.setGender(IgawCommon.Gender.MALE);




附录 : 登录 Custom Install Receiver 

若使用多个第三方分析工具时,Google Install Referral 需向 ThirdParty Receiver 各传达并处理。

参考如下示例,建议另行创建 Receiver Class 并处理。

<!-- 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 Google Install Receiver。
        IgawReceiver igawReceiver = new IgawReceiver();
        igawReceiver.onReceive(context, intent);
        //登录需接受 INSTALL_REFERRER 的其他 Receiver。
    }
}




APPENDIX : DeepLink Tracking

为了在 adbrix 上使用 DeepLink 功能时,在应用内需支持 DeepLink。


DeepLink 设置

为了在 Android 应用上设置 DeepLink 功能,在 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 值的话,可以顺便使用 adbrix 发布的 AppKey 来生成 Scheme。

若 adbrix 发布的 AppKey 为 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>

 注意!!!  deeplink scheme 推荐为小写。[Google Development Guide]



DeepLink Open Tracking

adbrix 还支持通过 跟踪链接的 DeepLink Open 功能。

为了 DeepLink Open Tracking 数据统计,在安卓开发环境上注意一些例外处理事项。[How to set Deeplink??]



附录 : ProcessKill 使用时的 session 处理方式

adbrix Tracking Data 是在 onPause() 上调用的 endSession api 里直接传送到服务器。

但是在使用 ProcessKill 等的轻质结束方式的应用是会流失 adbrix Tracking Data。

因此参考如下内容,在安卓设备的返回按键上正常调用 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){

				// 强制终止本应用的 Process。
				android.os.Process.killProcess(android.os.Process.myPid());
 			}
    		}).setNegativeButton("否", new DialogInterface.OnClickListener(){
    			public void onClick(DialogInterface dialog, int which){
			}
    		}).show();
	}
   	return true;
}