洞察報告 API

提供單一且一致的介面，以用於檢索廣告統計資料。

資料細節：分組顯示結果
動作資料細節：了解來自動作資料細節的回應。
非同步工作：若是包含大量結果的要求，請使用非同步工作
限制和最佳操作實例：呼叫限制、過濾和最佳操作實例。

在可以取得有關廣告成效的資料前，請先設定好廣告，以便追蹤您想了解的衡量數據。為此，您可使用網址標籤、Meta 像素及轉換 API。

iOS 14.5 更新項目

為了回應 Apple 的新政策，我們宣佈了一些重大變更，而這些變更將影響歸因期。

若要進一步了解 Apple iOS 14.5 的要求將如何影響 Facebook 廣告服務，請瀏覽我們的企業商家幫助中心文章及變更記錄：

受影響的端點

GET /{ad-account-id}/insights
GET /{ad-id}/insights
GET /{ad-set-id}/insights
GET /{campaign-id}/insights
POST /{ad-account-id}/insights
POST /{ad-id}/insights
POST /{ad-set-id}/insights
POST /{campaign-id}/insights

準備工作

您將需要：

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"

若要了解詳情，請參閱廣告洞察報告參考資料。

執行呼叫

洞察報告 API 可在任何廣告物件用作為關係連線。

API 方法
`act_<AD_ACCOUNT_ID>/insights`
`<CAMPAIGN_ID>/insights`
`<ADSET_ID>/insights`
`<AD_ID>/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"
    }
  }
}

如果您無法在要求的級別存取所有的廣告物件，洞察報告呼叫將不會傳回任何資料。舉例來說，當您以設定為 ad 的 level 要求獲取洞察報告時，如果您無法存取該廣告帳戶內的一個或多個廣告物件，此 API 呼叫就會傳回權限錯誤。

歸因期

適用於 iOS 14 及以上版本的更新項目

如果未設定 action_attribution_windows，預設歸因值將為 7d_click 和 1d_view。一旦開始執行，28 天內瀏覽次數將不再可用，並會傳回空白數據。
若是歸因期值為 28 天的已停用舊版廣告，我們將傳回此數據。
若是預設或帳戶級別的歸因期，此值將設定為執行後 7 天。
use_account_attribution_setting 欄位已停用。我們會將此類要求切換為 action_attribution_windows 預設值 7d_click 及 1d_view。

請瀏覽重大變更的變更記錄，進一步了解因 iOS 14 而作出的變更。

轉換歸因期是指我們將事件歸因至 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，不論廣告是否處於已刪除或已封存狀態。另請參閱儲存並檢索廣告物件最佳操作實例。

不過，如果您使用篩選條件查詢，系統會預設套用狀態篩選條件，以僅傳回狀態為「使用中」的物件。因此，母節點的統計資料總計可能會大於子節點的統計資料總計。

不過，您可以輸入額外的 filtering 參數，從 ARCHIVED 物件的母節點取得該物件的統計資料。

要求

若要逐一取得廣告帳戶內所有 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"
    }
  }
}

已刪除物件的洞察報告

若要查詢已刪除物件的洞察報告，您可以使用該物件的編號或使用 ad.effective_status 篩選條件。

要求

舉例來說，如果您有廣告組合編號：

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 或非同步要求中，您可能會收到逾時錯誤。如果是非同步要求，最多可能需要 1 小時才能完成要求（包含重試動作在內）。舉例來說，如果您提出的查詢嘗試擷取許多廣告級別物件的大量資料，可能就需要這麼久的時間才能完成。

建議

查詢並沒有明確的失敗次數限制。如果發生逾時，建議您將查詢細分，方法是加入日期範圍等篩選條件。
不重複衡量數據需要大量的計算時間。建議您在個別的呼叫中查詢不重複衡量數據，以便改善非不重複衡量數據的成效。

限速

Meta 洞察報告 API 會實施限速，以確保所有合作夥伴都能獲得最佳的分析報告體驗。如需詳細資訊和更多建議，請參閱我們的洞察報告 API 限制和最佳操作實例。

廣告管理員的差異

API 與廣告管理員兩者的預設行為並不相同。如要觀察到與廣告管理員相同的行為，請將 use_account_attribution_setting 欄位設定為 true。

了解詳情

上方未列出的端點即不在此 API 的範圍內。如果您計劃在解決方案中加入來自 Meta 的報告，請參閱 Meta 平台使用條款及推廣 API 開發人員政策。