Интеграция с Meta Ads

Требуется помощь разработчика

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

Интеграция с Meta Ads позволяет синхронизировать аудитории Pushwoosh с вашими рекламными аккаунтами Meta. Используйте ее для таргетинга или исключения пользователей в рекламных кампаниях и добавления платной рекламы как еще одного канала в вашем пути клиента.

Сценарии использования

Используйте эту интеграцию, чтобы:

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

Предварительные требования

Прежде чем подключить Meta Ads, убедитесь, что:

• У вас есть роль Admin в вашем аккаунте Pushwoosh. О том, как работают роли и разрешения, см. в разделе Управление доступом и разрешениями пользователей.
• У вас настроен Facebook Business Manager для управления ресурсами вашего бренда в Facebook, включая рекламные аккаунты, страницы и приложения.
• У вас есть активный рекламный аккаунт Facebook, привязанный к вашему Business Manager.
• Администратор вашего Facebook Business Manager предоставил вам разрешения Manage Campaigns или Manage ad accounts для рекламных аккаунтов, которые вы планируете использовать с Pushwoosh.
• Вы приняли условия и положения для этих рекламных аккаунтов.
• Вы приняли Условия использования Custom Audiences от Facebook для рекламных аккаунтов Facebook, которые вы планируете использовать с Pushwoosh.

Настройка Meta Ads в Pushwoosh

1. В Pushwoosh перейдите в Настройки > Сторонние интеграции.

2. На карточке Meta Ads нажмите Страница входа.

3. Войдите в свой аккаунт Meta, затем нажмите Продолжить.

4. Выберите рекламные аккаунты, которые хотите подключить.

5. Проверьте запрашиваемые разрешения для рекламного аккаунта и бизнес-доступа.

6. Нажмите Сохранить. Затем Meta покажет подтверждение, что ваш аккаунт подключен.

Проверка статуса подключения

После настройки вы будете перенаправлены на страницу Meta Ads в Pushwoosh.

В таблице рекламных аккаунтов перечислены все подключенные аккаунты с указанием:

• Название рекламного аккаунта
• Бизнес-аккаунт
• ID

Откройте меню (три точки) в конце строки и выберите Удалить рекламный аккаунт, чтобы удалить этот рекламный аккаунт из списка в Pushwoosh.

Управление подключенными рекламными аккаунтами

На странице Meta Ads нажмите Управление аккаунтами, чтобы открыть диалоговое окно. Используйте переключатель в каждой строке, чтобы включить или исключить этот рекламный аккаунт из интеграции. Нажмите Применить, чтобы сохранить изменения, или Отмена, чтобы закрыть без сохранения.

Чтобы настроить вид списка:

• Включите или выключите Показывать только подключенные, чтобы ограничить отображаемые строки.
• Введите текст в поле Поиск по названию или ID…, чтобы найти аккаунты в списке.

Сопоставление тегов проекта с полями Meta

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

Примечание

Для синхронизации аудитории Pushwoosh всегда отправляет один идентификатор на пользователя из полей Email, Phone number или MADID, в зависимости от того, что есть в профиле. Настройте сопоставление, если вы хотите, чтобы Meta получала дополнительные атрибуты пользователя помимо вышеуказанных идентификаторов.

1. На странице Meta Ads нажмите Сопоставить данные пользователя.

2. Для каждого Поля Facebook в левом столбце выберите Название тега в вашем проекте из элемента управления справа. Сопоставляйте только те строки, которые вам нужны.

Автоматически сопоставляемые поля

Pushwoosh сопоставляет эти поля автоматически. Вам не нужно настраивать их в разделе Сопоставление тегов проекта с полями Meta:

• Email
• Phone number
• MADID

3. Нажмите Сохранить, чтобы применить сопоставление, или Отмена, чтобы закрыть без сохранения.

Включение сбора MADID в SDK

Meta Ads сопоставляет пользователей с помощью идентификаторов устройств (MADID), собираемых через мобильный SDK. SDK Pushwoosh не собирает рекламные идентификаторы (GAID на Android, IDFA на iOS) автоматически. Обе платформы требуют явного согласия пользователя перед считыванием идентификатора. В вашем приложении запросите согласие пользователя, считайте идентификатор, когда это разрешено, и передайте значение в SDK.

Android

1. Добавьте зависимость

implementation 'com.google.android.gms:play-services-ads-identifier:...'

2. Объявите разрешение AD_ID (требуется для targetSdk ≥ 33)

Добавьте это в ваш AndroidManifest.xml:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Осторожно

Без этого разрешения на Android 13+ AdvertisingIdClient.getAdvertisingIdInfo() молча возвращает нулевой UUID (00000000-0000-0000-0000-000000000000). SDK Pushwoosh нормализует это значение до null, поэтому MADID не отправляется на сервер, и сопоставление аудитории Meta не будет работать.

3. Получите GAID и передайте его в SDK

getAdvertisingIdInfo должен вызываться в фоновом потоке:

String gaid = AdvertisingIdClient.getAdvertisingIdInfo(context).getId();

Pushwoosh.getInstance().setAdvertisingId(gaid);

Чтобы очистить сохраненное значение на бэкенде, передайте null или пустую строку:

Pushwoosh.getInstance().setAdvertisingId(null);

Примечания к поведению:

• Если значение не изменилось с момента последнего успешного вызова, сетевой запрос не выполняется.
• Если сетевой запрос не удался, повторите попытку при следующем запуске приложения.
• Вызов игнорируется, когда активен Pushwoosh.stopCommunication().
• Нулевой UUID (00000000-0000-0000-0000-000000000000) обрабатывается так же, как null — сохраненный MADID очищается на бэкенде.

