Android SDK (Chinese)

当前 Android SDK 版本是 4.10.0

重要提示:以下快速联动指南适用于所有 TUNE 的用户。

支持 Android 平台的 TUNE SDK 提供应用会话(Application Session)和日志(Log)打印功能。TUNE SDK Android 版以单一的 Java JAR 文件的形式提供,您可以轻松将其添加到您的 Android 项目中。我们的 SDK 兼容所有 Android API 9 (2.3 GINGERBREAD)及以上版本。

遵循此快速联动指南,您可以迅速完成您的应用与 TUNE SDK 的联动,并使其正常运转。如果您的应用之前联动了 TUNE SDK 3.X 版本,并希望升级至 4.X 版本,请访问 Migrating from SDK 3.X to 4.X。如果您希望从 TUNE SDK 4.X 升级至 4.8及以上版本,请访问 Migrating to 4.8.0 and above

接下来为了开始跟踪会话(Session)和监测事件(Event),请先将 TUNE SDK 集成至您的 Android 项目 。当您的第一个 Activity 开始(Resume)之后,您便可以依靠归因分析(Attribution Analytics)去记录诸如购买、游戏等级和任何其他吸引用户的应用内事件(in-app events)。

提示:如果您的应用支持 Android API 14 及以下版本,请确认 Android API 14 and below Getting Started 指南。

 

