App Events API

App Events API позволяет отслеживать события в мобильном приложении или на веб-странице, например установки приложения или события покупок. Отслеживание событий позволяет измерять результативность рекламы и создавать аудитории для таргетинга рекламы.

Дополнительные сведения об отслеживании событий в приложении для переписок с клиентами см. в этой статьедокументации по платформе Messenger.

Принцип работы

Существует три типа событий в приложении:

• автоматически регистрируемые события — Facebook SDK автоматически регистрирует установки приложения, его сеансы и покупки в приложении;
• стандартные события — распространенные события, которые предлагает Facebook;
• специально настроенные события — события, которые вы сами настраиваете для своего приложения.

Событие в приложении состоит из трех элементов:

1. name — обязательная строка, описывающая событие. Когда событие в приложении отправляется в Analytics, это имя добавляется в журнал событий.
2. valueToSum — необязательное значение, которое Analytics добавляет к другим суммируемым значениям из одноименных событий в приложении.
3. parameters — необязательные значения, добавляемые в событие в приложении.

Можно использовать не более 1 000 уникальных имен событий. Примечание. После достижения этого лимита регистрация новых типов событий прекращается, и выдается ошибка 100 Invalid parameter. При этом устаревшие события можно отключить. Подробную информацию об ограничениях для событий см. в часто задаваемых вопросах.

Прежде чем начать

Вам понадобятся:

• ваш ID рекламодателя и рекламный ID устройства Android или рекламный идентификатор устройства Apple (IDFA);
• маркер доступа приложения для Facebook (не храните маркер доступа приложения в клиенте).

Установки приложения

Отправьте запрос POST с сервера к конечной точке /{app-id}/activities с параметрами application_tracking_enabled и advertiser_tracking_enabled.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id={advertiser-tracking-id}
   &{app-access-token}"

В случае успеха приложение получит следующий ответ:

{
  "success": true
}

Оговорки

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

Список доступных параметров см. в справочном руководстве.

Включение отслеживания рекламы

В поле advertiser_tracking_enabled указано, включено ли на устройстве пользователя отслеживание рекламы. Чтобы отключить его, установить для этого поля значение 0, чтобы включить — значение 1. Вы должны получить эти данные и вернуть их Facebook, чтобы определить, можно ли использовать отслеживание рекламы для оптимизации или конверсий. Meta использует данные о событиях (сведения о действиях пользователей за пределами Meta, полученные от партнеров) в соответствии со своей Политикой использования данных, в том числе для отчетов по рекламе, выявления мошенничества, а также создания и улучшения наших продуктов (включая продукты для показа рекламы), однако сведения о конкретном пользователе используются только для персонализации рекламы, которая ему демонстрируется. На устройствах с версиями iOS младше 6 для этого параметра по умолчанию следует использовать значение 1.

Сведения о том, как определить статус отслеживания для пользователя, см. в справке Apple по AdSupport.

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

Текущую настройку флажка отслеживания можно получить из свойства Settings.shared.isAdvertiserTrackingEnabled.

print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")

Отключение отслеживания рекламы

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

События конверсии

Отправьте запрос POST к конечной точке /{app-id}/activities, задав при этом для параметра event значение CUSTOM_APP_EVENTS и указав advertiser_tracking_enabled для каждого отдельного события. Необходим параметр advertiser_id или attribution.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

В случае успеха приложение получит следующий ответ:

{
  "success": true
}

Атрибуция

Конечная точка attribution возвращает данные об установках и конверсиях на основании кликов по рекламе за последние 28 дней. В Ads Manager используется модель атрибуции просмотров за 1 день и кликов за 28 дней. Статистика представлена по времени показа или клика (не по времени установки или конверсии). Это следует учитывать, если вы будете сравнивать свои отчеты с отчетами в Ads Manager. Помимо стандартных событий в приложении после клика по рекламе, рекомендуем учитывать следующее:

• Атрибуция по просмотрам. Параметр consider_views=TRUE возвращает данные атрибуции по установкам, которые произошли в течение 1 дня после показа рекламы, при условии, что пользователь аккаунта из Центра аккаунтов не нажал рекламу в течение 28 дней. При этом возвращается параметр is_view_through=TRUE, а параметр view_time занимает место параметра click_time. Все остальные атрибуции совпадают с данными атрибуции по кликам рекламы.

• Атрибуция по кампаниям. Рекламодатели могут отслеживать результативность рекламы, которая привела к событию в приложении. Facebook собирает данные о событиях в приложении, произошедших благодаря рекламным кампаниям, цель которых отличается от установок мобильного приложения и вовлеченности для мобильного приложения. Эти данные отображаются, только если рекламодатель добавил приложение в поле "Отслеживание событий в мобильном приложении" рекламы.

• Пример. При желании клиент может отслеживать в Ads Manager установки, привлеченные рекламой с целью "Публикация Страницы" или "Клики на сайт", которая перенаправляет людей на мобильный сайт, а Facebook будет собирать данные об установках приложения.

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