iOS

1. Добавьте описание использования в Info.plist

Apple требует этот ключ перед отображением диалогового окна разрешений ATT:

<key>NSUserTrackingUsageDescription</key>
<string>We use your advertising identifier to show you relevant ads.</string>

2. Объявите домен отслеживания в вашем манифесте конфиденциальности

Если ваше приложение использует IDFA для отслеживания, Apple требует, чтобы вы перечислили домены, которые получают данные отслеживания, в вашем манифесте конфиденциальности (PrivacyInfo.xcprivacy). Полные требования см. в TN3182.

Установите NSPrivacyTracking в true и добавьте домен отслеживания Pushwoosh в NSPrivacyTrackingDomains:

<key>NSPrivacyTracking</key>
<true/>
<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.svc-nue.pushwoosh.com</string>
</array>

Примечание

Если пользователь не предоставил разрешение ATT, iOS блокирует сетевые запросы ко всем доменам, перечисленным в NSPrivacyTrackingDomains. MADID не будет отправлен независимо от того, что делает ваш код.

3. Запросите авторизацию отслеживания и передайте IDFA в SDK

ATTrackingManager требует iOS 14 или более поздней версии. Если ваша цель развертывания ниже iOS 14, оберните вызов в проверку доступности.

SDK Pushwoosh не вызывает ATTrackingManager. Запросите авторизацию отслеживания в вашем приложении, а затем передайте результат в SDK:

import AppTrackingTransparency
import AdSupport

if #available(iOS 14, *) {
    ATTrackingManager.requestTrackingAuthorization { status in
        let idfa = status == .authorized
            ? ASIdentifierManager.shared().advertisingIdentifier.uuidString
            : nil
        Pushwoosh.configure.setAdvertisingId(idfa)
    }
}

Чтобы очистить сохраненное значение на бэкенде, передайте nil или пустую строку:

Pushwoosh.configure.setAdvertisingId(nil)

Примечания к поведению:

• Если значение не изменилось с момента последнего успешного вызова, сетевой запрос не выполняется.
• Если сетевой запрос не удался, вызовите setAdvertisingId еще раз при следующем запуске приложения.
• Вызов игнорируется, когда Pushwoosh_ALLOW_SERVER_COMMUNICATION отключен.
• Нулевой UUID (00000000-0000-0000-0000-000000000000) обрабатывается так же, как nil или пустая строка — сохраненный MADID очищается на бэкенде.

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

Как это работает

Как только вы вызовете setAdvertisingId, SDK отправит это значение на конечную точку отслеживания Pushwoosh в качестве поля madid вместе с кодом приложения и аппаратным ID устройства. Pushwoosh использует этот идентификатор для сопоставления записей ваших устройств с аудиториями Meta Ads для синхронизации.

Синхронизация аудиторий в Journey

Элемент Audience sync в Journey Builder связывает ваш Journey с Meta Custom Audience. Каждый раз, когда пользователь достигает этого элемента, Pushwoosh запрашивает у Meta либо добавить его в аудиторию, либо удалить из нее.

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

Чтобы настроить синхронизацию аудитории:

1. Откройте Journey Builder.

2. Добавьте Вход на основе аудитории. В Источнике аудитории выберите сегмент или список Pushwoosh, который определяет, кто войдет в этот Journey. Например, сегмент Пользователи с тегом webinar_registered, установленным в true. Только эти пользователи будут продвигаться по Journey и достигнут элемента Audience sync.

3. Добавьте элемент Audience sync.

4. В разделе Как синхронизировать информацию о пользователях с аудиторией Meta выберите один из вариантов:

   • Добавлять пользователей в аудиторию. Добавляет каждого пользователя, достигшего этого шага, в выбранную вами аудиторию Meta. Например, используйте это, чтобы начать показывать рекламу пользователям, которые зарегистрировались, но еще не посетили мероприятие.
   • Удалять пользователей из аудитории. Удаляет каждого пользователя, достигшего этого шага, из этой аудитории Meta. В этом примере выберите этот вариант, чтобы прекратить показ рекламы вебинара пользователям, которые уже зарегистрировались.

5. В Аккаунте Meta Ads выберите подключенный рекламный аккаунт.

6. В Аудитории выберите аудиторию Meta, например, Вебинар.

7. Нажмите Применить, чтобы сохранить элемент, или Отмена, чтобы закрыть без сохранения.

8. Завершите настройку Journey, а затем запустите его.

Когда эти пользователи достигают элемента Audience sync, они удаляются из аудитории Вебинар в Meta, поэтому они больше не видят там рекламу вебинара.

Поведение и обработка ошибок

Обработка Journey зависит от доступности аккаунта и аудитории Meta:

• Meta обновляет аудиторию только тогда, когда может сопоставить пользователя по данным, предоставленным Pushwoosh. Если Meta не может сопоставить пользователя, аудитория для этого пользователя не изменяется, и он продолжает движение по Journey.
• Если профиль достигает элемента Audience sync, когда подключенный рекламный аккаунт отключен, Journey для этого профиля останавливается, и Pushwoosh отправляет системные и email-уведомления.
• Если выбранная аудитория не найдена в Meta и API возвращает ошибку, Journey для этого профиля останавливается, и Pushwoosh отправляет системные и email-уведомления.

Статистика Audience sync

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