广告数据报表

约 1297 字大约 4 分钟

此接口用于获取引力后台广告报表页数据,包括媒体消耗、产品后向回收等数据指标,具体可以参考【应答参数指标说明】

数据口径

  1. 曝光归因口径:将事件的时间归因到该用户有效触点广告的曝光时间上。适合场景:首日 ROI,24 小时 ROI 等 ROI 追踪等
  2. 行为发生口径:事件发生的独立时间。适合场景:当日的行为发生数,上报率等

关于数据口径的更多信息,请参考这篇文章open in new window

数据更新频率

  1. 数据每 15~30 分钟更新一次;
  2. 一般行为发生口径的历史数据都不会变,除了数据有问题有校对的情况会更新历史数据;
  3. 曝光归因口径的数据会随着用户行为的发生而不断变化。

申请引力开发者应用

在正式接入本接口之前,您需要在引力后台-引力开发者open in new window页面申请引力开发者应用,申请之后,我们将在一个工作日内完成审核,审核通过之后,您的开发者应用才可以正常拉取数据。

创建好开发者应用之后,请复制app_key参数,并发送给研发同学以供后续接口调用使用。

接口限频

默认接口限频:每 10 分钟 1 次,接口限频是按开发者应用维度,即同一个app_key下限频共用同一套频次统计。如果开发者绑定应用过多,导致频繁触发限频,请联系引力运营评估后提升限频等级。

接口信息

请求地址

https://backend.gravity-engine.com/openapi/api/v1/report/combo_sql/open in new window

请求方法

POST

字段类型描述
Authorizationstring具体如何生成,请参考【签名生成】

body 请求参数

字段必填参数类型描述
date_listYstring[]起始日期数组,格式 YYYY-MM-DD,举例: ["2023-08-14","2023-08-19"]
metrics_listYstring[]指定需要的指标名称,可参考应答参数返回的消耗指标字段,应答参数指标说明,参考这个文件open in new window
dims_listYstring[]分组条件,支持多种分组条件,具体详见【分组组合规则】
statistics_caliberYstring数据口径:user_activated_time为曝光归因口径,behavior_occurred_time为行为发生口径
decimal_pointYnumber数据精度,可选值为:24,表示返回的数据小数点精度值
roi_versionNnumberROI 精准模型,可选值为:12,传 2 表示启用 ROI 精准模型,默认为 1,传 1 表示关闭 ROI 精准模型
app_idYnumber查询的应用引力 ID,可以在引力后台-应用管理open in new window页面获取
filteringNFilterObject具体参见 【FilterObject】
signYstring签名,详情请参考【签名生成】

FilterObject

字段必填参数类型描述
ad_platform_listNstring[]广告平台枚举值,具体详见广告平台枚举
channel_listNstring[]渠道列表,例如['xiaomi', 'huawei']
version_listNnumber[]版本列表,例如[123, 125]
turbo_promoted_object_id_listNstring[]引力推广活动 ID 列表

应答参数指标说明

请参考这个文件open in new window中的说明。

其他信息

分组规则

引力支持同时根据多个维度来聚合查询数据:

字段分组聚合维度
date日期
ad_platform媒体
advertiser_id账户
gid计划
aid广告
channel渠道
os_platform设备类型
operator优化师
turbo_promoted_object_id推广活动
csite版位
dept部门

但是需要遵循以下互斥规则,标 ❌ 的两个维度不可以同时查询,否则会报错或者数据不准确:

字段日期媒体账户计划广告渠道设备类型优化师推广活动版位部门
日期-
媒体-
账户-
计划-
广告-
渠道-
设备类型-
优化师-
推广活动-
版位-
部门-

请求示例

curl:

POST http://localhost:8000/openapi/api/v1/report/combo_sql/
Content-Type: application/json
Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcHBfa2V5IjoiMWMyOGU2MDNlNzE2NGNiYWFjZWEwMGU5ODkxNTNhNGQifQ.ZaVNUeFdKUJG7cRXorxaupDDCk9XAII-aV68yCFPmtc

{
  "date_list": [
    "2023-09-12",
    "2023-09-13"
  ],
  "metrics_list": ["AdCost","AppActivateStandard","AppROI"],
  "dims_list": ["date","advertiser_id"],
  "statistics_caliber": "user_activated_time",
  "decimal_point": 4,
  "app_id": 17214059,
  "filtering": {
    "ad_platform_list": [],
    "channel_list": [],
    "version_list": [],
    "turbo_promoted_object_id_list": []
  },
  "sign": "adab8bac98c2f639a94b4b9733249513"
}

应答示例

{
  "data": {
    "columns": ["AdCost", "AppActivateStandard", "AppROI"],
    "items": [
      {
        "date": "2023-09-12",
        "AdCost": 192448.89,
        "AppROI": 0.14
      },
      {
        "date": "2023-09-13",
        "AdCost": 1000.89,
        "AppROI": 0.16
      }
    ],
    "total": [
      {
        "AdCost": 193448.89,
        "AppROI": 0.15
      }
    ],
    "tips": {
      "平台_消耗": "总花费(无法拆分设备类型)",
      "标准_激活数": "引力引擎收集到的标准全量激活数",
      "总ROI": "(总收入-提现金额)/平台_消耗"
    },
    "static": [
      "日期",
      "渠道",
      "推广活动ID",
      "推广活动名称",
      "设备类型",
      "优化师",
      "设计师",
      "广告平台",
      "广告主ID",
      "广告主名称",
      "广告计划ID",
      "版位",
      "广告ID",
      "广告名称",
      "广告状态",
      "广告创意ID",
      "广告创意名称",
      "部门"
    ]
  },
  "extra": {
    "error": "",
    "request_id": "cfd6772848d440828875844bfce3db80"
  },
  "code": 0,
  "msg": "成功"
}