Интеграция AppsFlyer SDK — Android

android.pngSDK Version:  4.8.9 (Release Notes)

1. Обзор

SDK AppsFlyer предназначен для установки приложений и отслеживания событий. Разработанный нами SDK — надежный (на сегодняшний день выполнено более 7 миллиардов установок ), безопасный, легкий и очень просто встраиваемый.

Вы можете отслеживать установки приложения, обновления и сессии. А также другие внутренние события приложения (в том числе покупки из приложения, уровни игры и т. п.), что позволяет оценивать ROI и уровни вовлеченности пользователей.

AppsFlyer SDK для Android совместим с Android 2.3 и с более поздними версиями.

Для миграции с AppsFlyer SDK V.3.3.x для Android нажмите здесь.

2. Начало работы

2.1 Загрузка SDK 

Чтобы загрузить Android SDK в формате JAR, нажмите здесь.

Подробнее о примере приложения от AppsFlyer см. здесь.

2.2 Встраивание SDK в приложение

Интеграцию AppsFlyer SDK можно выполнить либо автоматически с помощью функции управления зависимостями системы Gradle, либо вручную, используя файл SDK.jar.

2.3 Добавление SDK в свой проект

Самый простой способ интеграции SDK в свой проект — это использование функции управления зависимостями системы сборки Gradle. Сведения о версиях см. здесь.

Если вы не используете Gradle, загрузите и скопируйте файл AF-Android-SDK.jar к классам вашего проекта.

Добавление AppsFlyer’s Android SDK для Android:

  1.  Откройте свой проект (или создайте новый), а затем откройте ваше_приложение | build.gradle
  2.  Добавьте этот элемент в /app/build.gradle перед блоком зависимостей:
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'
}

 Важно!

  • Зависимость 'com.android.installreferrer:installreferrer:1.0' необходима для поддержки API Google Play Install referrer. Использование этого API позволяет повысить точность атрибуции, обеспечить защиту от мошеннических установок и многое другое.
  • Поддержка этого API предусмотрена в SDK AppsFlyer для Android начиная с версии 4.8.6. При переходе с SDK более старой версии добавьте эту новую зависимость путем обновления метода инициализации SDK.
  • Разработчикам, которые используют утилиту ProGuard, и хотят использовать новый Google 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 Настройка BroadcastReceiver в AndroidManifest.xml

Есть два варианта использования Broadcast Receiver для определения источника установки (параметр referrer):

Использование одного Broadcast Receiver Использование нескольких Broadcast Receiver

Если в AndroidManifest.xml файле не присутствует ресивер для INSTALL_REFERRER добавьте следующий ресивер в тег <application>:

<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 добавьте в свое приложение функцию 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 и поместить её в любую функцию OnCreate() данной Activity. .

 Совет

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 в разделе "Конфигурация", меню "Настройки приложения":

Это API дает возможность АppsFlyer отслеживать установки, сеансы и обновления.

4. Отслеживание внутренних событий приложения (In-App Events)

Отслеживая внутренние события приложения, можно понять, что в нем происходит. для отслеживания ROI (окупаемость инвестиций) и LTV (пожизненная стоимость клиента)

Для отслеживания внутренних событий приложения используется вызов trackEvent с именем события и значениями параметров. Подробные сведения см. в статье "Внутренние события приложения".

 Примечание

Имя внутреннего события приложения должно содержать не более 45 символов. Имена событий, в которых более 45 символов, не отображаются на панели управления. Их можно увидеть только в необработанных данных, полученных с помощью Push и Pull 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);


Example
: Level Achieved In-App Event

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);
 

This generates an event of type af_level_achieved with the following event values:
{af_level: 9, af_score: 100}

 Примечание

  • AppsFlyer supports non-English characters with in-app events, or with any other SDK API, starting from Android SDK version 4.8.1.
  • 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. Отслеживание диплинков

 Совет

Настоятельно рекомендуется интегрировать диплинкинг в ваше приложение. Диплинкинг — это важная часть ретаргетинговых кампаний, и его необходимо использовать при проведении таких кампаний.

Для каждой активности, которая может использоваться для диплинкинга (при необходимости и для основной активности), добавьте в onCreate() такую строку:

AppsFlyerLib.getInstance().sendDeepLinkData(this);

Activities которые открываются при Deeplinking, должны содержать следующий intent-filter в определении Activity в manifest файле. 

<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.

