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

Official_unity_logo.png

Current Unity SDK Version:  v4.17.0
Compatible with Android SDK v4.8.13 and iOS SDK v4.8.7

1. Обзор

С помощью функций AppsFlyer SDK мобильные приложения могут отслеживать установки и события в устройствах на платформах Android, iOS, Windows Phone и на других.

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

Мобильные приложения, созданные на платформе Unity, с интегрированным AppsFlyer SDK можно использовать для отслеживания событий как в приложениях, созданных на платформе Android, так и созданных на платформе iOS. Это руководство содержит подробные инструкции по интеграции AppsFlyer SDK в приложения Unity для использования с приложениями iOS и Android.

 Примечание

AppsFlyer поддерживает интеграцию с Unity версии 5 и выше

 Важно!

Google Play Install Referrer API поддерживается, начиная с плагина Unity версии 4.16.0. Для использования нового Referrer API обновите плагин до 4.16.0 или более поздней версии.

 Совет

  • Chapters 2 and 3 are MANDATORY to implement BASIC SDK integration, i.e. install attribution only
  • Tracking in-app events chapter is HIGHLY RECOMMENDED to implement
  • The rest of the described features are OPTIONAL to implement, although some of them may be necessary for you, depending on your app's business logic. For example, tracking revenue or getting the conversion data on first launch may be vital for your app's flow

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

2.1 Загрузка плагина AppsFlyer для Unity

Этот плагин можно загрузить на веб-сервисе Github по ссылке https://github.com/AppsFlyerSDK/Unity

Далее даны инструкции по интеграции плагина AppsFlyer для использования с платформой Unity.

2.2 Установка плагина

Далее даны инструкции по установке плагина AppsFlyer:

  1. Выполните импорт пакета AppsFlyerUnityPlugin.unitypackage в свой проект Unity.
  2. Последовательно выберите Assets >> Import Package >> Custom Package
  3. Выберите файл AppsFlyerUnityPlugin.unitypackage.

2.3 Обязательные настройки для Android и iOS

Настройки для Android


Настройка приемника AF и разрешений для AndroidManifest.xml:

<!-- receiver should be inside the <application> tag -->
<receiver android:name="com.appsflyer.MultipleInstallBroadcastReceiver" android:exported="true">
        <intent-filter>
                <action android:name="com.android.vending.INSTALL_REFERRER" />
        </intent-filter>
</receiver>
<!-- Mandatory permission: -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />


Настройка требуемых разрешений

Файл 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" />


Настройка BroadcastReceiver в AndroidManifest.xml

Есть два варианта реализации приемника широковещательных сообщений об источнике установки (параметр referrer):

Использование одного приемника широковещательных сообщений Использование нескольких приемников широковещательных сообщений

Если в файле 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>

Настройки для iOS


Связанные фреймворки и библиотеки


После создания проекта в Unity для xCode необходимо добавить Security.Framework в разделСвязанные структуры и библиотеки xCode, если данная структура не была добавлена ранее.


iOS Apple Search Ads

Добавьте такие файлы:

AdSupport.framework
AppsFlyer выполняет сбор данных IDFA только при наличии в проекте приложения этой структуры. Если не добавить эту структуру, то нельзя будет отслеживать статистику в Facebook, Twitter и многих других.
iAd.framework

Настоятельно рекомендуется включить эту структуру в проект приложения, т.к. она необходима для отслеживания Apple Search Ads.

3. Инициализация SDK

В методах Start / Init выполняется настройка ключа разработчика AppsFlyer и уникальных ID приложений, используемых в iTunes и Google Play. Примите во внимание, что при задании ID приложений для iOS здесь нужно использовать только цифры без префикса "id".

Добавьте следующий код:

