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

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

ios.pngВерсия SDK: 4.10.0 (Примечания о выпуске)

1. Обзор

This guide details how to integrate AppsFlyer's SDK into your iOS app. You can record installs, updates, sessions, and additional in-app events as well as app installs (including in-app purchases, game levels, etc.) to evaluate ROI and user engagement levels. The iOS SDK is compatible with all iOS devices (iPhone, iPod, iPad) with iOS version 6 and later.

 Примечание

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

 Важно!

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

 Совет

  • In order to implement basic SDK integration that is, install attribution only, it is mandatory to complete the procedures in sections 2 and 3 in this document. 
  • It is recommended that you read the Recording in-app events section as an aid to implementation
  • The rest of the described features described, are optional and implementing them will depend on your app's business logic. For example, recording revenue or getting the conversion data on first launch may be vital for your app's flow

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

2.1 Загрузите AppsFlyer SDK и добавьте его в Xcode.

CocoaPodsCarthageStatic FrameworkStatic Lib
  1. Обязательно загрузите и установите последнюю версию CocoaPods.
  2. Добавьте следующую строку в свой Podfile:
    pod 'AppsFlyerFramework'
  3. Запустите pod install
  4. Всегда используйте для открытия своего проекта в Xcode только файл .xcworkspace, вместо .xcodeproj.

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

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

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

SwiftObjective-C

В файле AppDelegate.swift выполните следующие действия:

  1. import AppsFlyerLib
  2. Добавьте AppsFlyerTrackerDelegate в объявление класса
import AppsFlyerLib
class AppDelegate: UIResponder, UIApplicationDelegate, AppsFlyerTrackerDelegate {
   // your code here
}

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

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

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

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

 Примечание

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

 

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

Проверка выполнения запроса Track App Launch (Отслеживание запуска приложения)

Чтобы проверить, выполнен ли запрос на отслеживание запуска приложения, можно использовать метод trackAppLaunchWithCompletionHandler. Затем результат применения этого метода (запрос выполнен/не выполнен) можно обработать с помощью логических операторов.

Пример

[[AppsFlyerTracker sharedTracker] trackAppLaunchWithCompletionHandler:^(NSDictionary<NSString *,id> *dictionary, NSError *error) {
        if (error) {
            NSLog(@"%@", error);
            return;
        }
        if (dictionary) {
            NSLog(@"%@", dictionary);
            return;
        }
        [NSException exceptionWithName:@"fatalError" reason:nil userInfo:nil];
    }];

4. Регистрация внутренних событий приложения

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

Для регистрации внутренних событий приложения используется вызов функции trackRichEvent с именем события и значениями параметров. Подробные сведения см. в статье о внутренних событиях приложения".

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

Пример: событие покупки в приложении

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

swift-record-in-app-events.png

В этом примере создается событие типа af_purchase (с использованием константы AFEventPurchase) со следующими значениями: {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.

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

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

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

Проверка регистрации внутренних событий приложения

Чтобы проверить, выполнена ли регистрация внутренних событий приложения, можно использовать метод completionHandler. Затем результат применения этого метода (регистрация выполнена/не выполнена) можно обработать с помощью логических операторов.

Пример

[[AppsFlyerTracker sharedTracker] trackEventWithEventName:AFEventPurchase
	eventValues:@{AFEventParamRevenue: @"1200",
					AFEventParamContent: @"shoes",
					AFEventParamContentId: @"123"}
	completionHandler:^(NSDictionary<NSString *,id> *dictionary, NSError *error) {
	if (error) {
		NSLog(@"%@", error);
		return;
	}
	if (dictionary) {
		NSLog(@"%@", dictionary);
		return;
	}
	[NSException exceptionWithName:@"fatalError" reason:nil userInfo:nil];

5. Настройка диплинкинга

 Совет

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

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

Для работы с диплинками, добавьте в свое приложение следующий код (в класс app delegate). С помощью методов, заданных в этом коде, можно получить данные диплинков. Используя данные диплинков, можно перенаправлять пользователей на определенные действия в приложении и предоставлять им соответствующий контент.

SwiftObjective-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
  }
  

 Важно!

В Swift 4.2 и более новых версиях используйте для метода continue userActivity следующий код:

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) — это ЕДИНСТВЕННЫЙ event параметр, который учитывается в AppsFlyer, как реальная прибыль в Raw data и в Dashboard. Подробные сведения см. здесь.


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

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

 Важно!

Для значений дохода НЕЛЬЗЯ применять какое бы то ни было форматирование. В них не должны использоваться запятые-разделители, знаки валюты или текст. Событие дохода должно иметь, например, такой формат: 1234.56.

Регистрация отрицательного дохода

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

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

 Примечание

Обратите внимание на приведенный выше код:

  1. Перед значением дохода стоит знак минус
  2. Имя события имеет уникальное значение "cancel_purchase", которое позволяет легко найти события отрицательного дохода на панели управления и в отчетах сырых данных.

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

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

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

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

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

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

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

SwiftObjective-C
let appsflyerId = AppsFlyerTracker.shared().getAppsFlyerUID()

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

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

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

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

 Важно

Рекомендуется установить свой идентификатор Customer User ID как можно раньше, так как после его установки только он привязывается к событиям, включаемым в отчеты. Если вызов setCustomerUserId выполняется перед вызовом trackAppLaunch, при экспорте необработанных данных идентификатор Customer User ID будет отображаться и для установок, и для событий. Если же этот идентификатор установить позже, то он будет отображаться только для событий, зарегистрированных после вызова этого метода.

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

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

Идентификатор пользователя-клиента можно получить из объекта sharedTracker.

[AppsFlyerTracker sharedTracker].customerUserID

 Важно!

Идентификатор клиента нужно задавать при каждом запуске приложения перед вызовом trackAppLaunch.

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

IDFA и IDFV

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

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

Измерение количества удалений приложений

Для измерения количества удалений нужно включить в приложении push-уведомления. Подробные сведения см. в документе Apple Руководство по программированию удаленных уведомлений.

См. указания по настройке отслеживания удалений в инструкции по интеграции SDK для iOS .

Регистрация push-уведомлений

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

SwiftObjective-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"
  }
}

