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

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

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

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

Варианты использования

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

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

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

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

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

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

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

2. На карточке Meta Ads нажмите Login page.

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

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

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

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

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

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

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

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

Нажмите на три точки в конце строки и выберите Remove ad account, чтобы удалить этот рекламный аккаунт из списка в Pushwoosh.

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

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

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

• Включите или выключите Show only connected, чтобы ограничить отображаемые строки.
• Введите текст в поле Search by name or id…, чтобы найти аккаунты в списке.

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

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

Примечание

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

1. На странице Meta Ads нажмите Map user data.

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

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

Pushwoosh сопоставляет эти поля автоматически. Вам не нужно настраивать их в Map project tags to Meta fields:

• Email
• Phone number
• MADID

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

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

Meta Ads сопоставляет пользователей с помощью идентификаторов устройств (MADID), собранных через мобильный SDK. Pushwoosh SDK не собирает рекламные идентификаторы (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). Pushwoosh SDK нормализует его до 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, оберните вызов в проверку доступности.

Pushwoosh SDK не вызывает 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 из основного UI-потока вашего приложения. Apple рекомендует делать это после показа вашего собственного пояснительного экрана, а не сразу при запуске.

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

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

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

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

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

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

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

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

3. Добавьте точку Audience sync.

4. В разделе How to sync users info to Meta audience выберите один из вариантов:

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

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

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

7. Нажмите Apply, чтобы сохранить точку, или Cancel, чтобы закрыть без сохранения.

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

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

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

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

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

Статистика синхронизации аудитории

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