Руководство по интеграции SDK iOS для маркетологов

Фон

Начиная с iOS 14.5, для сбора IDFA нужно согласие пользователя. Фактически это означает, что доступом к IDFA управляет фреймворк App Tracking Transparency (ATT). На устройствах с iOS 14 и выше для получения доступа к IDFA устройства SDK использует фреймворк ATT. 

Базовую информацию об ATT см. в разделе Принципы ATT.

Если атрибуция выполняется с использованием IDFA, важно, чтобы IDFA отправлялся при первом запуске. Для этого в SDK предусмотрена утилита waitForATTUserAuthorization.

Обзор waitForATTUserAuthorization

waitForATTUserAuthorization позволяет настроить, на сколько SDK будет задерживать отправку данных на серверы AppsFlyer, ожидая получения статуса ATT.

Когда пользователь запускает приложение, ATT имеет статус notDetermined (Не определен). В течение времени ожидания waitForATTUserAuthorization:

• SDK помещает в очередь в памяти событие запуска и последующие внутренние события приложения, аналогично тому, как регистрируются оффлайн-события.
• Если пользователь принимает запрос на ATT (сбор IDFA):
  • SDK добавляет IDFA к кэшированным событиям.
  • SDK запускается и отправляет кэшированные события с IDFA (не дожидаясь окончания времени ожидания).
• Если пользователь отклоняет запрос на ATT:
  • SDK запускается и отправляет кэшированные события без IDFA (не дожидаясь окончания времени ожидания).
• Если время ожидания истекло, и статус разрешения на ATT остается notDetermined (Не определен):
  • SDK запускается и отправляет кэшированные события без IDFA.

Факторы, которые необходимо учитывать

• Вызов requestTrackingAuthorization без настройки waitForATTUserAuthorization приведет к тому, что данные о запусках и событиях на устройствах iOS 14+ будут отправляться без IDFA.
• Если в течение времени ожидания пользователь переводит приложение в фоновый режим:
  • Таймер приостанавливается, пока пользователь не вернется к окну приложения.
  • События кэшируются в памяти.
• Если в течение времени ожидания пользователь прекращает работу приложения или закрывает его:
  • Таймер перезапускается при следующем запуске приложения.
  • Кэшированные события будут потеряны.

Запрос на ATT можно настроить. Сообщение, в котором четко указана цель запроса, может увеличить процент согласий.

При создании сообщения обратите внимание на следующее:

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

Закончив работу над сообщением, предоставьте разработчику текст и эти инструкции.

Чтобы просмотреть внешние примеры запросов на ATT, щелкните здесь.

SKAN — это класс, используемый iOS для проверки установок приложений, стимулируемых рекламодателем. Для проверки установки нужны исходное приложение и рекламируемое приложение. 

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

Для рекламируемого приложения (приложение с SDK AppsFlyer) решение AppsFlyer SKAN использует SKAN, чтобы отправлять постбэки об атрибуции. При этом AppsFlyer собирает, расшифровывает и агрегирует данные, обеспечивая конфиденциальность пользователей. При первом запуске приложения платформа AppsFlyer сообщает SDK, как задать значение конверсии SKAN, используя настройки, определенные маркетологом.

Чтобы использовать решение SKAN:

• Маркетолог настраивает измерение SKAN в AppsFlyer. От разработчика действий не требуется.
• SDK AppsFlyer автоматически вызывает необходимые API SKAN.
• Если для атрибуции SKAN вы используете AppsFlyer, обязательно отключите вызовы SKAN в других SDK.
• В магазине приложений не требуется каких-либо действий или регистраций со стороны разработчика или маркетолога. 

Чтобы отключить атрибуцию SKAN, попросите разработчика отключить ее в SDK. 

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

Инструкции для разработчиков см. в разделе Регистрация доходов.

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

Если приложение относится к определенной категории, такой как путешествия, игры, электронная коммерция, см. список рекомендованных событий для каждой категории.

Если у пользователей не установлено ваше приложение, OneLink определяет тип устройства и перенаправляет их в нужное место назначения: в Google Play, Apple App Store, сторонний магазин приложений или на веб-страницу. Это зависит от ваших настроек шаблона OneLink. Узнать больше

Примечание: для идентификации устройств и перенаправления SDK AppsFlyer не требуется. Однако SDK нужен для диплинкинга.

Если у пользователей установлено ваше приложение, OneLink открывает приложение. Помимо открытия приложения, вы также можете перенаправлять пользователей по диплинкам на определенное действие или страницу в приложении. Для этого вашему разработчику нужно реализовать унифицированный диплинкинг (UDL).

