成效分析 API

提供单一且一致的接口，便于检索广告统计数据。

细分数据 — 分组结果
操作细分数据 — 了解操作细分数据返回的响应。
异步作业 — 针对有大量结果的请求使用异步作业
限制和最佳实践 — 调用限制、筛选和最佳实践。

您必须先设置广告以追踪您关注的指标，之后才能获得广告成效数据。如要追踪相关指标，您可使用网址标签、Meta Pixel 像素代码，以及转化 API。

iOS 14.5 更新

为了响应 Apple 的新政策，我们宣布了一些重大变更，这些变更将影响统计时间窗。

要进一步了解关于 Apple iOS 14.5 的要求将如何影响 Facebook 广告，请访问我们的 Business 帮助中心文章和更新日志：

受影响的端点

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"
    }
  }
}

若您无权在所请求的层级访问所有广告对象，则成效分析调用将不会返回任何数据。例如，虽然您请求的是 level 设为 ad 的成效分析，但是若您无权访问此广告帐户中的一个或多个广告对象，此 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 Business 帮助中心 > 统计时间范围简介。我们衡量发生转化事件时的操作，并以 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，无论广告是处于已删除还是已归档状态，其均在统计范围内。另请参阅存储和检索广告对象最佳实践。

但是，如果您通过筛选查询，则状态筛选会默认应用为仅返回“Active”状态的对象。因此，父节点的总统计数据可能大于子节点的统计数据。

但您可以通过提供额外的 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 或异步请求中，您可能收到提示超时的错误消息。对于异步请求，最多可能需要一小时才能完成（包括重试操作在内）。例如，如果您发出查询命令，尝试获取多个广告层级对象的大量数据，这可能需要很长时间。

建议

有关查询失败的标准，目前尚无明确限制。在查询超时的情况下，尝试加入日期范围等筛选条件，将查询细分为更小的查询。
独立指标的计算需要耗费许多时间。尝试在单独的调用命令中查询独立指标，从而改善非独立指标的查询表现。

流量限制

Meta 成效分析 API 会利用流量限制，确保为所有合作伙伴提供优质的报告体验。如需更多信息和建议，请参阅成效分析 API 的限制和最佳实践文档。

与广告管理工具的差异

API 的默认行为不同于广告管理工具中的默认行为。如需观察与广告管理工具相同的行为，请将字段 use_account_attribution_setting 设为 true。

详细了解

上方未列出的任何端点即不在此 API 的范围内。如果您计划在解决方案中添加来自 Meta 的报告，请参阅 Meta 开放平台条款和市场营销 API 开发者政策。