Атрибуция в кампаниях перекрестной рекламы

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

Подробные сведения см. в статье Атрибуция в кампаниях перекрестной рекламы.

Атрибуция приглашений пользователей

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

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

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

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

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

public void currencyCode(String currencyCode);

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

SwiftObjective-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-CSwift
[[AppsFlyerTracker sharedTracker] validateAndTrackInAppPurchase:@"ProductIdentifier" price:@"price"
    currency:@"USD"
    transactionId:@"transactionID"
    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);
      if([response isKindOfClass:[NSDictionary class]]) {
        if([response[@"status"] isEqualToString:@"in_app_arr_empty"]){
          // retry with 'SKReceiptRefreshRequest' because
          // Apple has returned an empty response
          // <YOUR CODE HERE>
        }

      } else {
        //handle other errors
        return;
      }
  }];

 Важно!

Когда AppsFlyer, проверяя покупку на серверах Apple, получает ответ с пустым полем in-app, то AppsFlyer отправляет обратный вызов с статусом ошибки {"status":"in_app_arr_empty"}.

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

После обновления чека снова выполните вызов validateAndTrackInAppPurchase.

Способ обработки такой ошибки показан в приведенном выше коде.

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

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

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

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

SwiftObjective-C
AppsFlyerTracker.shared().deviceTrackingDisabled = true

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

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

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

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

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

Однако, если необходимо установить свой вариант минимального интервала между сессиями, можно использовать этот API:

SwiftObjective-C
AppsFlyerTracker.shared().minTimeBetweenSessions = <ваш_временной_интервал_в_секундах>
Обратите внимание, что установка большого интервала между запусками может отрицательно сказаться на работе API, которые используют данные сессий, например, для диплинкинга.

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

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

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

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

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

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

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

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

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

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

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

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

SwiftObjective-C
AppsFlyerTracker.shared().isStopTracking = true

 Важно

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

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

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

SwiftObjective-C
AppsFlyerTracker.shared().shouldCollectDeviceName = false

 Важно

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

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

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

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

Разрешение упакованных URL-адресов глубинных ссылок

Если используются ссылки OneLink, которые поддерживают ссылки для приложений Android, и при этом упаковываются в сторонние универсальные ссылки, то для уведомления SDK AppsFlyer о том, какие домены CLICK, вызывающие приложение, нужно разрешить и использовать для извлечения базовой ссылки OneLink, можно применять API setResolveDeepLinkURLs. Это позволит поддерживать диплинкинг и атрибуцию при упаковке ссылки OneLink в стороннюю универсальную ссылку. Этот API нужно обязательно вызвать перед инициализацией SDK.

Objective-CSwift
[AppsFlyerTracker sharedTracker].resolveDeepLinkURLs = @[@"example.com",@"click.example.com"];

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

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

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

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

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

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

Комментарии

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

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

Содержание страницы: