用户信息报表

约 1525 字大约 5 分钟

此接口用于获取引力收集到的用户信息数据，包括用户的归因信息、基础信息、属性信息。

数据更新频率：数据分钟级更新延迟，高峰期时间可能会变长，极端情况可能会延迟 10 分钟以上；

申请引力开发者应用

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

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

接口限频

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

接口信息

请求地址

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

请求方法

POST

字段	类型	描述
Authorization	string	具体如何生成，请参考【签名生成】

body 请求参数

字段	必填	参数类型	描述
app_id	Y	number	查询的应用引力 ID，可以在引力后台-应用管理open in new window页面获取
user_filtering	Y	UserFilterObject	用户默认属性过滤，具体参见【UserFilterObject】
event_filtering	Y	EventFilterObject	付费事件属性过滤，具体参见【EventFilterObject】
order_by_list	N	OrderByObject	排序数组，具体参见【OrderByObject】
page	N	number	查询的页码，从 1 开始
page_size	N	number	单页的大小，最大支持 500
sign	Y	string	签名，详情请参考【签名生成】

UserFilterObject

用户默认属性过滤

字段	必填	参数类型	描述
create_date_list	N	string[]	用户注册时间，如["2023-03-01", "2023-03-10"]
ad_platform_list	N	string[]	广告平台枚举值，具体详见广告平台枚举
channel_list	N	string[]	渠道列表，例如`['xiaomi', 'huawei']`
version_list	N	number[]	版本列表，例如`[123, 125]`
turbo_promoted_object_id_list	N	string[]	引力推广活动 ID 列表
advertiser_id_list	N	string[]	广告账户 id 列表
gid_list	N	string[]	计划 id 列表
aid_list	N	string[]	广告 id 列表
cid_list	N	string[]	创意 id 列表
wx_openid_list	N	string[]	openid 列表
client_id_list	N	string[]	用户 clientID 列表
turbo_promoted_object_id_list	N	string[]	引力推广活动 ID 列表

EventFilterObject

付费事件属性过滤

字段	支持查询类型	参数格式	描述
postback_filtering	单选查询	PostBackItem	订单金额，具体见【PostBackItem】

PostBackItem

PostBackItem 为一个查询单元，其中

event_type 表示查询事件，事件枚举值如下

enum allEventEnum {
  activate = "激活",
  register = "注册",
  pay = "付费",
  twice = "次留",
  key_active = "关键行为",
  withdraw_iaa = "短期退订",
  create_role = "创角",
  login = "登录",
  customer_effective = "有效获客",
  wx_launch = "微信小程序调起",
  re_active = "关键页面浏览",
  retention_2d = "2日留存",
  retention_3d = "3日留存",
  retention_4d = "4日留存",
  retention_5d = "5日留存",
  retention_6d = "6日留存",
  retention_7d = "7日留存",
  retention_14d = "14日留存",
  retention_30d = "30日留存",
  service_pay_success = "服务购买成功",
  complete_order = "订单提交(非付费)",
  first_day_pay = "首日付费",
  first_pay = "首次付费",
  ad_quality = "广告变现",
  game_action = "游戏行为",
  action_valid = "有效行为",
}

status 表示回传状态，0 为未回传，1 为回传成功，2 为回传失败，3 为回传跳过

event_filtering举例如下：

查询首次付费事件状态为回传跳过的用户

{
  "event_type": "first_pay",
  "status": "1"
}

OrderByObject

如果想在查询时排序，需要传入 order_by_list 参数，其中 order_by_list 为一个数组，数组中的元素为 OrderByObject 类型，OrderByObject 中包含两个字段：

field：排序字段，支持的排序字段参考【排序指标】
sort: 排序方式，支持的排序方式有：0（升序）和 1（降序）

order_by_list 具有顺序，会优先按照第一个排序字段进行排序，如果第一个排序字段相同，则按照第二个排序字段进行排序，以此类推。

order_by_list举例如下：

优先按照付费次数降序，其次按照付费金额升序排序

[
  {
    "field": "user$pay_count",
    "sort": 1
  },
  {
    "field": "user$pay_amount_sum",
    "sort": 0
  }
]

排序指标