Внимание:

• Для UDL нужен SDK версии 6.1+.
• Вместо UDL клиенты, уже применяющие OneLink для диплинкинга, могут использовать устаревшие методы.

См. наше руководство по настройке диплинкинга при помощи OneLink.

Если у пользователей не установлено ваше приложение, OneLink определяет тип устройства и перенаправляет их в нужное место назначения: в Google Play, Apple App Store, сторонний магазин приложений или на веб-страницу. Когда пользователь загрузит приложение, вы можете направить его на определенную активность или страницу приложения с помощью отложенного диплинкинга.

Для этого вашему разработчику нужно реализовать унифицированный диплинкинг (UDL).

Внимание:

• Для UDL нужен SDK версии 6.1+.
• Вместо UDL клиенты, уже применяющие OneLink для отложенного диплинкинга, могут использовать устаревшие методы.

Дополнительные сведения см. в руководстве по отложенному диплинкингу.

AppsFlyer поддерживает измерение кампаний с push-уведомлениями всех поставщиков, а также поддерживает разработчиков, напрямую использующих Google Cloud Messaging или службу push-уведомлений Apple. Конверсии, определенные как открытие приложения из push-уведомления, отображаются на дэшборде ретаргетинга.

С помощью OneLink вы можете измерять повторное вовлечение пользователей через push-уведомления. См. руководство по измерению эффективности кампаний по повторному вовлечению пользователей при помощи push-уведомлений.

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

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

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

[[AppsFlyerLib shared] startWithCompletionHandler:^(NSDictionary<NSString *,id> *dictionary, NSError *error) {
        if (error) {
            NSLog(@"%@", error);
            return;
        }
        if (dictionary) {
            NSLog(@"%@", dictionary);
            return;
        }
    }];

 AppsFlyerLib.shared()?.start(completionHandler: { (dictionnary, error) in
            if (error != nil){
                print(error ?? "")
                return
            } else {
                print(dictionnary ?? "")
                return
            }
        })

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

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

Пример кода setAdditionalData:

NSDictionary* customDataMap = [[NSDictionary alloc] initWithObjectsAndKeys:@"value_of_param_1", @"custom_param_1", nil];
[[AppsFlyerLib shared] setAdditionalData:customDataMap];

let customDataMap: [AnyHashable: Any] = [
  "custom_param_1" : "value_of_param_1"
]
AppsFlyerLib.shared().customData = customDataMap

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

Например, пользователь ищет что-то в Google и кликает по ссылке на ваш домен www.example.com:

• Если у пользователя не установлено приложение, он направляется на веб-сайт (www.example.com).
• Если приложение уже установлено на устройстве этого пользователя, диплинк приведет его в приложение, связанное с доменом www.example.com. Данная сессия атрибутируется медиа-источнику (параметр pid), указанному в appendParametersToDeepLinkingURL.

Дополнительную информацию см. в материалах по iOS SDK.

Заметьте: Смарт-баннеры помогают конвертировать посетителей сайта в пользователей мобильного приложения.

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

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

[AppsFlyerLib shared].minTimeBetweenSessions = <your_custom_time_in_seconds>;

AppsFlyerLib.shared().minTimeBetweenSessions = <your_custom_time_in_seconds>

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

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

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

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

Например, у вас есть три домена регистрации кликов, которые выполняют перенаправление на вашу ссылку OneLink по адресу https://mysubdomain.onelink.me/abCD. Используйте этот API для получения ссылки OneLink, на которую перенаправляют домены регистрации кликов.  Этот метод API получает список доменов, разрешение которых выполняет SDK.

[AppsFlyerLib shared].resolveDeepLinkURLs = @[@"example.com",@"click.example.com"];

AppsFlyerLib.shared().resolveDeepLinkURLs = ["example.com", "click.example.com"]

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

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

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

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

Внимание! Для перекрестной рекламы по IDFV требуется SDK 6.0.2 или новее. Идентификаторы IDFV собираются автоматически, от разработчика не требуется дополнительных действий.

Для каждой новой установки приложения AppsFlyer создает уникальный ID. Вы можете использовать этот ID для различных целей:

• Отправляйте внутренние события приложения от сервера к серверу.
• Сопоставьте его с данными пользователей в ваших back-end системах.
• Сопоставляйте записи при объединении данных из Pull API и Push API.

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

NSString *appsflyerId = [AppsFlyerLib shared].getAppsFlyerUID;

let appsflyerId = AppsFlyerLib.shared().getAppsFlyerUID()

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