TUNE SDK Android 版支持以下 TMC(TUNE Marketing Console) 解决方案

  •      归因分析(Attribution Analytics
  •      应用内营销(In-App Marketing需要额外的 SDK 配置,而且仅支持 v4.0.0 以上版本。)
  •      应用商店分析(App Store Analytics

下载 TUNE SDK

TUNE SDK Android 版的大小约为 260KB。在您可以下载 TUNE SDK之前,请确认您的应用已经添加到您在 TUNE 平台上的账户下。另外,TUNE SDK 也以开源的形式提供,您可以通过访问 GitHub 获取开源代码和库(Library)。

代码实现

安装 TUNE SDK时,您可以通过 Gradle 或添加 JAR 文件至项目的方式中进行选择。

Gradle

以下是通过 TUNE jCenter 去安装 TUNE SDK 的方式:

 

  1. 确认 jCenter 作为一个仓库包含在您的 Gradle 文件中。
    buildscript {
        repositories {
            [...]
            jcenter()
        }
        [...]
    }
  1. 请将如下代码添加至您的 Gradle dependency。
    compile 'com.tune:tune-marketing-console-sdk:4.10.0'

这样,TUNE SDK 将通过 Gradle 自动被添加至您的项目中。

JAR

以下是通过添加 JAR 文件至项目去安装 TUNE SDK 的方式:

  1.  请将 TuneMarketingConsoleSDK-x.y.z.jar 文件复制到您的应用项目中的 libs 路径下。如果您在使用 Gradle 的情况下,同时希望将libs本地文件夹添加至您的dependencies,可以添加如下代码:
    compile fileTree(dir: 'libs', include: ['*.jar'])
  1. 安装 EventBus 库(Library)并将其导入(import)到您的项目中。
    compile 'de.greenrobot:eventbus:2.4.0'
  1.  安装 Android Support V4 库(Library)并将其导入(import)到您的项目中。
    compile 'com.android.support:support-v4:24.+'

先决条件

Google Play Services

为了能够让TUNE SDK收集Google Advertising ID,您需要安装Google Play Services SDK 并将其导入到您的项目中。如果您正在使用 Gradle,也许您只需选择性地将 basement 库(Library)添加至您的 dependencies中即可。

compile 'com.google.android.gms:play-services-basement:10.0.0'

提示:如果您的项目已经包含了完整的Google Play Services 库(compile ‘com.google.android.gms:play-services:10.0.0’),您无需添加basement 子包。您可以使用任何高于4.0.0以上的Google Play Service 版本。

Android Manifest File

为了在集成TUNE SDK的过程中,使用您创建的自定义Application类,需要在AndroidManifest.xml文件的 <application> 标签下添加一个 android:name 来注册该自定义Application类。(已经设置自定义Application类的情况除外)另外,通过添加 <receiver> 标签,可以让 TUNE SDK 从Google收到Install Referrer,而且TUNE SDK需要获取网络连接和网络状态的权限。

在您的AndroidManifest.xml文件中添加如下代码:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>     
<application ... >        
    <receiver android:name="com.tune.TuneTracker">        
        <intent-filter>       
            <action android:name="com.android.vending.INSTALL_REFERRER" />        
        </intent-filter>
    </receiver>
</application>

提示:如果您的Android 应用添加和实现了多个用于归因分析的SDK,您也许需要多个Android INSTALL_REFERRER receiver,这时请参考Multiple Android Install Referrers。为了确认是否正确收集了 INSTALL_REFERRER,请参考 Testing the Google Play Install Referrer里介绍的测试方法。

ProGuard

如果您正在使用ProGuard,请在您的ProGuard配置文件中将TUNE 和Google Advertising ID 类从模糊(obfuscation)清单中除外。请参考如下代码:

-keep public class com.tune.** { public *; }
-keep public class com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.gcm.** { *; }
-keep public class com.google.android.gms.common.** { *; }
  
-keepclassmembers class ** {
    public void onEvent(**);
}

如果您希望进一步优化,请参考Avoiding the Dalvik 65K method Limit.

初始化 TUNE SDK

创建一个新的 Application 类,或者是更新现有类,使其可以继承TuneApplication类,之后按照如下代码初始化TUNE SDK:

import com.tune.Tune;
import com.tune.ma.application.TuneApplication;
 
public class MyApplication extends TuneApplication {
	@Override
	public void onCreate() {
        super.onCreate();
    	
    	// Initialize TMC
 	   Tune.init(this, "your_advertiser_ID", "your_conversion_key");
   	
    	//TUNE SDK 会在您的应用获取用户位置信息访问权限的情况下
    	//默认地将当前位置信息包含在事件信息中,并发送至TUNE平台
    	//如果不希望让TUNE SDK发送位置信息,可以通过下列函数关闭
        //https://developers.tune.com/sdk/automatic-collection-of-device-geo-location
Tune.setShouldAutoCollectDeviceLocation(false);
 
   	//如果您希望以调试为目的,获取服务器响应信息,需注册TuneListener。
   	//https://developers.tune.com/sdk/reading-server-responses/#code-platform-android
   	//MyTuneListener listener = new MyTuneListener();
   	//Tune.getInstance().setListener(listener);
 
//为了确认Deferred Deep Link,并在回调函数中处理Deep Link,
//需要注册TuneDeeplinkListener.
//仅当您的TMC账户激活了TUNE提供的Deferred Deep Link功能时使用。
//若要使用Deferred Deep Link功能,需要向TUNE Support申请该功能的激活。
//功能未激活时,即使登陆了监听器,也会从服务器收到失败响应。
//https://developers.tune.com/sdk/implementing-a-deferred-deep-link/#code-platform-andorid
/*
Tune.getInstance().registerDeeplinkListener(new TuneDeeplinkListener(){
@Override public void didReceiveDeeplink(String deeplink) {
        	// Handle the deferred deeplink here // e.g. open the link
        	if ( !””.equals(deeplink)) {
             	// Handle deferred deeplink
@Override public void didFailDeeplink(String error) {
         	// Error was encountered
	}
});
*/
	}
}

提示:如果您的类已经继承了其他类,您也许需要在Application的onCreate函数中调用registerActivityLifecycleCallbacks,并将TuneActivityLifecyleCallbacks作为参数进行传递。

import com.tune.ma.application.TuneActivityLifecycleCallbacks;
 
public class MyApplication extends SomeOtherClass {
    @Override
    public void onCreate() {
        super.onCreate();

        if (Build.VERSION.SDK_INT >= 14) {
            registerActivityLifecycleCallbacks(new TuneActivityLifecycleCallbacks());
        }
    }
}

为了使用您创建的自定义Application类,需要在AndroidManifest.xml文件的 <application> 标签下添加一个 android:name 来注册该自定义Application类。(已经设置自定义Application类的情况除外)

<application
    android:name=".MyApplication" />

Activities

如果您的应用支持Android API 14以下版本,您的每个Activity类都必须继承TuneActivity类。如果您的Activity类已经继承了其他类,则需要在Activity的onStart()、onResume()、onStop()函数下分别调用TuneActivity.onStart(Activity activity)、TuneActivity.onResume(Activity activity) 和 TuneActivity.onStop(Activity activity)函数。

public class MainActivity extends SomeOtherActivityNotTuneActivity {
    @Override
    public void onStart() {
        super.onStart();
        if (Build.VERSION.SDK_INT < 14) {
            TuneActivity.onStart(this);
        }
    }
  
    @Override
    public void onResume() {
        super.onResume();
        if (Build.VERSION.SDK_INT < 14) {
            TuneActivity.onResume(this);
        }
    }
  
    @Override
    public void onStop() {
        if (Build.VERSION.SDK_INT < 14) {
            TuneActivity.onStop(this);
        }
        super.onStop();
    }
}

IDs

如果您的应用只是通过Google Play 发布,可以跳过此节。如果您的应用同时在GooglePlay以外的其他Android 应用商店发布,您可以将ANDROID_ID、Device ID和MAC Address作为设备识别码进行收集。在TMC正确地在onCreate函数内初始化之后,可以通过如下设定将这些识别码传送给TUNE SDK。

(Android SDK在支持Google AID的设备上,通常只收集Google AID,仅在无法收集Google AID时收集Android ID。大部分情况下,建议遵循SDK自身的自动收集功能。收集Android ID等设备识别码时,会涉及个人隐私信息保护相关条款,所以请事先与相关人员确认并获取授权。)

Android ID

当获取Google Advertising ID失败之后,ANDROID_ID将在后台自动被收集(Amazon设备、Google Play Services 4.0以下版本)。如果您希望一直收集Android ID,可以使用如下代码实现。

import android.provider.Settings.Secure;
 
Tune.getInstance().setAndroidId(Secure.getString(getContentResolver(), Secure.ANDROID_ID));

Device ID

获取Device ID 需要android.permission.ACCESS_WIFI_STATE权限。

import android.telephony.TelephonyManager;
 
String deviceId = ((TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE)).getDeviceId();
Tune.getInstance().setDeviceId(deviceId);

MAC Address

获取MAC Address 需要android.permission.ACCESS_WIFI_STATE权限。

import android.net.wifi.WifiManager;
 
// WifiManager objects may be null
try {
    WifiManager wm = (WifiManager) getSystemService(Context.WIFI_SERVICE);
    Tune.getInstance().setMacAddress(wm.getConnectionInfo().getMacAddress());
} catch (NullPointerException e) {
}

需要注意的事项

  •   “your_advertiser_ID” 和 “your_conversion_key”的值对应于您在TMC平台上创建“Mobile App”的时候,TUNE提供的Advertiser ID和Conversion Key。有关Advertiser ID和Conversion Key的更多内容,请参考Finding Advertiser ID and Conversion Key
  •   Deferred deep linking 功能仅支持TUNE SDK for Android 3.7.0及以上版本。有关Deferred deep linking 的更多内容,请参考Implementing a Deferred Deep Link
  •   如果您的应用已有一定的用户基础(已经安装您的应用的用户),可以使用TUNE提供的几种方法识别和处理已有用户(Pre-Existing User),从而避免将这些用户归因于某个媒体。有关识别和处理已有用户的方案,可以参考handle existing users prior to SDK implementation
  •   为了提高归因的一致性和简便性,可以考虑收集Unique Identifiers for Attribution里提到的设备识别信息。
  •   TUNE SDK v4.0+将自动收集用户的位置信息,从而提高基于地理位置的用户分类。TUNE仅在终端用户授权应用使用位置信息时,收集位置信息。TUNE SDK本身不会向终端用户请求位置信息的访问权限。

测试和故障排除

  •   如果您想测试是否在您的应用上正确集成和实现了TUNE SDK,您可以直接在TUNE MAT 平台上测试,无需另行测试环境,详情参考Testing Your Mobile App

测定Event

在您的应用上集成和实现 TUNE SDK 并可以记录会话(Logging Session)之后,您可以尝试将广泛且多样的应用内事件(In-App Event)集成到您的应用中。(例如用户注册和应用内购买等)

通过记录和分析您的应用内事件,您可以更加有效的优化您的应用功能和广告战略。更重要的是您可以了解用户是如何与您的应用进行互动,从而直接地影响您构建有效、获益的广告方案。

如果您要构建自定义事件(Custom Event),请参考Event Builder

在应用程序的事件中