广告数据报表

约 1697 字大约 6 分钟

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

数据口径

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

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

数据更新频率

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

申请引力开发者应用

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

创建好开发者应用之后,请复制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[]指定需要的指标名称,可参考应答参数返回的消耗指标字段
dims_listYstring[]分组条件,支持多种分组条件,具体详见【分组组合规则】
statistics_caliberYstring数据口径:user_activated_time为曝光归因口径,behavior_occurred_time为行为发生口径
decimal_pointYnumber数据精度,可选值为:24,表示返回的数据小数点精度值
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部门

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

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

签名生成

我们提供了以下 JavaGolangPython 版本的实例,请参照示例生成签名

TestJWT {

 @Test public void test() {

    String appKey = "your_app_key";

    HashMap<String, Object> params = Maps.newHashMap();
    params.put("date_list", Arrays.asList("2023-08-14", "2023-08-19"));
    params.put("metrics_list", Lists.newArrayList("AdCost","AppActivateStandard","AppROI"));
    params.put("dims_list", Lists.newArrayList("date","advertiser_id"));
    params.put("statistics_caliber", "user_activated_time");
    params.put("decimal_point", 4);
    params.put("app_id", 13467210);

    HashMap<String, Object> filtering = new LinkedHashMap<>(); # 保持顺序
    filtering.put("ad_platform_list", Lists.newArrayList());
    filtering.put("channel_list", Lists.newArrayList());
    filtering.put("version_list", Lists.newArrayList());
    filtering.put("turbo_promoted_object_id_list", Lists.newArrayList());

    params.put("filtering", filtering);
    params.put("sign", "");


    String sign = getSign(params, appKey);
    System.out.println(sign);
    params.put("sign", sign);

    String authorization = getAuthorization(appKey, sign);
    System.out.println(authorization);
 }


 /** * 参数加签 *
    * @param map 参数
    * @param appKey 申请的引力APPKEY
    * @return 签名 */
public String getSign(Map<String, Object> map, String appKey) {
    List<String> params = new ArrayList<>();
    for (Map.Entry<String, Object> entry : map.entrySet()) {
        if (entry.getKey().equals("sign")) {
          continue;
    }
        params.add(entry.getKey() + "=" + JSONObject.toJSONString(entry.getValue()));
    }
    Collections.sort(params);
    StringBuilder sb = new StringBuilder();
    sb.append(Joiner.on("&").join(params));
    sb.append(appKey);
    String str = sb.toString().replaceAll("\"", "");
    return Hashing.md5().newHasher().putString(str, Charsets.UTF_8).hash().toString();
 }

 /** * 请求头加签 *
 * @param appKey 申请的引力APPKEY
 * @param sign 参数加签
 * @return 请求头签名
*/ public String getAuthorization(String appKey, String sign) {
    HashMap<String, Object> payload = Maps.newHashMap();
    payload.put("app_key", appKey);
    JWTSigner jwtSigner = JWTSignerUtil.hs256(sign.getBytes());
    return JWTUtil.createToken(payload, jwtSigner);
 }
}

请求示例

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": {
    "request_id": "cfd6772848d440828875844bfce3db80",
    "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": ""
  },
  "code": 0,
  "msg": "成功"
}