AppsFlyer SDK 对接 - Android

android.pngSDK Version:  4.8.13 (Release Notes)

1. 概述

AppsFlyer SDK为移动应用提供安装和应用内事件的追踪。我们所开发的 SDK 不但非常强大(目前 SDK 安装量已经超过 70 亿)、安全、轻量化,而且可以轻松内嵌。

您可以追踪安装、更新和互动以及应用安装以外的其他应用内事件(包括应用内购买、游戏级别等),以评估 ROI 和用户互动水平。

AppsFlyer Android SDK 兼容 Android 2.3 及以上版本。

如果您要把 AppsFlyer Android SDK 从3.3.x 升级到更高版本,请点击此处

2. 快速开始

2.1 SDK 下载

要下载 Android SDK 文件,请点击此处

如需了解 AppsFlyer 样本应用的详细信息,请点击此处

2.2 将 SDK 嵌入应用

您可以使用 Gradle 的 Dependency Management 自动对接 AppsFlyer SDK,也可以将其作为 SDK.jar 手动对接。

2.3 将 SDK 添加到项目中

将 SDK 对接到您的项目的最简单的方式就是使用 Gradle 的 Dependency Management。如需了解版本信息,请点击此处

如果您使用的不是 Gradle,下载 AF-Android-SDK.jar 并将其添加到项目的类路径中。

添加 AppsFlyer 的 Android SDK Dependency:

  1.  打开项目(或创建新项目),接着打开 your_app | build.gradle
  2.  将其添加到模块级别 /app/build.gradle,在此之前添加 Dependency:
repositories {
mavenCentral()
}


Add the compile dependency with the latest version of the AppsFlyer SDK in the 
build.gradle file: 

dependencies {
compile 'com.appsflyer:af-android-sdk:4+@aar'
compile 'com.android.installreferrer:installreferrer:1.0'
}

 重要信息!

  • 如果需要支持 Google Play Install referrer API,必须添加 'com.android.installreferrer:installreferrer:1.0' 依赖项。使用此 API 可提高归因的准确性,能有效预防安装作弊等现象。
  •  AppsFlyer Android SDK 版本 4.8.6 和更高版本均支持此 API。如果从旧 SDK 版本更新,可通过更新 SDK 初始化方法完成新 Dependency 对接。
  • 正在使用 ProGuard 并希望使用 Google 的新 referrer API 的开发者必须设置下列 ProGuard 规则:
    -dontwarn com.android.installreferrer
  • Developers who are not using gradle build or aar and want to use Google's new referrer API must manually add com.android.installreferrer jar as a file, and ensure that the following permission is added:
    com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE

2.4 设置所需的许可

AndroidManifest.xml 应包括下述许可:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- Optional : -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

2.5 在 AndroidManifest.xml 中设置 BroadcastReceiver

执行 install referrer broadcast receiver 可以使用下面的两个选项:

使用单个 Broadcast Receiver 使用多个 Broadcast Receiver

在AndroidManifest.xml中,请添加以下监听器作为 INSTALL_REFERRER 中第一个监听器,并确保监听器在application tag中:

<receiver android:name="com.appsflyer.SingleInstallBroadcastReceiver" android:exported="true">
    <intent-filter>
         <action android:name="com.android.vending.INSTALL_REFERRER" />
     </intent-filter>
</receiver>

3. SDK 初始化

Initialization of the SDK is completed in two stages. In the first stage the DevKey is supplied along with your app ID and an optional conversionDataListener. In the second stage the call to startTracking indicates that all relevant preparations are complete (e.g. call setCustomerUserId) and the SDK can start tracking all events.

要初始化 SDK,将下列代码添加到您应用的Application onCreate() 函数中:

public class AFApplication extends Application {
   private static final String AF_DEV_KEY = "<your-appsflyer-dev-key>";
   @Override
   public void onCreate() {
       super.onCreate();
       AppsFlyerConversionListener conversionDataListener =
new AppsFlyerConversionListener() {
           ...
       };
AppsFlyerLib.getInstance().init(AF_DEV_KEY, conversionDataListener, getApplicationContext());
       AppsFlyerLib.getInstance().startTracking(this);   }
}

 注意

您还可以延迟调用 startTracking,并将其放到任何相关的 Activity OnCreate() 函数内。

 提示

The following dependancy: compile 'com.android.installreferrer:installreferrer:1.0' And the getApplicationContext() passed in the following method: AppsFlyerLib.getInstance().init(AF_DEV_KEY, getConversionListener(), getApplicationContext()); are the prerequisite for reporting Google's New Referrer API to AppsFlyer.

