Graph API

Version 2.9

Graph API | Marketing API

Записи в журнале изменений разделяются на следующие категории:

  • Новые функции: новые продукты или услуги, включая новые узлы, поля и границы контекста.
  • Изменения: изменения существующих продуктов или услуг (за исключением упраздненных элементов).
  • Упраздненные элементы: существующие продукты или услуги, которые будут упразднены.
  • Важные изменения за 90 дней: изменения, которые вступят в силу через 90 дней после даты выпуска версии (в эту категорию входят и случаи упразднения элементов).

Категории Новые функции, Изменения и Упраздненные элементы относятся только к этой версии. Категория Важные изменения за 90 дней относится ко всем версиям.

Категория Важные изменения здесь не упоминается, так как она не привязана к определенным выпускам.

Graph API

Released April 18, 2017 | Available until July 18, 2019

New Features

General

  • Read After Write - Graph API POST requests now support returning specified values of an object during the same request as a write, saving a round trip for clients. If a fields parameter is specified (explanation of the syntax), the request will first do the write, then read the created or updated object, selecting fields using the fields parameter, as the response. Read-after-write is now enabled for all versions of the Graph API. Visit our docs page to learn more.

  • New short_names Field on the User Object - The following field has been added to the user endpoint:

    • short_name - first_name assumes the universally friendly way to refer to a person is by their first name. However, in many cultures (especially Chinese, Japanese, Korean, Thai, Indic, and a few others), it's inappropriate to address people by their first name. The new short_name method understands the culture-specific rules for how to address a person with a short name. So, for a viewer in the US, they'll continue to see friends in China, Japan, Korea, and India addressed by their first name, but their friends in East and South Asia will see friends with full names.

Pages

  • Business App Page Mapping - The user node has two new edges, ids_for_pages and ids_for_apps, for de-referencing a person's ID for an app or a page. The ids_for_pages edge returns other IDs that person has for pages owned by the same business. Similarly, the ids_for_apps edge returns other IDs that person has for apps owned by the same business. See Connecting with People Across Apps and Bots in Messenger.

  • Page POST Support to Add Pages to Crosspost Videos - Approve and accept a crossposting relationships request from another page by POST /{page_id}/crossposting_pages.

  • Webhooks IDs Are Serialized as Strings - Numeric IDs are converted to strings in this webhooks update.

Permissions

Places Graph

  • Current Place - The following fields have been added:

    • GET /current_place/results - Helps determine what place a person is currently at by using location signals. User permission is required.
    • POST /current_place/feedback - Allows you to provide feedback about whether they were actually there. For more information, see Places Graph

  • GET /search?type=place - The following parameters have been added:

    • categories - Search by category.
    • matched_categories - Indicate which categories the resulting place matches. Must be used with categories.

Video APIs

  • Time Spent in Video Metrics for Page - The following metrics have been added. For more information, see Insights Metric /{object-id}/insights/{metric}.

    • page_video_view_time- The time spent on videos on the page.
    • post_video_view_time_by_country_id - The time spent on videos on the page by country.

Webhooks

  • Apps Can Receive Changed Values for User's Profile Updates with Webhooks Updates - When a user changes a field, your app can receive the new value as part of the update, saving the step of checking the value. Previously, whenever a user changed one of their fields, we would notify the app of the field that changed without sending the new value.

  • Documentation - Webhooks now has reference documentation for topics and fields you can subscribe to. This documentation is on Facebook Developers site under Webhooks Reference in the Graph API.

  • Sample Sender Tool - The new tool makes it easier for developers to test out the Webhooks update structure before subscribing to the topic. In the past, developers had to subscribe to a field and then try to trigger the update by making a change through Facebook. For example, an app might need to know when a user (users that installed the app and granted needed permissions) changes their profile picture. The app would subscribe to the profile picture field in the Webhooks framework. However, to test how this works, you had to change the profile picture on some user that had installed the app to see the structure of the update we send. The sample sender tool allows apps to test the update structure without having to make an unnecessary change. You can find the sample sender tool in the webhooks section of your app's dashboard.

  • Versioning - Webhooks versions are now the same as Graph API. Any existing Webhooks subscriptions will be running on the oldest supported version of the app. Previously, Webhooks subscriptions didn't support versioning. The only way to make changes was by making breaking changes. For more information on Webhooks versions, see Versioning.

Changes

