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

  • Рекламодатели
  • Разработчики

ios.pngSDK Version: 4.8.10(Release notes)

1. Обзор

Это руководство содержит подробные инструкции по интеграции AppsFlyer SDK в приложение для iOS. Вы можете отслеживать установки приложения, обновления и сессии, а также другие внутренние события приложения (в том числе покупки из приложения, уровни игры и т. п.), что позволяет оценить ROI и уровень вовлеченности пользователей. SDK для iOS совместим со всеми устройствами на iOS (iPhone, iPod, iPad), на которых используется iOS версии 6 или более поздних.

 Примечание

AppsFlyer SDK полностью совместим с сетями Apple с поддержкой протоколов IPv6 и DNS64/NAT64. Подробные сведения см. здесь.

 Важно!

В AppsFlyer SDK используется класс NSUserDefaults. Не удаляйте из NSUserDefaults все значения — это может привести к проблемам при атрибуции.

 Совет

  • Для интеграции БАЗОВОГО SDK, то есть для использования только функции атрибуции установок, НЕОБХОДИМО выполнить действия, описанные в пунктах 2 и 3.
  • Выполнение действий, описанных в пункте "Отслеживание внутренних событий приложения", НАСТОЯТЕЛЬНО РЕКОМЕНДУЕТСЯ.
  • 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 SDK и добавьте его в Xcode.

CocoaPods Carthage Static Framework Static Lib
  • Обязательно загрузите и установите последнюю версию CocoaPods.
  • Добавьте следующую строку в свой профиль:
    pod 'AppsFlyerFramework'
  • Запустите pod install
  • Всегда используйте для открытия своего проекта в Xcode только файл .xcworkspace, вместо .xcodeproj.

AppsFlyer SDK использует следующие структуры из основного набора:

AdSupport.framework
Данная структура требуется для сбора IDFA на устройствах.
Без IDFA отслеживание рекламы в Facebook, Twitter, Google и других сетях недоступно.
iAd.framework
Эта структура предназначена для отслеживания в приложении кампаний Apple Search Ads.

2.2 Настройка интеграции в App Delegate

Откройте файл AppDelegate.m своего приложения и выполните импорт SDKAppsFlyer:

Swift Objective-C
import AppsFlyerLib

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

Инициализируйте SDK в методе didFinishLaunchingWithOptions, используя ID приложения, полученный из iTunes Connect, и свой ключ разработчика AppsFlyer

Примите во внимание, что при задании ID приложений здесь нужно использовать только цифры без префикса "id".

Swift Objective-C
AppsFlyerTracker.shared().appsFlyerDevKey = "<your-appsflyer-dev-key>";
AppsFlyerTracker.shared().appleAppID = "123456789"
AppsFlyerTracker.shared().delegate = self
#ifdef DEBUG
AppsFlyerTracker.shared().isDebug = true
#endif

 Примечание

Если задано правило isDebug=true, то AppsFlyer SDK будут отображаться на консоли xCode Console.

 

  • Добавьте в функцию applicationDidBecomeActive такой код:
Swift Objective-C
func applicationDidBecomeActive(application: UIApplication) { 
// Track Installs, updates & sessions(app opens) (You must include this API to enable tracking) 
AppsFlyerTracker.shared().trackAppLaunch() 
// your other code here.... }

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

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

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

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

Example: Purchase In-App Event

Swift Objective-C
AppsFlyerTracker.shared().trackEvent(AFEventPurchase,
    withValues: [
         AFEventParamRevenue: "1200",
         AFEventParamContent: "shoes",
         AFEventParamContentId: "123"
]);

This generates an af_purchase event type (using the AFEventPurchase constant) with the following event values: {af_revenue: 200 , af_currency: "USD", af_quantity: 2, af_content_id: "092" af_receipt_id: "9277"} 

 Примечание

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

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

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

Swift Objective C
AppsFlyerTracker.shared().trackEvent(AFEventPurchase,
withValues: [
    AFEventParamRevenue: @1200,
    AFEventParamCurrency : @"JPY"
]); 

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

 Совет

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

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


To handle deep linking, add the following code in your app (in the app delegate class). The methods in this code allow you to get deep linking data. With deep linking data you can redirect users to the relevant app activity and serve them with the relevant content.

Swift Objective-C

 func onConversionDataReceived(_ installData: [AnyHashable: Any]) {
    //Handle Conversion Data (Deferred Deep Link)
    }
    
    func onConversionDataRequestFailure(_ error: Error?) {
        //        print("\(error)")
    }
    
    func onAppOpenAttribution(_ attributionData: [AnyHashable: Any]) {
        //Handle Deep Link Data
        
    }
    
    func onAppOpenAttributionFailure(_ error: Error?) {
    }
// Reports app open from a Universal Link for iOS 9 or later
    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
        AppsFlyerTracker.shared().continue(userActivity, restorationHandler: restorationHandler)
        return true
    }

    // Reports app open from deep link from apps which do not support Universal Links (Twitter) and for iOS8 and below
    func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
        AppsFlyerTracker.shared().handleOpen(url, sourceApplication: sourceApplication, withAnnotation: annotation)
        return true
    }

    // Reports app open from deep link for iOS 10 or later
    func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
        AppsFlyerTracker.shared().handleOpen(url, options: options)
        return true
    }
   

 Важно!