您可以在AppsFlyer 控制面板左栏“配置(Configuration)”下的“应用设置(App Settings)“处,找到您账户的 Dev Key:

该 API 确保 AppsFlyer 可以成功检测安装、事件、回话和应用更新。

4. 追踪应用内事件

应用内事件能够为您提供用户在安装应用后,与应用交互行为的深入分析。强烈建议花些时间定义需要监测的应用内事件,以追踪投资回报率 (ROI) 和用户生命周期价值 (LTV)等数据。

追踪应用内事件是通过调用 trackEvent ,传输事件名称和数值参数来实现的。如需了解更多详细信息,请参阅应用内事件文档

 注意

应用内事件名称长度不得超过 45 个字符。超过 45 个字符的事件名称不会出现在控制面板中,只会出现在原始数据、Pull API 和 Push API 中。

//context - use getApplicationContext()
//eventName is any string to define the event name.
//eventValues is a map of event parameters that comprise a rich event.  
public static void trackEvent(Context context, String eventName, Map eventValues);


示例
:达到级别的应用内事件

Map<String, Object> eventValue = new HashMap<String, Object>();
eventValue.put(AFInAppEventParameterName.LEVEL,9);
eventValue.put(AFInAppEventParameterName.SCORE,100);
AppsFlyerLib.getInstance().trackEvent(context,AFInAppEventType.LEVEL_ACHIEVED,eventValue);
 

这样可以生成 af_level_achieved 类型的事件,包含下列事件值:
{af_level: 9, af_score: 100}

 注意

  • 从 Android SDK 4.8.1 版起,AppsFlyer 支持应用内事件或任何其他 SDK API 使用非英语字符。
  • Do not to add any currency symbol or decimal points to the figures, as these are not recognized.

 Usage Example

Map<String,Object> eventValues = new HashMap<>();
eventValues.put(AFInAppEventParameterName.REVENUE, "1200");
eventValues.put(AFInAppEventParameterName.CURRENCY, "JPY");
        
AppsFlyerLib.getInstance().trackEvent(this, AFInAppEventType.PURCHASE, eventValues);

5. 追踪深度链接

 提示

我们强烈建议将深度链接与您的应用相对接。深度链接是访客找回营销活动的重要组成部分,强烈建议您在开展访客找回营销活动时使用这一功能。

For each activity that may be used for deep linking (including the main activity if needed) add the following line in the onCreate():

AppsFlyerLib.getInstance().sendDeepLinkData(this);

通过 Deeplinking 开启的 activity 需在 manifest 文件中含有以下 activity 定义。 

<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="yourUniquescheme" />
</intent-filter>


The 
Scheme configured correlates with the af_dp value you include in your tracking link.

要接收您的深度链接数据,您必须执行通过 AppsFlyer SDK 调用的回调方法 onAppOpenAttribution。您可利用此回调获取OneLink/追踪链接中的参数信息,来自定义不用来源的用户在应用内深度跳转。

void onAppOpenAttribution(Map<String,String> attributionData);

如需了解更多信息,请点击此处,或查看本文章中的获取转化数据一节。

6. 追踪收入

Use the af_revenue (AFInAppEventParameterName.REVENUE) event parameter to count revenue as part of an in-app event. You can populate it with any numeric value, positive or negative.

 注意

af_revenue is the ONLY event parameter that is counted on AppsFlyer as real revenue on the raw data and dashboard. For more details please click here.

示例:付费收入类的应用内事件

Map<String, Object> eventValue = new HashMap<String, Object>();
eventValue.put(AFInAppEventParameterName.REVENUE,200);
eventValue.put(AFInAppEventParameterName.CONTENT_TYPE,"category_a");
eventValue.put(AFInAppEventParameterName.CONTENT_ID,"1234567");
eventValue.put(AFInAppEventParameterName.CURRENCY,"USD");
AppsFlyerLib.getInstance().trackEvent(context,AFInAppEventType.PURCHASE,eventValue);

这样可以生成 af_purchase 类型的事件,包含下列事件值:

{af_content_id: “1234567”, af_content_type: “category_a”, af_revenue: 200, af_currency: “USD”}

上述购买事件包含 $200 的收入,展示在 AppsFlyer 控制面板中的收益(Revenue)里。 

 注意

为应用内购买设置用户当地的货币代码。货币代码应为 3 个字符的 ISO 4217 代码。(默认设置为 USD)。 