[AppsFlyerLib shared].customerUserID = @"my user id";

AppsFlyerLib.shared().customerUserID = "my user id"

В iOS идентификатор пользователя необходимо устанавливать с каждым запуском приложения. Рекомендуется установить свой ID клиента на раннем этапе продвижения приложения, так как после установки этого идентификатора только он привязывается к событиям, включаемым в отчеты:

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

Чтобы избежать необходимости повторно устанавливать значение ID клиента после первого запуска и многократно обращаться к серверу для его получения, проверьте, задано ли его значение, с помощью этого кода:

NSString *customerUserID = [AppsFlyerLib shared].customerUserID;

let customerUserID = AppsFlyerLib.shared().customerUserID

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

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

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

- (void)applicationDidBecomeActive:(UIApplication *)application {
    NSString *customUserId = [[NSUserDefaults standardUserDefaults] stringForKey:@"customerUserId"]; // Your custom logic of retrieving CUID
    if (customUserId != nil && ![customUserId  isEqual: @""]) {
        [AppsFlyerLib shared].customerUserID = customUserId; // Set CUID in AppsFlyer SDK for this session
        [[AppsFlyerLib shared] start]; // Start
    }
}

func applicationDidBecomeActive(_ application: UIApplication) {
        let customUserId = UserDefaults.standard.string(forKey: "customUserId")  //  your logic to retrieve CUID
        if(customUserId != nil && customUserId != ""){
            AppsFlyerLib.shared().customerUserID = customUserId // Set CUID in AppsFlyer SDK for this session
            AppsFlyerLib.shared().start() // Start
        }
    }

Дополнительные сведения об отсрочке инициализации SDK до получения идентификатора клиента см. здесь.

Можно отложить инициализацию SDK и отправку данных, пока пользователь не даст согласие (например, согласие в соответствии с GDPR или COPPA).

Примечание: Это не связано с ATT, представленным в iOS 14. 

Чтобы отложить инициализацию SDK:

1. Запретите отправку сеанса при переходе из фонового режима в активный. В методе sendLaunch() (который вызывается при каждом applicationDidBecomeActive (как описано в разделе 3.3), оберните вызов start с проверкой состояния. Например:
   
   

   -(void)sendLaunch:(UIApplication *)application {
       if (consent_given) { // check the condition
           [[AppsFlyerLib shared] start]; // Start
       }
   }

2. Отправьте сессию, как только исчезнет причина задержки (сразу после изменения состояния). Вызовите start, когда будете готовы отправить данные первой сессии. Например:
   
   

   ...
   consent_given = YES; // change the condition
   [[AppsFlyerLib shared] start]; // Start
   ...

В исключительных случаях может потребоваться полное отключение средств SDK для соблюдения норм законодательства и правил конфиденциальности. Это может быть реализовано с помощью параметра isStopped. Когда для параметра установлено значение true, SDK прекратит работу и обмен данных с серверами AppsFlyer.

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

[AppsFlyerLib shared].isStopped = true;

AppsFlyerLib.shared().isStopped = true

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

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

[AppsFlyer shared].anonymizeUser = YES;

AppsFlyerLib.shared().anonymizeUser = true

Предоставление данных можно запустить снова, установив anonymizeUser на значение false.

Используйте строгий режим в SDK, чтобы полностью удалить функции сбора IDFA и зависимости инфраструктуры AdSupport (например, при разработке приложений для детей).

Примечание. Данные IDFV остаются доступны.

В вашем Podfile замените зависимость AppsFlyerLib на:

pod 'AppsFlyerFramework/Strict','6.2.3'

Для отключения фреймворков AdSupport и iAd в SDK предусмотрены следующие схемы настройки:

• disableCollectASA = true. Узнать больше
• disableAdvertisingIdentifier = true. Узнать больше

Чтобы отключить фреймворки для рекламы:

[AppsFlyerLib shared].disableCollectASA = YES
[AppsFlyerLib shared].disableAdvertisingIdentifier = YES;

AppsFlyerLib.shared().disableCollectASA = true
AppsFlyerLib.shared().disableAdvertisingIdentifier = true

В некоторых случаях рекламодатели должны прекратить передачу рекламным сетям / партнерам данных по определенным пользователям. Причины могут быть следующие: 

• Политики конфиденциальности, такие как CCPA или GDPR.
• Отказ пользователей от предоставления данных
• Конкуренция с некоторыми партнерами (рекламными сетями, третьими сторонами)

Обмен данными с партнерами контролируется с помощью метода setSharingFilterForPartners.