Для получения данных диплинкинга необходимо реализовать обратный вызов метода onAppOpenAttribution , который вызывается из AppsFlyer SDK.  Этот вызов возвращает параметры ссылки Onelink/tracking, которые используются для запуска приложения. Затем можно проанализировать значения и применить логику для вызова соответствующей страницы приложения.

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, которая будет отображаться на панели управления. 

 Примечание

Setting user local currency code for in app purchases - the currency code should be a 3 character ISO 4217 code. (default is USD). 

You can set the currency code for all events by calling the following method: AppsFlyer.setCurrencyCode("GBP");

7. Получение данных о конверсиях

AppsFlyer предоставляет доступ к данным атрибуции пользователей для каждой новой установки в реальном времени непосредственно на уровне SDK. Таким образом, можно предоставлять пользователям персонализированный контент или направлять их на определенные действия в приложении, что может значительно увеличить их взаимодействие с вашим приложением.

Для доступа из SDK для Android к данным о конверсиях в AppsFlyer используйте ConversionDataListener:

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


Example:

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 создает уникальный AppsFlyer ID . Чтобы узнать его, используйте следующий API:

public String getAppsFlyerUID(Context context);


Usage Example:

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

Установка Customer User ID

Установка собственного ID клиента позволяет создать перекрестные ссылки между своим уникальным ID и уникальным ID AppsFlyer, а также ID других устройств. Этот идентификатор можно посмотреть в отчетах AppsFlyer в формате CSV, а также получить с помощью Postback API для перекрестных ссылок между внутренними идентификаторами.

Для установки своего Customer User ID используйте такой код:

public void setCustomerUserId(String id);


Usage Example:

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

 Примечание

Идентификатор customerUserID ДОЛЖЕН быть задан перед trackAppLaunch. Рекомендуется установить свой Customer User ID как можно скорее, поскольку только этот идентификатор будет связан с событиями, включенными в отчеты после его установки. Customer User ID можно также использовать для интеграции с аналитическими платформами, такими как Mixpanel и Swrve.

Подробные сведения о Customer User ID см. здесь.

Настройка User Email

AppsFlyer позволяет включать в отчеты один или несколько адресов электронной почты, связанных с устройством. Необходимо собирать данные об адресах электронной почты и передавать их в AppsFlyer, используя требуемый метод шифрования.

Можно использовать следующие методы шифрования: SHA1, MD5, SHA256 и прямое шифрование.

Пример:

public void setUserEmails(String... emails);


Usage Example:

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

 Примечание

AppsFlyer несохраняет персональные данные, такие как адреса электронной почты, и эти данные не отображаются в отчетах. Сбор таких данных проводится исключительно для обратной передачи медиа-источнику.

Google Advertising ID

Начиная с версии 4.8.0, AppsFlyer SDK автоматически выполняет сбор идентификаторов рекламы Google google_advertising_id. Требование включать сбор идентификаторов рекламы Google относится только к SDK версии 4.7.X или более старых версий.

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). 

Чтобы гарантированно отправить эти идентификаторы в AppsFlyer, разработчики могут использовать такие API:

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.

Для отмены сбора данных IMEI и Android ID разработчики могут использовать такие API:

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

 Предупреждение

Для правильной атрибуции НЕОБХОДИМО получить ID хотя бы одного из этих идентификаторов: GAID, Android ID или IMEI.

9. Дополнительные возможности

Отслеживание удалений

С помощью AppsFlyer можно отслеживать удаление приложения.

Чтобы правильно выполнить эту процедуру и использовать все ее возможности, ознакомьтесь с этой статьей.

Отслеживание Push-уведомлений 

AppsFlyer позволяет учитывать пуш-уведомления при проведении ретаргетинговой кампании.

Чтобы включить эту функцию, добавьте приведенный ниже метод в каждую Activity внутри метода 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\" } } }"

 Примечание

Подробнее об измерении push-уведомлений см. здесь.

Отслеживание Cross Promotion  

AppsFlyer allows you to track and attribute installs originating from a cross promotion of one of your apps from within the current app the user has. Cross promoting apps can be a major growth factor in driving additional installs for your apps.

For details, see the Cross Promotion Tracking article, here.

Отслеживание пользовательских приглашений

AppsFlyer allows you to track and attribute installs originating from user invites within your app. Allowing your existing users to invite their friends and contacts as new users to your app can be a key growth factor for your app.

For details, see the User Invite Tracking article, here.

Установка кода валюты 

Можно установить коды конкретных валют, используемых в каждом внутреннем событии приложения, которые передаются в AppsFlyer. Еще можно установить код глобальной валюты. Код глобальной валюты используется в тех случаях, когда параметр af_currency