您可以通过调用以下方法来为所有事件设置货币代码:AppsFlyer.setCurrencyCode("GBP");

7. 获取转化数据

AppsFlyer 令您可以直接在 SDK 级别上实时访问每次新安装的用户归因数据。这样,您就可以为用户提供个性化内容或将内容发送到应用内的特定活动,这样可以大大增强与应用的互动。

要通过 Android SDK 访问 AppsFlyer 的转化数据,请执行 ConversionDataListener:

public interface AppsFlyerConversionListener {
       void onInstallConversionDataLoaded(Map<String,String> conversionData);
       void onInstallConversionFailure(String errorMessage);
}


示例

AppsFlyerLib.getInstance().registerConversionListener(this,new AppsFlyerConversionListener() {
  @Override
  public void onInstallConversionDataLoaded(Map<String, String> conversionData) {
      for (String attrName : conversionData.keySet()){
          Log.d(AppsFlyerLib.LOG_TAG, "attribute: " + attrName + " = " + conversionData.get(attrName));
      }
  }
  @Override
  public void onInstallConversionFailure(String errorMessage) {
      Log.d(AppsFlyerLib.LOG_TAG, "error getting conversion data: " + errorMessage);
  }
  @Override
  public void onAppOpenAttribution(Map<String, String> conversionData) {
  }
  @Override
  public void onAttributionFailure(String errorMessage) {
      Log.d(AppsFlyerLib.LOG_TAG, "error onAttributionFailure : " + errorMessage);
  }
}); 

8. 用户标示符

获取 AppsFlyer Device ID

应用内的每次新安装都会创建一个 AppsFlyer 独有的 device ID。使用下列 API 获取 AppsFlyer 独有的 ID:

public String getAppsFlyerUID(Context context);


使用示例:

String appsFlyerId = AppsFlyerLib.getInstance().getAppsFlyerUID(this);

设置客户用户 ID

设置您自己的客户 ID 可以帮助您交叉引用自己的独有 ID 以及 AppsFlyer 的独有 ID 和其他设备的 ID。该 ID 与回传 IP 一同出现在 AppsFlyer CSV 报告中,用于与您的内部 ID 交叉引用。

要设置您的客户用户 ID:

public void setCustomerUserId(String id);


使用示例:

AppsFlyerLib.getInstance().setCustomerUserId("myId");

 注意

customerUserID 应在 trackAppLaunch 之前设置。建议您尽快设置自己的客户用户 ID,因为此 ID 只与设置后报告的事件关联。客户用户 ID 还可以用于完成与 MixpanelSwrve 等分析平台的对接。

了解客户用户 ID 的更多信息,请单击此处

设置用户电子邮件

AppsFlyer 允许您报告一个或多个设备的关联电子邮件地址。您必须收集电子邮件地址并按照要求的加密方法报告给 AppsFlyer。

可以采用下列加密方法:SHA1、MD5、SHA256 和明文加密。

示例:

public void setUserEmails(String... emails);


使用示例:

AppsFlyerLib.getInstance().setUserEmails(AppsFlyerProperties.EmailsCryptType.MD5, "email1@domain.com","email2@domain.com",….);

 注意

AppsFlyer 不会保留电子邮件地址等个人可识别信息 (PII),此类信息不会出现在报告中。收集此类信息的目的仅限于向媒体渠道回传。

Google Advertising ID

从 SDK 4.8.0 版起,AppsFlyer 会自动收集 google_advertising_id。只有 SDK 4.7.X 及以下版本需要收集 Google Advertising ID。

IMEI 和 Android ID

By default, IMEI and Android ID are not collected by the SDK if the OS version is higher than KitKat (4.4) and the device contains Google Play Services (on SDK versions 4.8.8 and below the specific app needed GPS). 

To explicitly send these IDs to AppsFlyer, developers can use the following APIs and place it before the startTracking code:

AppsFlyerLib.getInstance().setImeiData("IMEI_DATA_HERE");
AppsFlyerLib.getInstance().setAndroidIdData("ANDROID_ID_DATA_HERE");

If the app does NOT contain Google Play Services, the IMEI and Android ID are collected by the SDK. However, apps with Google play services should avoid IMEI collection as this is in violation of the Google Play policy.

开发者可以使用这些 API 停止收集 IMEI 和 Android ID:

AppsFlyerLib.getInstance().setCollectIMEI(false);
AppsFlyerLib.getInstance().setCollectAndroidID(false);

 警告

