API Insights

Единый интерфейс для получения статистики рекламы.

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

Чтобы получать сведения о результативности рекламы, настройте отслеживание важных для вас метрик. Это можно сделать с помощью меток URL, пикселя Meta и Conversions API.

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

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

• разрешение ads_read;
• приложение (подробности см. в статье Разработка приложений Meta).

Статистика кампании

Получение статистики по результативности кампании за последние 7 дней:

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

Подробные сведения см. в справке по Ad Insights.

Выполнение вызовов

API Insights доступен в виде границы контекста для любого объекта рекламы.

Запрос

Вы можете запросить определенные поля в виде списка с разделителями-запятыми в параметрах fields. Пример:

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"
    

Ответ

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Уровни

Результаты собираются на определенном уровне объекта. При этом автоматически выполняется дедупликация данных.

Запрос

Например, можно получить статистику кампании на уровне отдельных рекламных объявлений.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/CAMPAIGN_ID/insights"

Ответ

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Если у вас нет доступа ни к каким рекламным объектам на нужном уровне, вызов статистики не вернет никаких данных. Например, вы запрашиваете статистику, установив для параметра level значение ad. Если у вас нет доступа хотя бы к одному объекту в этом рекламном аккаунте, этот вызов API вернет ошибку, связанную с разрешением.

Окна атрибуции

Окно атрибуции конверсии определяет промежутки времени, в течение которых мы соотносим то или иное событие с конкретной рекламой на платформа Meta. Подробные сведения см. в разделе об окнах атрибуции в Справочном центре Meta для бизнеса. Мы измеряем действия, совершаемые вместе с событиями конверсии, за периоды 1 и 7 дней в прошлом. Чтобы просмотреть действия, отнесенные к различным окнам атрибуции, выполните запрос к /{ad-account-id}/insights. Если вы не предоставите action_attribution_windows, мы воспользуемся значением 7d_click и укажем его для value.

Например, укажите action_attribution_windows. При этом value будет исправлено в окне атрибуции 7d_click. Выполните запрос к act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'], и вы получите следующий результат:

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

Расширение поля

Запросите поля на уровне узла и по полям, указанным в расширении поля.

Запрос

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_ID"

Ответ

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Сортировка

Чтобы отсортировать результаты, укажите параметр sort со значением {fieldname}_descending или {fieldname}_ascending:

Запрос

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID/insights"

Ответ

{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Ярлыки рекламы

Статистика по всем ярлыкам с идентичными названиями. Агрегируется в единое значение на уровне объекта рекламы. Подробности см. в справке по ярлыкам рекламы.

Запрос

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

Ответ

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

Определения кликов

Чтобы лучше понять метрики кликов, предлагаемые Meta, изучите их определения и принципы использования:

• Клики по ссылкам, actions:link_click — количество кликов по содержащимся в рекламе ссылкам на ресурсы Meta или других компаний. Подробные сведения см. в этой статье.

• Клики (все), clicks — учитывает разные виды кликов по рекламе, в том числе некоторые типы взаимодействия с контейнером рекламы, ссылками на другие целевые страницы и ссылками на развернутую рекламу. Подробные сведения см. здесь.

Удаленные и заархивированные объекты

Рекламные блоки могут иметь статус DELETED или ARCHIVED. Статистика по удаленным или перенесенным в архив объектам отображается при отправке запроса родительским объектам. Таким образом, если вы запросите impressions на уровне группы объявлений, результаты будут содержать метрику impressions для всех объявлений в этой группе, включая удаленные и перенесенные в архив. См. также рекомендации по хранению и извлечению рекламных объектов.

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

Однако статистику объектов ARCHIVED также можно получить от родительских узлов с помощью дополнительного параметра filtering.

Запрос

Чтобы получить статистику всей рекламы со статусом ARCHIVED в рекламном аккаунте, выполните следующий запрос:

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/insights/"

Ответ

Обратите внимание: в этом ответе будут выданы только заархивированные объекты.

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Статистика по удаленным объектам

Вы можете запрашивать статистику по удаленным объектам с помощью их ID или фильтра ad.effective_status.

Запрос

Например, если у вас есть ID группы объявлений:

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID"
    

В этом примере в запросе используется ad.effective_status:

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

Ответ

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Устранение неполадок

Таймауты

Чаще всего к сбою этой конечной точки приводит слишком большое количество запросов и таймаутов:

• При запросах /GET или синхронных запросах вы можете получать ошибки таймаута или нехватки памяти.
• При запросах /POST или асинхронных запросах могут возникнуть ошибки таймаута. Выполнение асинхронных запросов, в том числе повторных попыток, может занять час. Например, это может произойти, если вы выполните запрос для сбора большого объема данных от множества объектов на уровне отдельных рекламных объявлений.

Рекомендации

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

Ограничение числа обращений

API Insights Meta ограничивает число обращений, чтобы обеспечить оптимальную производительность при создании отчетов для всех наших партнеров. Дополнительную информацию и советы см. в разделе Ограничения и рекомендации для API Insights.

Расхождение с данными Ads Manager

Работа API по умолчанию отличается от работы Ads Manager по умолчанию. Если вы хотите получать те же результаты, что и в Ads Manager, задайте для поля use_account_attribution_setting значение true.

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

• Статистика рекламного аккаунта
• Статистика рекламной кампании
• Статистика группы объявлений
• Статистика рекламы

Конечные точки, не вошедшие в список выше, не поддерживаются этим API. Если вы хотите добавить в свое решение отчеты Meta, ознакомьтесь с условиями использования платформы Meta и правилами API Marketing для разработчиков.