Плагин Unity 4.15.1 и выше Плагин Unity 4.14.3 и ниже
void Start () {
/* Mandatory - set your AppsFlyer’s Developer key. */
AppsFlyer.setAppsFlyerKey ("YOUR_APPSFLYER_DEV_KEY");
/* For detailed logging */
/* AppsFlyer.setIsDebug (true); */
#if UNITY_IOS
   /* Mandatory - set your apple app ID
      NOTE: You should enter the number only and not the "ID" prefix */
   AppsFlyer.setAppID ("YOUR_APP_ID_HERE");
   AppsFlyer.trackAppLaunch ();
#elif UNITY_ANDROID
   /* Mandatory - set your Android package name */
   AppsFlyer.setAppID ("YOUR_ANDROID_PACKAGE_NAME_HERE");
   /* For getting the conversion data in Android, you need to add the "AppsFlyerTrackerCallbacks" listener.*/
   AppsFlyer.init ("YOUR_APPSFLYER_DEV_KEY","AppsFlyerTrackerCallbacks");
#endif
}

 Важно!

  • В коде для ОС Android метод AppsFlyer.init включает в себя вызов trackAppLaunch. Поэтому не включайте вызов trackAppLaunch в сборку плагина Unity для Android.
  • В iOS отклик на вызов для получения данных о конверсиях инициируется в классе AppsFlyerTrackerCallbacks.cs.

4. Отслеживание событий внутри приложения

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

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

 Примечание

Название события внутри приложения должно содержать не более 45 символов. Названия, в которых более 45 символов, не отображаются на панели управления. Их можно увидеть только в необработанных данных, полученных с помощью Push и Pull API.


Пример отслеживания события:

System.Collections.Generic.Dictionary<string, string> purchaseEvent = new   
System.Collections.Generic.Dictionary<string, string> ();
purchaseEvent.Add ("af_currency", "USD");
purchaseEvent.Add ("af_revenue", "0.99");
purchaseEvent.Add ("af_quantity", "1");
AppsFlyer.trackRichEvent ("af_purchase", purchaseEvent);

 Примечание

Начиная с SDK для Unity версии 4.15.1, AppsFlyer поддерживает не только английские символы для событий внутри приложения и всех других API для SDK.

5. Отслеживание диплинков

For deep linking, follow the instructions according to your operating system.

Android iOS
Добавьте в файл манифеста следующие строки:

<activity android:name="com.appsflyer.GetDeepLinkingActivity" android:exported="true">
 <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" />
 </intent-filter>
</activity>

6. Отслеживание выручки

Используйте параметр события AFInAppEvents.REVENUE для подсчета выручки как части события внутри приложения. Этому параметру можно назначить любое числовое значение — положительное или отрицательное.

 Примечание

AFInAppEvents.REVENUE (равносильно использованию af_revenue) — это ЕДИНСТВЕННЫЙ параметр события, который учитывается в AppsFlyer как реальный доход и отображается в необработанных данных и в дашборде. Подробные сведения см. здесь.

 Пример

Событие внутри приложения, которое содержит сумму выручки
AppsFlyer.trackRichEvent(AFInAppEvents.LEVEL_ACHIEVED, new Dictionary<string, string>(){
	{AFInAppEvents.CONTENT_ID, "1234567"},
	{AFInAppEvents.CONTENT_TYPE, "category_a"},
	{AFInAppEvents.REVENUE, "1.99"},
	{AFInAppEvents.CURRENCY, "USD"}
});

 Важно!

Do NOT format the revenue value in any way. It should not contain comma separators, currency sign, or text. A revenue event should be similar to 1234.56, for example.

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

AppsFlyer предоставляет вам доступ к данным о конверсиях пользователей в реальном времени на уровне SDK. Это позволяет персонализировать целевую страницу — ту, которую видит пользователь, открывая приложение в первый раз после установки.

Для загрузки данных о конверсиях с серверов AppsFlyer выполните следующие действия:

  1. Добавьте пустой объект GameObject
  2. Прикрепите к нему файл AppsFlyerTrackerCallbacks.cs, который входит в проект (этому объекту gameobject необходимо присвоить имя AppsFlyerTrackerCallbacks).
