版本 2.11

推廣 API

發佈日期：2017 年 11 月 7 日 | 網誌文章

• 新功能
• 重大變更項目
• 停用項目
• 立即停用項目

新功能

企業管理平台 API 改版

我們現在有新的關係可以代表客戶和代理商。過去，我們也沒有 user；所有對企業及其資產的存取和邀請，我們都是透過 bid/userpermissions 來處理，卻產生了成效問題。全新 API 的焦點功能包括：

• 專屬於企業管理平台的用戶 - 新用戶會連結到特定企業管理平台，且擁有專屬於該企業管理平台的權限。用戶可以管理他們與該企業管理平台相關的個人檔案、權限和資產存取權。
• 邀請 - 邀請用戶透過新端點存取企業管理平台。在這些端點查看及更新用戶邀請狀態。
• 資產類別 - 將各種資產分門別類，並為每個類別提供專屬端點。這樣當您在閱讀資產時，就能更輕鬆地將結果進行分頁。此外，如果您管理上千個資產和企業管理平台，這也能減少成效問題。在這次改版中，我們新增了幾個端點。

若要在企業管理平台上存取用戶：

• 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、企業管理平台 -> 系統用戶、企業資產管理 API，以及企業管理平台 API -> 最佳操作實例。

輪播廣告 -> 即時地點

您現在可以建立輪播廣告，並加入附件來顯示即時位置。已為 AD_CREATIVE_ID/object_story_spec 在 place_data 中新增選項 type=REALTIME 和 location_source_id = PAGE_ID。 這項資料可在下列位置的 object_story_spec 欄位中取得：

• POST /AD_ACCOUNT_ID/adcreatives
• GET CREATIVE_ID

來店客流量 -> 鎖定地理位置

您現在可以鎖定某商店位置半徑範圍以外的地理區域。我們在 targeting_specs 欄位中新增了 geo_locations 參數，協助您建立目標為來店客流量的廣告組合。由於只開放給少數人使用，因此請向您的 Facebook 代表申請使用。 參閱來店客流量

• POST AD_ACCOUNT_ID/adsets 有新的選項。
• 支援目標設定規格 -> 地點中的所有地理區域，但按照 country_groups 進行鎖定以及鎖定 travel_in 地點類型則不包含在內。
• 若要建立目標為 STORE_VISITS（僅開放給少數人使用）的廣告，請參閱來店客流量

廣告組合 -> 目的地類型

這反映了廣告所連結的目的地類型，也就是用戶點擊廣告或當中呼籲字句後會前往的位置。這會為廣告組合中的所有廣告提供一致的目的地類型，這樣廣告就只會包含類型各有不同的廣告創意。請參閱廣告組合 -> 目的地類型。

• 已為廣告組合新增 destination_type
• 可於 /ADSET_ID 取得

關鍵成效指標

在 AD_ACCOUNT_ID/CAMPAIGN_ID 中新增 kpi_type 欄位，以描述您要為宣傳活動或當中廣告物件追蹤的關鍵成效指標類型。若要在 kpi_results 中按照 kpi_type 查看洞察報告，請進行以下調用：

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

詳情請參閱廣告宣傳活動 -> 參考資料。

重大變更項目

廣告管理

• 將廣告目標設定判為無效right_hand_column - 鎖定這個位置，但在 AD_ACCOUNT_ID/adsets 上的 right_hand_column 有無效廣告創意的廣告會傳回錯誤。我們不允許格式為影片、焦點系列或全螢幕展示的僅限 right_hand_column 版位。如果是僅限 right_hand_column 版位，您只能使用單一圖像和輪播格式。

• 已變更GET VERSION/RF_PREDICTION_ID/pause_periods - 立即傳回 Array 而非 String，以便進行處理。

企業管理平台 API

• 已改名的欄位 — 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。這個欄位在 Atlas API 下又稱舉報時間表，目前已換成 recurrence_values。請參閱進階衡量方式 -> 舉報時間表。

企業管理平台

在企業管理平台 API 改版時已停用端點：

• 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 版本，且會在 2017 年 11 月 14 日生效。

活動廣告和連結廣告

已停用活動廣告或連結廣告（未連結有效專頁）的建立和編輯功能。下列格式已經失效，且會傳回錯誤。

即將停用的簽章：

• 活動廣告

  • 目標：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

您先前建立的現有活動廣告和連結廣告仍會繼續刊登，但在這項變更生效後，您就無法修改廣告創意或新建廣告，否則會收到錯誤。請參閱活動和本地廣告以及廣告 -> 參考資料。