General

  • The Batch API returns an error rather than a null response for aborted request items in the Batch API. For more information, see Graph API, Making Batch Requests.

  • GET /{url}/share - The share endpoint has been removed and replaced with:

    • engagement field with subfields:
      • comment_count
      • comment_plugin_count
      • reaction_count
      • share_count

Pages

  • /{page-id}/feed - Backdated posts are included in the {page_id}/feed request if the backdated_time of the post is within the since and until time range. The created_time is the actual creation time. (See changes to Posts below.)

  • page-restaurant-services - All fields now return false or true instead of 0 or 1.

  • GET /{post-id} - The following field has been added to this endpoint:
    • promotable_id - Previously, certain posts could not be promoted, only their contents. In such cases, the id field would return the contents ID, rather than the ID for the post. Posts now always return their own ID in the id field, and a new field, promotable_id, is added to the GET {post-id} endpoint to be used when promoting the post.

Posts

  • Backdating a post will no longer update the post's created_time value. Instead, it will duplicate the original, but with created_time and backdated_time set to the new value. The original post will keep its old created_time value and gain the new backdated_time and value. Finally, GET {post-id}/feed will no longer return the original post, but instead will return the newly created duplicate.

Video API

  • Expose dash preview URL for live video instead of RTMP URL.

  • GET /{page_id}/crosspost_pending_approval_pages - List all the Pages your Page has sent crossposting requests, but that have not accepted yet.

  • GET /{page_id}/crosspost_whitelisted_pages - List all the pages you have given crossposting permission.

  • POST /{video_id}/allow_crossposting_for_pages = [{"page_id": {page_id}, "allow": {true/false}] - Allow or disallow the permission for certain Pages in your crossposting allow list to crosspost a specific video.

  • POST /{page_id}/crossposting_pages=[{"page_id": {page_id}, "allow": false, "action": "EXPIRE_ALL_CROSSPOSTS_ON_SHARED_ASSETS"}] - Remove pages from your crossposting allow list and expire all previously crossposted content.

  • POST /{page_id}/crossposting_pages=[{"page_id": {page_id}, "allow": false, "action": "NO_ACTION"}] - Remove pages from your crossposting allow list without affecting previously crossposted content.

Webhooks

  • GET /{app-id}/subscriptions - This endpoint now returns versions for fields. Before Webhooks versioning was introduced, the endpoint returned only a list of subscribed fields. Now the endpoints return the list of fields with their respective versions.

Deprecations

Messages

  • GET /{message-id} - The following field has been deprecated:
    • subject
  • GET /{thread-id} - The following field has been deprecated:
    • tags

90-Day Breaking Changes

  • The following fields are deprecated for edges and dialogs that allow attaching links to posts:

    • caption
    • description
    • name
    • picture
    • thumbnail

  • The edges and dialogs for which these are deprecated include:

    • POST /{event-id}/feed
    • POST /{group-id}/feed
    • POST /{page-id}/feed
    • POST /{user-id}/feed
    • share and feed dialogs

Video

  • Insights Edge - All paid and organic metrics are deprecated.

Webhooks

  • The following Webhooks fields from the user topic are deprecated:

    • about_me
    • birthday_date
    • contact_email
    • current_location
    • education_history
    • hometown_location
    • sex
    • statuses
    • tv
    • work_history

  • Instead use:

    • about
    • birthday
    • education
    • email
    • gender
    • hometown
    • location
    • status
    • television
    • work

Новые функции в API Marketing версии 2.9

Оформление рекламы

С помощью API Marketing на Facebook можно создавать кампании с Холстами. Формат видеорекламы позволяет рекламодателям продвигать бренды и достигать целей с прямым откликом. Подробнее см. в разделе API Marketing, реклама на Холсте.

Динамическая реклама

  • Новые API для динамической рекламы: API Checks и API Quality. API Checks позволяет убедиться, что источник сигналов предоставляет достаточно информации, чтобы показывать подходящие объявления в формате динамической рекламы. API Quality позволяет проверить и убедиться, что ваш каталог и лента содержат достаточно качественной информации для показа динамической рекламы. Подробнее см. в разделе Динамическая реклама, качество каталога и сигналов.

  • Несколько изображений одного объекта: теперь динамическая реклама в формате кольцевой галереи позволяет показывать несколько изображений одного объекта. В такую рекламу можно добавить до 20 изображений из каталога, соответствующих одному объекту. Например, таким объектом может быть отель или место назначения. Для этой функции мы добавили новые опции: force_single_link = true и show_multiple_images = true. Сведения см. в разделах «Динамическая реклама», «Управление рекламой», «Шаблон оформления».

Управление рекламой

  • Рекламный текст — теперь вы можете дублировать кампании, группы объявлений и отдельные объявления с помощью API Ad Copy. В этом случае вам не потребуется каждый раз создавать рекламу с нуля, потому что вы сможете дублировать эффективные объявления и создать из них шаблоны рекламы. См. раздел Оформление, плейсменты и предварительный просмотр рекламы.

  • Приблизительный дневной охват — мы добавили новый эндпойнт /delivery_estimate на уровне рекламного аккаунта и группы объявлений. Этот эндпойнт позволяет узнать предполагаемый результат ставки — дневной охват и количество конверсий для выбранной группы объявлений. Подробнее см. в разделе Таргетинг, предполагаемый дневной охват.

  • API Rules Engine — позволяет проще и эффективнее управлять рекламой на основе правил компании, которые вы задали. В API Rules Engine используется модель на основе push-уведомлений. Вместо того чтобы постоянно отправлять в API запросы на обновление информации о рекламе, мы заранее отправляем вам push-уведомления и выполняем указанные вами действия, когда условия соответствуют правилам. Подробнее об API Rules Engine см. здесь.

  • API Batch — группирование и асинхронная отправка запросов. Сгруппируйте несколько вызовов API Graph в один HTTP-запрос и выполните их асинхронно без блокировки. Помимо этого, в пакетном запросе можно задать зависимости между связанными операциями. Facebook обрабатывает независимые операции параллельно, а зависимые — последовательно. См. Асинхронные и пакетные запросы, API Batch.

Плейсмент рекламы

  • Эффективный плейсмент рекламы — вы можете указать плейсменты рекламы в настройках таргетинга, однако раньше вы не могли узнать, показал ли Facebook вашу рекламу во всех плейсментах. Если вы выбрали плейсменты, недопустимые для заданной цели, Facebook не будет показывать в них вашу рекламу. Ранее чтобы определить реальные результаты рекламы, приходилось запускать ее и экспериментировать с настройками. Теперь с помощью API Placement effective_ вы можете определить, какие из выбранных вами плейсментов соответствуют цели рекламы и были использованы для ее показа. С помощью API Recommendations вы также можете узнать, почему некоторые плейсменты исключены. См. «Таргетинг», «Дополнительно» «Эффективный плейсмент».

Важные изменения в API Marketing версии 2.9

Управление рекламой

  • Плейсмент в разделе «Рекомендуемое видео» — ранее был частью плейсмента в Ленте Facebook; вы автоматически выбирали его, если использовали плейсмент в Ленте. В версии 2.9 мы отделили плейсмент в разделе «Рекомендуемое видео» от плейсмента в Ленте. Теперь от него можно отказаться, даже если вы выбрали плейсмент в Ленте. Если вы использовали плейсмент в Ленте Facebook в версии 2.8 или более ранней версии, мы больше не будем автоматически показывать вашу рекламу в разделе «Рекомендуемое видео».

  • Цель «Местная узнаваемость» — мы упразднили цель кампании LOCAL_AWARENESS. Начиная с версии 2.9 использовать цель LOCAL_AWARENESS для создания новых кампаний нельзя. Чтобы повысить местную узнаваемость с помощью групп объявлений для одного места, используйте цель REACH. LOCAL_AWARENESS для нескольких мест больше не поддерживается. Если у вас есть кампании с этой целью, вы по-прежнему сможете считывать их, редактировать и создавать в них новые группы объявлений и отдельные объявления. Однако от типа существующей кампании зависит, сможете ли вы скопировать ее, чтобы создать новую. Если задано только одно место LOCAL_AWARENESS, мы скопируем кампанию с указанным значением REACH. Если задано LOCAL_AWARENESS и несколько мест, вы не сможете скопировать кампанию.

  • Цели мобильной рекламы — чтобы упростить цели мобильной рекламы, мы упразднили CanvasAppEngagement, CanvasAppInstalls, MobileAppInstalls и MobileAppEngagement. Это цели CAE, MAE, CAI и MAI (в том же порядке). Начиная с версии 2.9, вы не сможете создавать кампании с этими целями. Вместо них мы поддерживаем:

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

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

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

    • MAI с целью APP_INSTALLS; чтобы создать кампании с рекламой MAI, нужно использовать APP_INSTALLS.

  • Цели мобильной рекламы, совместимость — при дублировании кампаний CAE, MAE, CAI и MAI с помощью API Marketing API или инструментов Facebook мы автоматически преобразуем исключенные цели в эквивалентные цели из версии 2.9:

    • цели MAI или CAI преобразуются в APP_INSTALLS;

    • цель CAE преобразуется в LINK_CLICKS;

    • цель MAE преобразуется в LINK_LICKS или CONVERSIONS в зависимости от настроек оптимизации, которые вы задали для групп объявлений в кампании. При наличии дочерних групп объявлений, оптимизированных для OFFSITE_CONVERSION, мы преобразуем кампанию MAE в кампанию CONVERSIONS; в противном случае кампания MAE преобразуется в кампанию LINK_CLICKS.

  • Заблокированные категории — мы исключили некоторые категории рекламы Audience Network, вставок в видео и моментальных статей и заменили их более общими категориями для тех же плейсментов. Эти категории позволяют вам запретить показ рекламы в материалах определенного типа: про онлайн-казино, алкогольные напитки и т. д. Категории politics и religion упразднены. Доступны следующие категории:

    • Для моментальных статей и Audience Network: debated_social_issues, mature_audiences, tragedy_and_conflict, dating, gambling.

    • Для вставок в видео: debated_social_issues, mature_audiences, tragedy_and_conflict.

  • Из настроек оформления рекламы на уровнях рекламного аккаунта и отдельных объявлений упразднено поле SUPPLEMENTAL_MEDIA_ID. Вы больше не сможете считать его значение.

  • Из оформления рекламы упразднено поле ACTION_SPEC. Оно использовалось для рекламных статей, которые мы больше не поддерживаем.

  • В версиях 2.9 и 2.8 из оформления рекламы упразднены поля actor_image_hash, actor_image_url и actor_name. Они использовались вместе с элементом action_spec, который мы также упразднили.

  • Из оформления рекламы исключены поля link_title и link_description в call_to_action. Чтобы настроить заголовки и описания в оформлении рекламы, воспользуйтесь name и description в link_data или title и link_description в video_data.

  • run_status=3 — ранее вы могли удалить оформление рекламы с помощью этого поля и значения. Поскольку из-за этого возникали проблемы, мы переименовали run_status в status, а значение — из Int в значение String DELETED. Чтобы удалить оформление рекламы, воспользуйтесь status=DELETED.

  • Поле COVER_PHOTO_ID из GET в эндпойнтах оформления {creative_id} и {ad_account_id}/adcreatives упразднено. Оно редко использовалось и было предназначено только для внутреннего ограниченного применения.

  • image_url или image_hash — теперь вы можете задать только одно из этих значений в video_data для object_story_spec оформления рекламы. См. справку по оформлению рекламы.

  • OBJECT_INSTAGRAM_ID из GET упразднено из эндпойнтов оформления, включая {creative_id} и AD_ACCOUNT_ID/adcreatives. Это поле было предназначено только для внутреннего использования.

  • В версии 2.8 и более ранних версиях поле instagram_story_id использовалось для получения ID публикаций в Instagram в оформлении рекламы. Если вы применяли это поле, когда задавали оформление рекламы, мы выдавали исключение, но игнорировали этот параметр и возвращали результаты с instagram_story_id. При использовании этого отклика возникала ошибка. Чтобы устранить эту проблему, мы переименовали instagram_story_id в effective_instagram_story_id, и теперь вам не следует использовать это поле для настройки оформления рекламы.

  • Тип отклика spent, today_spent и yesterday_spent для всех рекламных объектов изменен с Integer на String. Это влияет на кампании, группы объявлений и отдельные объявления.

Динамическая реклама

  • Идентичные группы продуктов не поддерживаются — мы больше не разрешаем добавлять в один каталог идентичные группы продуктов. При попытке создать идентичную группу продуктов наш API вернет FacebookApiException с кодом 10803, содержащим ID такой же группы продуктов.

  • quoted_fields в POST /{product_feed_id} больше не используется. В версии 2.6 мы удалили quoted_fields из POST /{product_feed_id/product_feeds}. Это поле было связано с ним, и теперь мы его также удалили.

  • Эндпойнт POST {catalog-id}/batch теперь возвращает STRING. Мы внесли это изменение, чтобы лучше адаптировать каталоги продуктов для динамической рекламы.

  • Сбой обновлений аудитории — если вы попытаетесь обновить аудиторию динамической рекламы, запрос вернет ошибку. Чтобы внести эти изменения, нужно будет удалить аудиторию, связанную с этой динамической рекламой, и создать новую. См. разделы Динамическая реклама, аудитории и Индивидуально настроенные аудитории

  • template_url_spec заменяет template_url. Это позволяет вам отслеживать клики и применять в рекламе URL в контексте места, а не только URL из каталога продуктов. Например, в рекламу можно включить выбранные пользователем даты заезда и выезда. См. Динамическая реклама, управление рекламой.

Сигналы и таргетинг

  • Переименование источников событий — раньше при создании или запросе индивидуально настроенных конверсий нужно было использовать поля pixel_id, pixel_rule и pixel_aggregation_rule. Мы изменили названия этих полей, поскольку теперь мы также можем получать данные офлайн-конверсий и индивидуально настроенных конверсий из приложений. Теперь эти поля называются event_source_id, rule и aggregation_rule.

  • Пиксель отслеживания конверсий — упразднен 15 февраля 2017 г. Вместе с ним мы удалили все границы контекста и узлы, необходимые для создания, обновления, чтения или ссылки на пиксель отслеживания конверсий, из всех версий API.

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

  • Поддержка delivery_estimate — мы внесли изменения в раздел приблизительного охвата с учетом недавно запущенного delivery_estimate:

    • Поле bid_estimations удалено из эндпойнта /reach_estimates. Все его документированные функции перенесены в /delivery_estimate.

    • Поле /AD_ID/reachestimate упразднено. Чтобы получить эту информацию, используйте /ADSET_ID/delivery_estimate.

    • Поле data удалено.

Статистика

  • Упраздненные элементы в date_preset — мы упразднили ряд значений date_preset и заменили их другими. Новые значения лучше соответствуют задачам рекламодателей и больше не включают данные за нынешний день. Например, если запрос отправлен 8 февраля и в нем указан диапазон дат «последние 7 дней», в отклике не будет данных за 8 февраля — только данные за период с 1 февраля по 7 февраля 23:59, включительно. Упразднены следующие значения:

    • last_3_days, заменено на last_3d;

    • last_7_days, заменено на last_7d;

    • last_14_days, заменено на last_14d;

    • last_28_days, заменено на last_28d;

    • last_30_days, заменено на last_30d;

    • last_90_days, заменено на last_90d;

    • last_week, заменено на last_week_sun_sat и last_week_mon_sun;

    • this_week, заменено на this_week_sun_today и this_week_mon_today;

    • значение last_3_months упразднено.

    • В версии 2.8 и более ранних версиях поддерживаются и новые, и старые значения.

  • date_preset по умолчанию — при отправке в API Insights запросов без поля date_preset мы по умолчанию использовали значение last_30_days, которое включает действия с сегодняшнего дня, с 12:00 по часовому поясу рекламного аккаунта. В версии 2.9 мы по умолчанию используем значение last_30d. Оно включает последние 30 дней, до 23:59 прошлого вечера, в часовом поясе вашего аккаунта, и не включает сегодняшний день.

  • Поле video_complete_watched_actions упразднено. Оно содержало ту же информацию, что и video_30_sec_watched_actions.

  • unique_impression и unique_social_impressions исключены. Используйте вместо них reach и social_reach.

  • Метрики newsfeed_clicks, newsfeed_impressions, newsfeed_avg_position, video_avg_sec_watched_actions и video_avg_pct_watched_actions упразднены как устаревшие.

  • В action_type: упразднены follow, gift_sale, video_play и vote.

  • Доступ к click_to_play_video теперь можно получить в разбивке action_video_type.

  • Из API Insights исключено поле разбивки placement, которое содержало данные о показе. В версии 2.9 поддерживается только ["publisher_platform", "platform_position"]. В версии 2.8 поддерживаются разбивки ["placement"] и ["publisher_platform", "platform_position"].

  • attribution_spec — ранее в API Insights для отображения данных об окнах атрибуции для кликабельности и конверсий после просмотра использовались два разных поля. Теперь для настройки любого из этих значений следует использовать attribution_spec. Настройка attribution_spec заменяет любые существующие настройки. Если вы настроили кликабельность и конверсии после просмотра, то при выборе для параметра attribution_spec значения event_type = CLICK_THROUGH будет удалена только атрибуция конверсий после просмотра.