AFInAppEventParameterName.CURRENCY

не передается вместе с данными внутреннего события приложения.

По умолчанию используется код USD (американский доллар). Коды валют по стандарту ISO см. здесь.

Чтобы установить код валюты, используйте этот API:

public void setCurrencyCode(String currencyCode);

Пример использования:

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

Валидация покупок в приложении

При покупках из приложения AppsFlyer SDK выполняет проверку сервера. Чтобы запустить отслеживание валидации покупок, вызовите метод validateAndTrackInAppPurchase внутри функции onActivityResult.

Этот запрос автоматически создает событие внутри приложения af_purchase.

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

Этот вызов содержит два блока обратного вызова — один для варианта «Успешно», а второй для варианта «Ошибочно» (по любой причине, включая сбой проверки).

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);
         }
     });


Usage Example:

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);
      }
  }
} 

Anonymize User Data

AppsFlyer provides you with a method to anonymize specific user identifiers in AppsFlyer analytics. This method complies with the latest privacy requirements and complies with Facebook data and privacy policies. Default is NO, meaning no anonymization is performed by default.

Use this API during the SDK Initialization to explicitly anonymize a user's installs, events and sessions:

public void setDeviceTrackingDisabled(boolean isDisabled);


Usage Example:

AppsFlyerLib.getInstance().setDeviceTrackingDisabled(true);

Если вам нужно запустить отслеживание снова, то вызовите еще раз deviceTrackingDisabled со значением false.

 Предупреждение

Anonymizing users SEVERELY impacts your attribution information.
Use this option ONLY for regions which legally prevents you from collecting your users' information.

Настройка временного интервала между сеансами

Чтобы AppsFlyer мог учитывать отдельные сеансы, интервал между ними должен быть не меньше 5 секунд (значение по умолчанию). Начало сеанса — это момент открытия приложения пользователем. Если нужно установить другой интервал между сеансами, используйте этот API: AppsFlyerLib.setMinTimeBetweenSessions(int seconds);

Фоновые сеансы для служебных приложений

Если ваше приложение — это служебное приложение, работающее в фоновом режиме, то в активности onCreate() этот API можно использовать так:

public void reportTrackSession(Context context);


Usage Example:

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" />

 Примечание

Значение CHANNEL задается на панели управления AppsFlyer во время настройки приложения.

Тег метаданных нужно поместить перед тегом </application>.

Подробные сведения об отслеживании установок приложений, приобретенных не в магазине, см. здесь.

Opt Out

In some extreme cases you might want to shut down all SDK tracking due to legal and privacy compliance. This can be achieved with the isStopTracking API. Once this API is invoked, our SDK will no longer communicate with our servers and stop functioning.

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

In any event, the SDK can be reactivated by calling the same API, but to pass false.

 Предупреждение

Use this API only in cases where you want to fully ignore this user from any and all tracking. Using this API SEVERELY impacts your reporting and attribution..

Delay SDK init for customerUserID

It is possible to delay the SDK Initialization until the customerUserID is set. This feature makes sure that the SDK doesn't begin functioning until the customerUserID is provided. If this API is used, all in-app events and any other SDK API calls are discarded, until the customerUserID is provided and tracked.

To indicate that the SDK should delay initialization for the customer user id call AppsFlyerLib.getInstance().waitForCustomerUserId(true); immediately before the init() method. The rest of the SDK initialization should remain unchanged.

Once the customerUserID has been provided, call AppsFlyerLib.getInstance().setCustomerIdAndTrack("customer_id", this); to provide the SDK with the relevant customer user id and trigger the SDK to begin its normal tracking.

The code should appear as follows:
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);
       // Do your magic to get the customerUserID
       // ...
       // any AppsFlyer SDK code invoked here will be discarded
      //Call the following API once the customerUserID is available:
 AppsFlyerLib.getInstance().setCustomerIdAndTrack("customer_id", this);
   }
}

 Предупреждение

Use this API only in cases where it is appropriate for your business logic. Using this API increases the chance for discrepancies and might make the app more exposed to fraud.

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);

10. Тестирование интеграции SDK

Описание процедуры тестирования интеграции SDK до и после отправки приложения в магазин Google Play см. здесь.

11. Известные проблемы

Если вы используете ProGuard и получили предупреждение относительно нашего AFKeystoreWrapper, добавьте в свой файл правил ProGuard такой код:

-dontwarn com.appsflyer.*
Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 12 из 14

Комментарии

0 комментариев

Войдите в службу, чтобы оставить комментарий.

Статьи в этом разделе