Версия 2.11

API Marketing

Выпуск 7 ноября 2017 г. | Публикация в блоге

• Новые функции
• Важные изменения
• Упраздненные элементы
• Элементы, упраздняемые в ближайшее время

Новые функции

Новый дизайн API Business Manager

У нас появилась новая форма отношений для клиентов и агентств. Кроме того, раньше не использовался объект user. Все запросы доступа и приглашения для компании и ее ресурсов обрабатывались через bid/userpermissions, что снижало производительность. Вот некоторые важные нововведения в новом API:

• Пользователи внутри компаний. Новый объект User привязан к конкретной компании, с которой также связаны его разрешения. Пользователи могут управлять свои профилем, разрешениями и доступом к объектам, связанным с этой компанией.
• Приглашения. Предложите людям доступ к компании через новые эндпойнты. Проверяйте и обновляйте статус отправленных приглашений в этих эндпойнтах.
• Категории объектов. Разделите разные типы объектов по категориям и используйте разные эндпойнты для каждой из них. Это упрощает пейджинацию результатов при чтении объектов и повышает производительность при управлении большим массивом объектов компании. Мы добавили несколько новых эндпойнтов.

Доступ к пользователям в компании:

• BUSINESS_ID/business_users
• BUSINESS_ID/system_users
• BUSINESS_ID/pending_users

Доступ к объектам, назначенным пользователям:

• BUSINESS_USER_ID/assigned_pages
• BUSINESS_USER_ID/assigned_ad_accounts
• BUSINESS_USER_ID/assigned_product_catalogs
• SYSTEM_USER_ID/assigned_pages
• SYSTEM_USER_ID/assigned_ad_accounts
• SYSTEM_USER_ID/assigned_product_catalogs
• PENDING_USER_ID/assigned_pages
• PENDING_USER_ID/assigned_ad_accounts
• PENDING_USER_ID/assigned_product_catalogs

Доступ к Страницам компании:

• BUSINESS_ID/owned_pages — получить список Страниц, принадлежащих компании.
• BUSINESS_ID/client_pages — получить список Страниц, принадлежащих клиентам компании.
• BUSINESS_ID/pending_owned_pages — получить список Страниц, принадлежащих компании и ожидающих подтверждения.
• BUSINESS_ID/pending_client_pages — получить список Страниц, принадлежащих клиентам компании и ожидающих подтверждения.

Доступ к рекламным аккаунтам компании:

• BUSINESS_ID/owned_ad_accounts — получить список рекламных аккаунтов, принадлежащих компании.
• BUSINESS_ID/client_ad_accounts — получить спи��ок рекламных аккаунтов, принадлежащих клиентам компании.
• BUSINESS_ID/pending_owned_ad_accounts — получить список рекламных аккаунтов, принадлежащих компании и ожидающих подтверждения.
• BUSINESS_ID/pending_client_ad_accounts — получить список рекламных аккаунтов, принадлежащих клиентам компании и ожидающих подтверждения.

Доступ к каталогам продуктов компании:

• BUSINESS_ID/owned_product_catalogs — получить список каталогов продуктов, принадлежащих компании.
• BUSINESS_ID/client_product_catalogs — получить список каталогов продуктов, принадлежащих клиентам компании.

Доступ к приложениям компании:

• BUSINESS_ID/owned_apps — получить список приложений, принадлежащих компании.
• BUSINESS_ID/client_apps — получить список приложений, принадлежащих клиентам компании.
• BUSINESS_ID/pending_client_apps — получить список приложений, принадлежащих клиентам компании и ожидающих подтверждения.

Для получения дополнительной информации см. статьи API Business Manager, Business Manager: системный пользователь, API Business Asset Management и API Business Manager: рекомендации.

Местоположение в режиме реального времени в рекламе с кольцевой галереей

Теперь вы можете создавать рекламу с кольцевой галереей с вложением, отображающим местоположения в реальном времени. Добавлены варианты type=REALTIME и location_source_id = PAGE_ID в place_data для AD_CREATIVE_ID/object_story_spec. Они доступны для поля object_story_spec в следующих объектах:

• POST /AD_ACCOUNT_ID/adcreatives
• GET CREATIVE_ID

Посещения точек: таргетинг на географические регионы

Теперь, помимо радиуса вокруг точки, вы можете настраивать таргетинг на другие географические регионы. При создании группы объявлений с целью «Посещения точек» вам доступен параметр geo_locations в поле targeting_specs. Эта возможность доступна не всем. Обратитесь к своему представителю Facebook. Подробнее читайте в этой статье.

• В POST AD_ACCOUNT_ID/adsets доступен новый параметр.
• Поддерживаются все географические регионы, описанные в этой статье, кроме таргетинга по country_groups и типу местоположения travel_in.
• Использование цели STORE_VISITS при создании рекламы доступно не всем. Подробнее читайте в соответствующей статье.

Типы мест назначения для групп объявлений

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

• Для групп объявлений добавлен параметр destination_type.
• Доступен в /ADSET_ID.

Ключевой показатель результативности

В AD_ACCOUNT_ID/CAMPAIGN_ID добавлено новое поле kpi_type, которое указывает тип ключевого показателя результативности, который вы хотите использовать для отслеживания кампании или рекламных объектов в ней. Чтобы получить статистику по kpi_type в kpi_results, используйте следующие вызовы:

• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights

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

Важные изменения

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

• Недействительная реклама с таргетингом наright_hand_column (правый столбец). Реклама, содержащая недействительное оформление для right_hand_column (правого столбца) в AD_ACCOUNT_ID/adsets, возвращает ошибку. В видеорекламе, подборках и рекламе на холсте в качестве плейсмента нельзя указывать только right_hand_column (правый столбец). Если плейсментом является только right_hand_column (правый столбец), вы можете использовать рекламу с одним фото или кольцевой галереей.