• Пример. Пользователь нажимает рекламу приложения на iPhone, а затем устанавливает это приложение на iPad. В этом случае мы поймем, что именно реклама на iPhone привлекла установку приложения на iPad независимо от таргетинга рекламы.

Расширенный поиск совпадений

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

Отправьте запрос POST к конечной точке /{app-id}/activities, указав в параметре ud информацию для отслеживания клиента, например электронный адрес или номер телефона. Все данные клиентов должны хэшироваться. В противном случае Facebook их проигнорирует. Укажите advertiser_tracking_enabled для каждого события.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
      "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

В случае успеха приложение получит следующий ответ:

{
  "success": true
}

Перед отправкой на Facebook все данные пользователей необходимо хэшировать по алгоритму SHA256. Нехэшированные данные игнорируются.

Дедупликация

Мы применяем для событий в приложении те же функции дедупликации, что и для веб-событий. Дедупликация выполняется на основании полей event_id и event_name. Параметр event_id позволяет различить похожие события. Неправильный ID события может стать причиной ошибочной дедупликации конверсий и повлиять на отчетность по конверсиям и эффективность кампании.

Расширенная информация об устройстве

С помощью /{app-id}/activities?extinfo в вызове события в приложении можно отправлять информацию об устройстве, например о ширине и высоте экрана. Значения должны быть разделены запятыми и перечислены в порядке, указанном в справочном руководстве по конечной точке /application/activites. При использовании extinfo необходимо указать все значения.

• Параметр version должен иметь значение a2 для Android.
• Параметр version должен иметь значение i2 для iOS.

Справка

• Параметры ApplicationActivities
• Документация Android для разработчиков: метрики дисплея
• Документация Android для разработчиков: внешнее хранилище
• Документация Apple для разработчиков: метрики дисплея
• Документация Apple для разработчиков: внешнее хранилище
• Документация Apple для разработчиков: размер экрана

Сбор файлов cookie для мобильных устройств

Мы рекомендуем связывать события в приложении с advertiser_id. Однако на устройствах под управлением Android и iOS до версии 6 можно использовать параметр attribution, задающий файлы cookie для мобильных устройств.

Примечание. Файлы cookie для мобильных устройств не зависят от свойств пользователя или устройства. Они непостоянны и часто обновляются. Не используйте их для ретаргетинга рекламы.

Android

Файл cookie представляет собой строку, состоящую из 22 случайных букв и цифр.

Получение ID Facebook Атрибуции с помощью ContentProvider:

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

Также следует получить рекламный ID вашего приложения для Android.

iOS

Файл cookie для мобильных устройств создается приложениями Facebook для iOS с помощью CFUUIDCreateString. Он представляет собой 128-битную строку UUID.

Получите ID файла cookie и IDFA и отправьте их на Facebook в качестве идентификатора:

ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (advertiserID) {
  // do stuff
}

Заголовок HTTP X-Forwarded-For

Если запросы POST отправляются из централизованного местоположения (например, с сервера или прокси), т. е. используется вызов между серверами, для получения точной информации о местоположении и устройстве потребуется заголовок HTTP X-Forwarded-For. Отправляйте IP-адрес устройства в формате IPv4 или IPv6 через заголовок HTTP X-Forwarded-For в каждом своем запросе событий в приложении. Благодаря этому мы сможем сопоставить advertiser_id с корректным IP-адресом и использовать его на нашей платформе.

Пример для IPv6

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

Пример для IPv4

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

Тестирование

1. Откройте Events Manager.
2. Нажмите "Источники данных" в левой части страницы.
3. Выберите название и ID нужных данных.
4. Нажмите "Тестирование событий" и в качестве канала выберите "Приложение".
5. Отправьте запрос AE-API с помощью инструмента Graph API.
6. Ваши взаимодействия вскоре будут показаны на вкладке "Тестирование событий".

Расхождения

Если клиент сравнит отчеты от Mobile Measurement Partner (MMP) с отчетами от Facebook и найдет расхождения в данных, проверьте перечисленные далее моменты.

Если в отчете Facebook меньше установок, чем у MMP:

• правильно ли интегрирован Facebook SDK;
• не использует ли клиент некорректный ID приложения.

Если в отчете Facebook больше установок, чем у MMP:

• настроены ли одинаковые окна атрибуции (как правило, Facebook анализирует большее окно атрибуции, чем большинство приложений Mobile Measurement Partner);
• правильно ли интегрирован SDK от MMP;
• не использует ли клиент некорректный ID приложения;
• встречается ли расхождение только в iOS7 и правильно ли MMP получает рекламный идентификатор Apple (IDFA) от устройства и отправляет его на Facebook.

Справка

Дополнительная информация о приложении

Подробнее о том, как получить дополнительную информацию о приложении, см. в справке по конечной точке /application/activites.

Параметры данных пользователя

Имена стандартных событий

Параметры стандартных событий

См. также

• События в приложении
• Рекомендации по использованию событий в приложении
• Обработка ошибок
• Соблюдение требований Общего регламента по защите данных
• Facebook Ads Manager
• Панель приложений Facebook