第 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

先前建立的既有活動廣告和連結廣告可繼續刊登，但這項變更一旦生效，您便無法修改這些廣告的廣告創意或建立新廣告，否則將會傳回錯誤。請參閱活動廣告和本地廣告及廣告參考資料。