• Изменение в GET VERSION/RF_PREDICTION_ID/pause_periods. Для упрощения обработки в ответе теперь приводится Array (массив), а не String (строка).

API Business Manager

• Переименование полей. Поле admin_system_user было переименовано в admin, а поле system_user — в employee. Это затрагивает следующие границы контекста:

  • /{business-id}/userpermissions
  • /{business-id}/system_users

Упраздненные элементы

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

Упразднена оптимизация для VIDEO_VIEWS (просмотров видео). Кампании с целью VIDEO_VIEWS больше не могут использовать CLICKS (клики), IMPRESSIONS (показы), PAGE_ENGAGEMENT (вовлеченность для Страницы), POST_ENGAGEMENT (вовлеченность для публикации )или REACH (охват) в качестве целей оптимизации.

• При создании группы объявлений с этими целями оптимизации возникает ошибка.
• При дублировании групп объявлений с целью оптимизации REACH (охват) цель автоматически заменяется на VIDEO_VIEWS (просмотры видео).
• При дублировании групп объявлений с целями CLICKS (клики), IMPRESSIONS (показы), PAGE_ENGAGEMENT (вовлеченность для Страницы) и POST_ENGAGEMENT (вовлеченность для публикации) возникает ошибка. Это связано с тем, что при создании или дублировании рекламы в существующей группе объявлений система пытается использовать те же цели оптимизации.

Это изменение затрагивает следующие границы контекста:

• POST ACCOUNT_ID/adsets
• POST AD_ACCOUNT_ID/ads
• POST CAMPAIGN_ID/copies
• POST ADSET_ID/copies
• POST AD_ID/copies

Упраздненreach (охват) в качестве optimization_goal для цели «Узнаваемость бренда». Эта цель удалена для /adset и доступна только для оптимизации для запоминаемости рекламы. Это позволяет избежать путаницы при использовании цели «Охват».

Упразднена оптимизацияBRAND_AWARENESS (узнаваемость бренда). Вместо нее используется вариант AD_RECALL_LIFT (повышение запоминаемости рекламы). Это связано с переходом на новую, более эффективную модель показа рекламы. Новая цель оптимизации поддерживает смешанные форматы оформления, например сочетание статической и видеорекламы в одной группе объявлений, и неавтоматические ставки. Оптимизация BRAND_AWARENESS (узнаваемость бренда) больше не доступна на следующих уровнях:

• POST /ADSET_ID
• GET /ADSET_ID
• POST /AD_ACCOUNT_ID/adsets

Упразднены поляfrequency_cap (ограничение частоты показов), включая lifetime_frequency_cap (ограничение на весь срок действия) и frequency_cap_reset_period (период сброса ограничения) на следующих уровнях:

• POST AD_ACCOUNT_ID/adsets
• GET /ADSET_ID
• POST /ADSET_ID

Вместо него используйте frequency_control_specs.

Для цели «Цена за действие» упразднено событие биллингаPOST_ENGAGEMENT (вовлеченность для публикации). Использовать POST_ENGAGEMENT в качестве billing_event для этой цели больше нельзя. Это позволяет лучше согласовать показ рекламы и измерение ее показателей. Это затрагивает следующий эндпойнт: /AD_SET_ID.

Статистика рекламы и измерения

Больше не используется поле video_15_sec_watched_actions на следующих уровнях:

• GET AD_ACCOUNT_ID/insights
• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights
• POST AD_ACCOUNT_ID/insights
• POST CAMPAIGN_ID/insights
• POST ADSET_ID/insights
• POST AD_ID/insights

Упразднено полеrecurrence_value (периодичность) из API Advanced Measurement. В API Atlas это поле называлось report schedule. Оно заменено на recurrence_values. Подробнее читайте в этой статье.

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

В связи с изменением дизайна API Business Manager упразднены следующие эндпойнты:

• BUSINESS_ID/userpermissions
• BUSINESS_ID/business_persona
• business_persona_id

Упразднены эндпойнты для управления объектами:

• BUSINESS_ID/pages
• BUSINESS_ID/adaccounts
• BUSINESS_ID/product_catalogs
• BUSINESS_ID/apps

Для доступа к объектам используйте BUSINESS_ID/owned_ASSET или BUSINESS_ID/client_ASSET.

Упразднены эндпойнты для управления объектами других компаний:

• BUSINESS_ID/assigned_ad_accounts
• BUSINESS_ID/assigned_pages
• BUSINESS_ID/assigned_product_catalogs

Вместо них используйте BUSINESS_USER_ID/assigned_ASSET.

Элементы, упраздняемые в ближайшее время

Эти функции будут упразднены во всех версиях API 14 ноября 2017 г.

Реклама мероприятий и реклама со ссылками

Упразднена возможность создания и редактирования рекламы мероприятий и рекламы со ссылками, если такая реклама не связана с действительной Страницей. Этот формат больше не действителен и возвращает ошибку.

Упраздненные подписи:

• Реклама мероприятий

  • Цель: EVENT_RESPONSES (ответы на приглашения)
  • Поля оформления: body, object_id
• Реклама со ссылками

  • Цель: LINK_CLICKS (клики по ссылке)
  • Поля оформления: title, body, object_url (image_file или image_hash)

Поддерживаемые подписи

• Реклама мероприятий

  • Цель: EVENT_RESPONSES (ответы на приглашения)
  • Поля оформления: object_story_id или object_story_spec
• Реклама со ссылками

  • Цель: LINK_CLICKS (клики по ссылке)
  • Поля оформления: object_story_id или object_story_spec

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