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

<Aside type="caution" icon="setting" title="Требуется помощь разработчика">
 Вам понадобится помощь вашей команды разработчиков для настройки интеграции. Пожалуйста, поделитесь с ними этим руководством.
</Aside>

Интеграция с [Meta Ads](https://www.facebook.com/business/ads) позволяет синхронизировать аудитории Pushwoosh с вашими рекламными аккаунтами Meta. Используйте ее для таргетинга или исключения пользователей в рекламных кампаниях и добавления платной рекламы в качестве еще одного канала в вашем customer journey.

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

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

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


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

* У вас есть роль **Admin** в вашем аккаунте Pushwoosh. О том, как работают роли и разрешения, читайте в разделе [Управление доступом и разрешениями пользователей](/ru/product/account-management-and-security/multi-login-accounts/#creating-and-managing-roles-also-known-as-groups).
* У вас настроен [**Facebook Business Manager**](https://www.facebook.com/business/tools/business-manager) для управления ресурсами вашего бренда в Facebook, включая рекламные аккаунты, страницы и приложения.
* У вас есть активный [**рекламный аккаунт Facebook**](https://www.facebook.com/business/tools/ads-manager), привязанный к вашему Business Manager.
* Администратор вашего Facebook Business Manager предоставил вам разрешения **Manage Campaigns** или **Manage ad accounts** для рекламных аккаунтов, которые вы планируете использовать с Pushwoosh.
* Вы приняли условия использования рекламного аккаунта для этих аккаунтов.
* Вы приняли [**Условия использования пользовательских аудиторий Facebook**](https://business.facebook.com/legal/terms/customaudience) для рекламных аккаунтов Facebook, которые вы планируете использовать с Pushwoosh.

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

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

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

<img src="/integrations-meta-ads-integration-1.webp" alt="Страница сторонних интеграций с карточкой Meta Ads, показывающей ссылки на конфигурацию, руководство по настройке и страницу входа"/>

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

4. Выберите рекламные аккаунты, которые вы хотите подключить.
<img src="/integrations-meta-ads-integration-6.webp" alt="Экран Meta для выбора опции доступа к бизнес-аккаунту для подключенной интеграции" width="480" />

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

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

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


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

<img src="/integrations-meta-ads-integration-8.webp" alt="Страница Meta Ads в Pushwoosh со значком 'Подключено', таблицей рекламных аккаунтов со столбцом бизнес-аккаунта, действиями в заголовке и разделом 'Как синхронизировать аудитории с Meta'" />

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

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

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

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

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

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

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

<img src="/integrations-meta-ads-integration-4.webp" alt="Диалоговое окно 'Управление рекламными аккаунтами' с переключателем 'Показывать только подключенные', поиском по имени или ID, переключателями строк со значками 'Подключено' или 'Отключено', кнопками 'Отмена' и 'Применить'" />



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

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

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

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

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

<img src="/integrations-meta-ads-integration-3.webp" alt="Модальное окно сопоставления тегов проекта с полями Meta со столбцами 'Поле Facebook' и 'Имя тега', флажком перезаписи, кнопками 'Отмена' и 'Сохранить'" width="480" />

<Aside type="note" title="Автоматически сопоставляемые поля">
Pushwoosh сопоставляет эти поля автоматически. Вам не нужно настраивать их в **Map project tags to Meta fields**:

* **Email**
* **Phone number**
* **MADID**
</Aside>
3. Нажмите **Save**, чтобы применить сопоставление, или **Cancel**, чтобы закрыть без сохранения.

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

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

<Tabs syncKey="maid-sdk">
<TabItem label="Android">

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

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

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

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

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

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

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

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

```java

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

Pushwoosh.getInstance().setAdvertisingId(gaid);

```

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

```java
Pushwoosh.getInstance().setAdvertisingId(null);
```

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

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

</TabItem>
<TabItem label="iOS">

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

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

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

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

Если ваше приложение использует IDFA для отслеживания, Apple требует, чтобы вы перечислили домены, получающие данные отслеживания, в вашем [манифесте конфиденциальности](https://developer.apple.com/documentation/bundleresources/privacy-manifest-files) (`PrivacyInfo.xcprivacy`). Полные требования см. в [TN3182](https://developer.apple.com/documentation/technotes/tn3182-adding-privacy-tracking-keys-to-your-privacy-manifest).

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

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

<Aside type="note">
Если пользователь не предоставил разрешение ATT, iOS блокирует сетевые запросы ко всем доменам, перечисленным в `NSPrivacyTrackingDomains`. MADID не будет отправлен независимо от того, что делает ваш код.
</Aside>

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

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

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

```swift
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` или пустую строку:

```swift
Pushwoosh.configure.setAdvertisingId(nil)
```

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

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

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

</TabItem>
</Tabs>

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

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


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

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

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

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

1. Откройте [**Journey Builder**](/ru/product/customer-journey/pushwoosh-journey-overview/).

2. Добавьте [**Audience-based entry**](/ru/product/customer-journey/journey-elements/entry-elements/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**.

<img src="/integrations-meta-ads-integration-10.webp" alt="Панель Audience sync с выпадающим списком Audience и выбранной Meta Custom Audience" />

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

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

<img src="/integrations-meta-ads-integration-9.webp" alt="Панель Audience sync с названием шага, опциями добавления или удаления пользователей, выбором аккаунта Meta Ads, аудитории, и кнопками 'Применить' и 'Отмена'" />

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

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

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

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

## Статистика синхронизации аудитории
После запуска откройте статистику для шага **Audience sync**, чтобы увидеть количество входов, добавлений и удалений, а также пропущенные профили. Подробнее о метриках см. в разделе [**Audience sync**](/ru/product/statistics-and-analytics/journey-statistics/journey-element-statistics/#audience-sync) в **статистике Customer Journey**.

<img src="/integrations-meta-ads-integration-11.webp" alt="Статистика Audience sync с общим количеством входов, добавленными в аудиторию Meta, удаленными из аудитории Meta, пропущенными (несинхронизированными) переходами к следующему шагу, экспортом пользователей и рекламным аккаунтом Meta для синхронизации" />