Плагин Android для Unity > 4.15.1 Плагин Android для Unity < 4.14.3 iOS
/*Для получения данных о конверсиях в Android необходимо добавить listener в метод init()*/
AppsFlyer.init ("YOUR_DEV_KEY","AppsFlyerTrackerCallbacks");


В Android можно переместить методы из AppsFlyerTrackerCallbacks.cs в другой класс и вызвать данный класс в слушателе.

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

8. Идентификаторы пользователя

Получение AppsFlyer Device ID

Для каждой новой установки приложения AppsFlyer создает уникальный ID устройства. Для получения уникального ID из AppsFlyer используйте следующий API:

public String getAppsFlyerId();


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

string AppsFlyerUID = AppsFlyer.getAppsFlyerId();

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

Установите ID пользователя, используемый приложением. 

Чтобы задать ID пользователя, вызовите следующий метод:

AppsFlyer.setCustomerUserID("someId");

 Примечание

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

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

Установка User Email

В настоящее время в Unity это недоступно.

Google Advertising ID

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

IMEI и Android ID

Если устройство работает под управлением ОС версии выше KitKat (4.4) и использует службы Google Play, то по умолчанию SDK не проводит сбор данных IMEI и Android ID (при использовании SDK для Unity версии 4.16.4 или более ранней определенным приложениям требуется GPS). 

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

AppsFlyer.setAndroidIdData(string)
AppsFlyer.setImeiData(string)

Если службы Google Play в приложении НЕ используются, сбор данных IMEI и Android ID выполняется с помощью SDK. Однако приложения, использующие службы Google Play, не должны выполнять сбор данных IMEI, так как это противоречит политике Google Play.

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

AppsFlyer.setCollectAndroidID(bool) 
AppsFlyer.setCollectIMEI(bool)

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

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

IDFA и IDFV

Если в приложение включен файл AdSupport.framework, то AppsFlyer автоматически выполняет сбор данных IDFA (ID для рекламодателей) и IDFV (ID для продавцов).

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

Измерение деинсталляций

Для реализации измерения деинсталляций следуйте указаниям для вашей операционной системы.

Android - Firebase Android - GCM iOS
1.  Скачайте Firebase SDK для Unity по адресу: https://firebase.google.com/docs/unity/setup
2.  Импортируйте FirebaseMessaging.unitypackage в проект.
3.  Импортируйте google-services.json в проект (полученный с помощью консоли Firebase)

 Примечание

Firebase SDK для Unity должен автоматически добавить приемники, заданные в манифесте.


4.  В класс Unity, управляющий кодом AppsFlyer, добавьте следующее:
using Firebase.Messaging;
using Firebase.Unity;

5.  Добавьте в метод Start():
Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;

6.  Добавьте следующий метод:
public void OnTokenReceived
    (object sender, Firebase.Messaging.TokenReceivedEventArgs token) { 
        AppsFlyer.updateServerUninstallToken (token.Token);
}

 

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

Пользователям, которые используют Firebase SDK для Unity, не нужно добавлять следующий вызов метода в enableUninstallTracking(“SenderID”), поскольку Firebase SDK получает ID отправителя из файла google-services.json, который был добавлен ранее. Если добавить этот метод, то Android может выдать предупреждение об отладке.

Tracking Push Notifications

С помощью AppsFlyer можно выполнять измерения push-уведомлений при проведении кампании по ретаргетингу.

handlePushNotification(Dictionary<string, string> payload)

Данные должны включать в себя объект 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 Tracking

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.

Set Currency Code

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

AFInAppEvents.CURRENCY

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

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

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

public void setCurrencyCode(String currencyCode);

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

setCurrencyCode(string currencyCode)

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

Для реализации валидации чеков при покупках из приложения следуйте указаниям для вашей операционной системы.

Вызов в Android Вызов слушателя (Только в Android) Вызов в iOS
//To get the callbacks
//AppsFlyer.createValidateInAppListener ("AppsFlyerTrackerCallbacks", 
"onInAppBillingSuccess", "onInAppBillingFailure"); AppsFlyer.validateReceipt(string publicKey, string purchaseData,
string signature, string price, string currency, Dictionary additionalParametes);