为了进行正确归因,必须至少收集一个设备标示符,即 GAID、Android ID 或 IMEI。

9. 可选功能

追踪卸载

AppsFlyer 令您能够追踪应用的卸载。

要完整、正确地完成此过程,请务必点击此处阅读说明。

追踪推送通知 

推送通知是访客找回营销活动的一部分,AppsFlyer 使您能够对其进行监测。

要启用该功能,在点击通知时,每一个行为 onCreate 方法都会启动,您需要调用其中的下一个方法:

AppsFlyerLib.getInstance().sendPushNotificationData(this);

数据有效载荷应包含一个对象:具有相关键值字符串的 af

示例

\"data\": { \"score\": \"5x1\", \"time\": \"15:10\" , \"af\" : { \"c\" : \"test_campaign\" , \"is_retargeting\" : \"true\" , \"pid\" : \"push_provider_int\" } } }"[with deep-linking] \"data\": { \"score\": \"5x1\", \"time\": \"15:10\", \"click_action\" : \"com.example.someAction\", 
\"af\" : { \"c\" : \"test_campaign\" , \"is_retargeting\" : \"true\" , \"pid\" : \"push_provider_int\" } } }"

 注意

了解关于推送通知监测的更多信息,请点击此处阅读说明。

交叉促销追踪 

AppsFlyer 允许您对用户现有应用中的交叉促销带来的安装进行追踪和归因。交叉促销应用可能成为增加您的应用安装量的主要增长因素之一。

了解详细信息,请点击此处参阅“交叉促销追踪”文章。

用户邀请追踪

AppsFlyer 允许您追踪并归因从应用内的用户邀请发起的安装。允许您现有的用户邀请朋友或联系人成为您应用的新用户,这可以成为应用的一个关键增长因素

了解详细信息,请点击此处参阅“用户邀请追踪”文章。 

设置货币代码 

You can set a global currency code using the API below, in addition to specific currency codes that can be used as part of each in-app event sent to AppsFlyer. The global currency code is used when af_currency

AFInAppEventParameterName.CURRENCY

未作为应用内事件的一部分发送时,则使用全局货币代码。

默认值为 USD。您可以在这里找到 API 可用的 ISO 货币代码。

使用以下 API 设置货币代码:

public void setCurrencyCode(String currencyCode);

用法示例:

AppsFlyerLib.getInstance().setCurrencyCode("GBP");

应用内购买验证

AppsFlyer 的 SDK 对于应用内购买提供服务器验证。要设置购买验证追踪,请在 onActivityResult 函数中调用 validateAndTrackInAppPurchase 方法。

该方法调用将自动生成一个 af_purchase 应用内事件。

public static void validateAndTrackInAppPurchase(
                     Context context,
                     String publicKey,
                     String signature,
                     String purchaseData,
                     String price,
                     String currency,
                     HashMap<String, String> additionalParameters);

This call has two callback blocks, one for ‘Success’ and one for ‘Failure’ (for any reason, including validation fail).

AppsFlyerLib.getInstance().registerValidatorListener(this,new
    AppsFlyerInAppPurchaseValidatorListener() {
         public void onValidateInApp() {
             Log.d(TAG, "Purchase validated successfully");
         }
         public void onValidateInAppFailure(String error) {
             Log.d(TAG, "onValidateInAppFailure called: " + error);
         }
     });


使用示例:

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  if (requestCode == 1001) {
      String purchaseData = data.getStringExtra("INAPP_PURCHASE_DATA");
      String dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE");
      if (resultCode == RESULT_OK) {
          HashMap<String,String> event = new HashMap<>();
          event.put(AFInAppEventParameterName.PRICE,"9");
          AppsFlyerLib.getInstance().validateAndTrackInAppPurchase(getApplicationContext(),publicKey, dataSignature, purchaseData, "3.00", "ILS", event);
      }
  }
} 

匿名用户数据

AppsFlyer 为您提供在 AppsFlyer 分析中匿名特定用户标示符的方法。该方法符合最新的隐私要求并遵守 Facebook 数据和隐私政策。默认为 NO,表示默认未进行匿名。

在 SDK 初始化过程中,使用该 API 明确匿名用户安装、事件和互动:

public void setDeviceTrackingDisabled(boolean isDisabled);


使用示例:

AppsFlyerLib.getInstance().setDeviceTrackingDisabled(true);

可以通过再次调用 deviceTrackingDisabled,并设置为 false,重新启动追踪。

 警告

对用户匿名会严重影响您的归因信息。
只在法律要求您不得收集用户信息的地区使用此选项。