目前支持排序的字段如下：其中字符串按照字符串字母排序，数字按照数字大小排序，时间类型按照时间先后排序。

    "ClientID": "oeBZI5JGNRKMWpzU44KtAFSiQ7cY", // client ID
    "AdPlatform": "tencent", // // 媒体平台
    "Channel": "base_channel", // 渠道
    "Version": 1116, // 客户端版本
    "TurboPromotedObjectID": "zcnBlouhsAuihqal", // 推广活动ID
    "WXOpenID": "oeBZI5JGNRKMWpzU44KtAFSiQ7cY", // openid
    "AdvertiserID": "31355163", // 广告账户ID
    "AdAid": "11758851965", // 广告ID
    "LatestLoginDay": "20240723", // 最近登录日期
    "user$pay_amount_sum": 33200, // 用户付费总额
    "user$pay_count": 4, // 用户付费次数
    "user$pay_max_amount": 19800, // 用户付费最大金额

请求示例

curl 'https://backend.gravity-engine.com/openapi/api/v1/report/order/list/' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'accept-language: en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7' \
  -H 'authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MjE4MDc4MDYsImlhdCI6MTcyMTcyMTQwNiwiaXNzIjoicGx1dHVzIiwiZGF0YSI6eyJpZCI6MjM44jwLCJuYW1lIjoiUU1IRCIsImNpZCI6MTM1LCJlbWFpbCI6ImxpdXNoaWppYUBxdWFubWluLWdhbWUuY29tIiwiaXNfcmVnaXN0ZXIiOmZhbHNlLCJpc19za2lwIjoxfX0.-IEqB_9X0UrB9RICmuaqp7INJXry9D3lxnzyOxBlIpc' \
  -H 'content-type: application/json' \
  -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36' \
  --data-raw '{"page":1,"page_size":20,"app_id":13142548,"user_filtering":{"create_date_list":["2024-07-23","2024-07-23"]},"event_filtering":{"postback_filtering":{"event_type":"activate","status":"0"}},"property_condition":[],"order_by_list":[{"field":"user$pay_count","sort":1},{"field":"user$pay_amount_sum","sort":1},{"field":"user$city","sort":1}]}'

应答示例

{
  "data": {
    "page_info": {
      "page": 1,
      "page_size": 20,
      "total_number": 32,
      "total_page": 2
    },
    "list": [
      {
        "CreateTime": "2024-07-23 09:01:40",
        "ClientID": "oeBZI5MHOLvm-Cf8yK9X0",
        "AdPlatform": "",
        "Channel": "xxx",
        "Version": 2040,
        "TurboPromotedObjectID": "default_13142548",
        "Name": "oeBZI5MHOLvm-Cf8yK9X0",
        "WXOpenID": "oeBZI5MHOLvm-Cf8yK9X0",
        "AdvertiserID": "",
        "AdAid": "",
        "AdGid": "",
        "AdCid": "",
        "CSite": "",
        "LatestLoginDay": "20240723",
        "user$ad_24h_ltv": 0,
        "user$ad_count": 0,
        "user$ad_ltv": 0,
        "user$ad_max_ecpm": 0,
        "user$brand": "HUAWEI",
        "user$channel": "xxx",
        "user$city": "宜宾市",
        "user$country": "中国",
        "user$first_pay_time": "2024-07-23 10:06:54",
        "user$first_scene": "1055",
        "user$first_visit_time": "2024-07-23 09:53:38",
        "user$gender": "",
        "user$interstitial_ad_24_ltv": 0,
        "user$interstitial_ad_count": 0,
        "user$interstitial_ad_ltv": 0,
        "user$interstitial_ad_max_ecpm": 0,
        "user$manufacturer": "HUAWEI",
        "user$model": "NOH-AN00",
        "user$name": "",
        "user$os": "android",
        "user$pay_amount_sum": 36200,
        "user$pay_count": 13,
        "user$pay_max_amount": 9800,
        "user$province": "四川省",
        "user$reward_ad_24h_ltv": 0,
        "user$reward_ad_count": 0,
        "user$reward_ad_ltv": 0,
        "user$reward_ad_max_ecpm": 0,
        "user$ta_account_id": "",
        "user$ta_distinct_id": "",
        "re_attribute_info": null
      }
    ],
    "total": []
  },
  "extra": null,
  "code": 0,
  "msg": "成功"
}

用户信息报表

# 申请引力开发者应用

# 接口限频

# 接口信息

# 请求地址

# 请求方法

# Header

# body 请求参数

# UserFilterObject

# EventFilterObject

# PostBackItem

# OrderByObject

# 排序指标

# 请求示例

# 应答示例