Отклик на вызов при валидации покупки инициируется в классе AppsFlyerTrackerCallbacks.cs

Анонимизация пользовательских данных

В AppsFlyer предусмотрен метод анонимизации идентификаторов определенных пользователей в аналитике AppsFlyer. Этот метод соответствует последним требованиям по защите личной информации и политикам Facebook в отношении обработки данных и конфиденциальности. Значение по умолчанию  — NO (НЕТ), то есть по умолчанию анонимизация не выполняется.

Для реализации явной анонимизации установок, событий и сеансов пользователя используйте этот API во время инициализации SDK:

public void setDeviceTrackingDisabled(boolean isDisabled);

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

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

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

Исключение пользователей СУЩЕСТВЕННО влияет на информацию атрибуции.
Используйте данный параметр ТОЛЬКО для регионов, в которых законодательно запрещен сбор информации о пользователях.

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

По умолчанию 2 сеанса учитываются как отдельные, если интервал между двумя запусками приложения составляет не меньше 5 секунд (см. дополнительные сведения об учете сеансов). 
Однако если необходимо установить свое значение минимального интервала между сеансами, можно использовать этот API:
setMinTimeBetweenSessions(int seconds)


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

AppsFlyer.setMinTimeBetweenSessions(10);

Обратите внимание, что установка большого интервала между запусками может отрицательно сказаться на работе API, которые используют данные сеансов, например, для диплинкинга.

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

В настоящее время в Unity это недоступно.

Track Out-of-Store Apps

 Примечание

Магазин по умолчанию — это 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>.

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

Отказ от использования данных

В исключительных случаях может потребоваться полное отключение отслеживания средствами SDK для соблюдения норм законодательства и правил конфиденциальности. Для этого можно использовать API isStopTracking. После вызова данного API пакет SDK завершит обмен данными с серверами и перестанет функционировать.

AppsFlyer.stopTracking(true);

В любом случае SDK можно активировать повторно путем вызова того же API с передачей значения "false".

Есть несколько различных сценариев, которые владелец приложения может применить для прекращения отслеживания пользователя. Настоятельно рекомендуется строго следовать инструкциям сценария, применимого для вашего приложения.

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

Используйте данный API, только если необходимо полностью исключить данного пользователя из любого процесса отслеживания. Использование данного API СУЩЕСТВЕННО влияет на отчетность и атрибуцию.

Настройка дополнительных пользовательских данных

API setAdditionalData необходим для интеграции на уровне SDK с несколькими внешними партнерским платформами, включая Segment, Adobe и Urban Airship. Используйте данный API, только если в статье об интеграции платформы специально обозначена необходимость использования API setAdditionalData.
Ниже приведен пример кода для использования setAdditionalData в приложениях, созданных в Unity:

Dictionary<string, string> CustomDataMap = new Dictionary<string, string>();
CustomDataMap.Add("custom_param_1", "value_of_param_1");
AppsFlyer.setAdditionalData(CustomDataMap);

Attribution for Pre-Installed Apps

Android Only

You can programatically set a pre-installed media source, from Unity, using the following API:

setPreinstallAttribution(string MediaSource, string Campaign, string Site_Id);

For details on native implementations, click here.

 Важно!

При использовании комплекта разработчика ПО AppsFlyer для Unity, избегайте

PlayerPrebs.DeleteAll()

10. Тестирование результатов интеграции

Указания по тестированию для вашей операционной системы см.в статьях Тестирование в Android или Тестирование в iOS.

Now you can start tracking the media sources you work with.

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

ProGuard

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

-keep class com.appsflyer.** { *; }

IL2CPP

To exclude our SDK from the Managed bytecode stripping with IL2CPP, add the following to the link.xml:

<linker>
    <assembly fullname="mscorlib">
        <type fullname="AppsFlyer.*" preserve="all"/>
    </assembly>
…
</linker>

12. Unity Sample Project

Пример проекта на Unity см. здесь.

Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 2 из 6

Комментарии

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

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

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