自定义互动之间的时间

为了让 AppsFlyer 能够计算两次互动之间的时间,每次互动的默认时间必须至少为 5 秒。用户打开应用时,互动开始。如果您想要为互动间隔另行配置时间,请使用以下 API:AppsFlyerLib.setMinTimeBetweenSessions(int seconds);

Background Sessions for Utility Apps

If your app is a utility app running in the background you can use this API in your activity’s onCreate() -

public void reportTrackSession(Context context);


使用示例:

AppsFlyerLib.getInstance().reportTrackSession(context);

追踪商店外应用 

 注意

Google Play 为默认应用商店。如果您的应用只在 Google Play 上发布,请跳过这一部分。

要追踪 Google Play 商店外的安装,请在应用的 AndroidManifest.xml 中设置渠道/商店,各 APK 应具有唯一的渠道或商店名称。CHANNEL 的值区分大小写。

示例

<meta-data android:name="CHANNEL" android:value="Amazon" />
<meta-data android:name="CHANNEL" android:value="Standalone"/>
<meta-data android:name="CHANNEL" android:value="Verizon" />

 注意

必须在设置应用时在 AppsFlyer 控制面板上配置 CHANNEL 的值。

Place the meta-data tag before the </application> tag.

了解关于如何追踪商店外应用安装的更多详细信息,请点击此处阅读说明。

Opt Out

在某些极端情况下,您可能出于法律和隐私合规方面的考虑,希望关闭所有 SDK 追踪。使用 isStopTracking API 可实现此功能。一旦调用该 API,SDK 将停止运行,不再与服务器通信。

AppsFlyerLib.getInstance().stopTracking(true,context);

在任何情况下,可调用相同 API 以重新激活 SDK,但会传递 False。

 警告

仅在您完全不想追踪该用户时,使用该 API。使用该 API 会严重影响您的报告和归因。

Delay SDK init for customerUserID

可以延迟 SDK 的初始化,直到 customerUserID 设置完毕。此功能可确保在提供 customerUserID 之前,SDK 不会运行。如果使用此 API,所有应用内事件以及任何其他 SDK API 调用都被忽略,直到提供 customerUserID 并对其进行追踪。

要指示 SDK 延迟客户用户 ID 的初始化,在 init() 方法之前立即调用 AppsFlyerLib.getInstance().waitForCustomerUserId(true);。SDK 初始化的其他部分保持不变。

在提供 customerUserID 后,调用 AppsFlyerLib.getInstance().setCustomerIdAndTrack("customer_id", this);,向 SDK 提供相关的客户用户 ID,并触发 SDK 开始正常追踪。

代码应如下所示:
public class AFApplication extends Application {
   private static final String AF_DEV_KEY = ;
   @Override
   public void onCreate() {
       super.onCreate();
AppsFlyerConversionListener conversionDataListener = 
       new AppsFlyerConversionListener() {
           ...
       };
       AppsFlyerLib.getInstance().waitForCustomerUserId(true); 
AppsFlyerLib.getInstance().init(AF_DEV_KEY,getConversionListener(), getApplicationContext());
       AppsFlyerLib.getInstance().startTracking(this);
// 正确设置以获取 customerUserID
       // ...
       // 此时对 AppsFlyer SDK 代码的任何调用都将被忽略
      //一旦 customerUserID 可用,调用以下 API:
 AppsFlyerLib.getInstance().setCustomerIdAndTrack("customer_id", this);⏎   }⏎}

 警告

仅在适合您的业务逻辑的情况下使用此 API。使用此 API 会提高数据差异的几率,并且可能使应用更容易暴露于诈骗中。

Setting Additional Data

The setAdditionalData API is required to integrate on the SDK level with several external partner platforms, including Segment, Adobe and Urban Airship. Use this API only if the integration article of the platform specifically states setAdditionalData API is needed.
The following is a code example for implementing setAdditionalData on Android:

HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("custom_param_1","value_of_param_1");
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);

Attribution for Pre-Installed Apps

There are various methods available for Android attribution for pre-installed apps.

For details, click here.

10. 测试 SDK 对接

要在提交到 Google Play 商店之前或之后测试 SDK 对接,请点击此处

11. 已知问题

If you are using ProGuard and you encounter a warning regarding our AFKeystoreWrapper class, then add the following code to your ProGuard rules file:

-dontwarn com.appsflyer。*
这篇文章有帮助吗?
16 人中有 14 人觉得有帮助

评论

0 条评论

登录写评论。