For Swift 4.2 and above, use the following code for the continue userActivity method:

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
	AppsFlyerTracker.shared().continue(userActivity, restorationHandler: nil)
	return true
}

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

Для подсчета дохода в составе внутреннего события приложения используйте параметр события af_revenue (AFEventParamRevenue). Этому параметру можно присвоить любое числовое значение — положительное или отрицательное.

 Примечание

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


Пример: событие внутри приложения, приносящее доход

Swift Objective-C
AppsFlyerTracker.shared().trackEvent(AFEventPurchase, 
withValues: [
	AFEventParamContentId:"1234567",
	AFEventParamContentType : "category_a",
	AFEventParamRevenue: 1.99,
	AFEventParamCurrency:"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.

Tracking Negative Revenue

If you need to track negative revenue for example when a user cancels a purchase or receives a refund, you can send negative revenue.

Swift Objective-C
AppsFlyerTracker.shared().trackEvent("cancel_purchase", 
withValues: [
	AFEventParamContentId:"1234567",
	AFEventParamContentType : "category_a",
	AFEventParamRevenue: -1.99,
	AFEventParamCurrency:"USD"
]);

 Примечание

Notice the following in the code above:

  1. The revenue value is preceded by a minus sign
  2. The event name has a unique value of "cancel_purchase" - to allow you to identify negative revenue events in the dashboard and raw data reports

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

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

Подробные сведения об этих дополнительных функциях см.здесь.

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

Существует несколько способов получения идентификаторов пользователей:

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

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

Swift Objective-C
let appsflyerId = AppsFlyerTracker.shared().getAppsFlyerUID()

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

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

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

Swift Objective-C
AppsFlyerTracker.shared().customerUserID = "my user id"

 Важно

It is recommended to set your Customer User ID as soon as possible as it is only associated to events reported after its setup. If setCustomerUserId is called before calling trackAppLaunch, the Customer User ID is visible in the raw export for installs and for events. If it is set after, only the value for events tracked is visible after calling this method.

Идентификатор пользователя-клиента можно также использовать для интеграции с аналитическими платформами, например Mixpanel и Swrve.

Получение Customer User ID:

To get the customer user ID retrieve it from the sharedTracker.

[AppsFlyerTracker sharedTracker].customerUserID

 Важно!

Make sure to set the customer user ID each time the app is launched, before calling trackAppLaunch</code.

Для получения дополнительных сведений о Customer User ID щелкните здесь.

Установка User Email

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

Пример: сбор пользовательских адресов электронной почты

Swift Objective-C
AppsFlyerTracker.shared().setUserEmails( ["email1@domain.com", "email2@domain.com"], with: EmailCryptTypeSHA1)

 Примечание

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

IDFA и IDFV

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

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

Measure Uninstalls

For Uninstall measurement, enable remote push notification on your app. See Apple's Remote Notification Programming Guide for more details.

Follow the iOS SDK integration instructions to complete the uninstall measurement feature setup.

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

Чтобы включить отслеживание запуска приложений из push-уведомлений, добавьте в делегат своего приложение такой код:

Swift Objective-C
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
	AppsFlyerTracker.shared().handlePushNotification(userInfo)
}

Рush-уведомление должно содержать параметр af с параметрами отслеживания AppsFlyer.

Пример сообщения:

{
   "aps":{
      "alert":"Push text",
      "sound":"default",
      "category":"REMINDER_CATEGORY"
   },
   "_p":123456,
   "payloadKey":"payloadValue",
   "af":{
      "pid":"swrve_int",
      "is_retargeting":"true",
      "c":"test_campaign"
   }
}

Отслеживание cross-promo рекламы

AppsFlyer позволяет отслеживать и атрибутировать установки, источником которых является cross-promo реклама одного из ваших приложений в другом приложении, которое уже есть у пользователя.  Сross-promo может заметно увеличить количество установок ваших приложений.

Подробные сведения см. в статье об Отслеживании кампаний перекрестной рекламы.

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

AppsFlyer позволяет отслеживать и атрибутировать установки, источником которых являются приглашения пользователя из вашего приложения. С их помощью уже имеющиеся пользователи могут приглашать своих друзей и знакомых в качестве новых пользователей вашего приложения, что может стать ключевым фактором продвижения. 
 
Подробные сведения см. в статье Отслеживание приглашений пользователя.

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

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

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

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

public void currencyCode(String currencyCode);

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

Swift Objective-C
AppsFlyerTracker.shared().currencyCode = "USD"

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

 Примечание

Эта функция поддерживается для iOS7 и более новых версий.

При покупках из приложения SDK AppsFlyer может выполнять проверку сервера. Чтобы запустить валидации чеков, вызовите метод validateAndTrackInAppPurchase из метода completeTransaction с параметром callback, который содержится в структуре SKStoreKit. Этот вызов автоматически создает событие внутри приложения af_purchase.

- (void) validateAndTrackInAppPurchase:(NSString *) productIdentifier
price:(NSString *) price
currency:(NSString *) currency
transactionId:(NSString *) tranactionId
additionalParameters:(NSDictionary *) params
success:(void (^)(NSDictionary *response)) successBlock
failure:(void (^)(NSError *error, id reponse)) failedBlock;

 Примечание

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


Этот вызов содержит два блока обратного вызова — один для варианта «успешно», а второй для варианта «ошибочно» (по любой причине, включая сбой проверки). В случае варианта «успешно» словарь получит в ответ подтверждение контрольных данных, предоставляемых серверами Apple.  

 Важно

Для тестирования рекомендуется установить значение YES для флага useReceiptValidationSandbox , чтобы перенаправлять запросы на изолированные серверы Apple.

#ifdef DEBUG
    [AppsFlyerTracker sharedTracker].useReceiptValidationSandbox = YES;
#endif

 

 Пример

Objective-C Swift
[[AppsFlyerTracker sharedTracker] validateAndTrackInAppPurchase:product.productIdentifier price:product.price.stringValue
currency:@"USD"
transactionId:trans.transactionIdentifier
additionalParameters:@{@"test": @"val" , @"test1" : @"val 1"}
success:^(NSDictionary *result){
  NSLog(@"Purchase succeeded And verified!!! response: %@", result[@"receipt"]);
} failure:^(NSError *error, id response) {
  NSLog(@"response = %@", response);
}];

Список возможных возвращаемых значений при валидации чеков см. в документации Apple по этой ссылке.

Анонимизация

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

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

Swift Objective-C
AppsFlyerTracker.shared().deviceTrackingDisabled = true

Чтобы снова запустить отслеживание, еще раз вызовите метод deviceTrackingDisabled со значением "false" (ложь).

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

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

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

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

Swift Objective-C
AppsFlyerTracker.shared().minTimeBetweenSessions = <ваш_временной_интервал_в_секундах>

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

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

Недоступно в iOS. 
 

Расширения приложений в iOS и WatchKit

Расширение приложения требует разрешения на доступ к интернету:

  1. Откройте файл info.plist для своего приложения, которое содержит расширение.
  2. В группе NSExtension / NSExtensionAttributes установите для флага RequestsOpenAccess значение YES.

Добавьте в подкласс UIViewController расширения приложения приведенный ниже код для метода viewDidLoad:

Swift Objective-C
override func viewDidLoad() {    
        super.viewDidLoad()
        AppsFlyerTracker.shared().appsFlyerDevKey = "MY_APPSFLYER_KEY"

        // MY_APP_ID below stands for you app ID on iTunes Connect. Should be 9 or 10 digits.
        AppsFlyerTracker.shared().appleAppID = "MY_APP_ID"
                
        AppsFlyerTracker.sharedTracker().trackAppLaunch()
    }

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

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

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 no longer communicates with our servers and stops functioning.

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

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

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 attribution, data collection and deep linking mechanism.

Swift Objective-C
AppsFlyerTracker.shared().isStopTracking = true

 Важно

Не вызывайте trackAppLaunch, если параметр isStopTracking установлен на значение "true"

Сбор информации об имени устройства

SDK AppsFlyer позволяет собирать информацию об имени устройства для внутреннего анализа. По умолчанию данная функция отключена. Чтобы включить ее, используйте следующий API:

Swift Objective-C
>AppsFlyerTracker.shared().shouldCollectDeviceName = false`

 Важно

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

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

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

Objective-C Swift
NSDictionary* CustomDataMap = [[NSDictionary alloc] initWithObjectsAndKeys:@"value_of_param_1", @"custom_param_1", nil];
    
[[AppsFlyerTracker sharedTracker] setAdditionalData:CustomDataMap];

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

Подробное описание процедуры тестирования см. здесь.

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

11. Отправка приложения в App Store

Инструкции по отправке приложения в App Store см. здесь.

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

Комментарии

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

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