菜单

受众服务接入

名词解释

名词
释义
受众 即用户的集合，通常是通过规则圈选等方式从全量用户中选择出满足条件的用户合集来构建的。
受众额度 每创建一个受众就会使用一个受众额度，额度使用完则不能再创建受众，额度可以通过删除受众释放。
T+1 规则受众 / 批受众

此类型的受众计算方式为离线计算，计算的数据范围截止到计算当天前一天的数据，即当天产生的数据不会纳入计算范围。

 

此受众有两种计算时间设置方式：

  • 如果受众计算时间选择定时 - 单次，则受众计算时间为设定的时间，执行一次计算后计算结果不再更新；
  • 如果受众计算时间选择定时 - 重复，则受众计算会按配置周期性执行，每次到达设定的执行时间都会执行一次计算和结果更新。
实时受众

此类型的受众计算为实时计算实时更新，计算的数据范围截止到当前神策能获取到的最新数据，满足该计算条件的用户会实时进入受众，进入后不满足条件的用户会实时退出该受众。
即时受众 在实时受众的基础上，对于用户行为事件通过更快速的数据链路来处理，达到更高时效（秒级）的计算结果。
业务系统 指第三方开发者开发的相关系统，任何需要接入神策受众引擎的系统都可称为业务系统，比如 A 公司的 SCRM 系统、B 公司的 webhook 推送系统、C 公司的 CDP 系统等等。
预估受众量 基于当前的受众筛选条件进行一次离线受众计算并给出当前满足该规则的受众量。
预估受众计算范围（抽样计算） 基于当前的受众筛选条件预估出计算中可能会涉及到的用户备选集的用户量。
人群包 受众的计算结果也可称作人群包，和受众的意思等价。
受众业务 id 受众的唯一标识 id，由第三方开发者定义，在创建受众时传入。
受众计算时间
（非实时受众）
  • 立即
    立刻开始计算受众，计算只调度一次，不会每日例行调度
  • 定时 - 单次
    按设置的时间计算受众，计算只调度一次，不会每日例行调度
  • 定时 - 重复
    在选定的日期范围内，按设置的时间计算受众，每日例行调度

接口文档列表

元数据接口列表

在线接口列表

流程说明

在实际使用受众引擎时，需要按照一定的流程使用，确保使用的流程正确才能达到想要的效果。

在实际使用中，受众引擎与业务系统之间存在多处交互的地方：

  • 业务系统需要发起受众的预估、创建或者属性的订阅等工作；
  • 在受众开始计算、计算完成、同步完成，以及属性同步完成等时机会通过通知的方式通知到业务系统；
  • 业务系统在受众或者属性同步完成的时候，进行属性在线查询和受众在线判定等。

 

通知

通知接口配置

通知接口按照项目设置，一个项目只能设置一个通知接口。

接口类型

method

Path

离线 /offline

POST

/api/v3/focus/v1/express-notify/set

请求示例

curl -X 'POST' \
  'http://{offline-domain}/api/v3/focus/v1/express-notify/set' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \ 
  -d '{
      "notify_config": {
          "notify_id": "test_notify",
          "notify_address": "http://10.129.17.208:8095/audience/notify_no_auth",
          "auth_type": "API_KEY",
          "auth_configs": [
              {
                  "key": "key1",
                  "value": "value1"
              },
              {
                  "key": "key2",
                  "value": "value2"
              }
          ],
          "send_mode": "RETRYABLE"
      }
  }'

参数说明

参数位置

参数

是否必传

参数说明

body

notify_id

必传

有业务方指定的一个业务 id，同一个项目内的 notify_id 不能重复。

notify_address

必传

即通知的 API 接收地址（回调地址）。

auth_type

必传

回调接口的认证方式，取值包括：

  • NO_AUTH_UNSPECIFIED：无需认证，此时配置的 auth_configs 无效；

  • API_KEY：配置 api-key 认证，此时需要配置 auth_configs。

auth_configs

非必传

配置的认证 key-value 键值对，该配置会放在 HTTP Header 里面回调业务系统接口。

send_mode

非必传

发送模式，默认值为 ONLY_ONCE_UNSPECIFIED，取值包括：

  • ONLY_ONCE_UNSPECIFIED：只发送一次，发送失败后不再重试；

  • RETRYABLE：可重试发送，发送失败后会自动重试（默认重试 60 次，每次间隔 2 秒）。

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "5cb25c615a524faf805723db827c72fa",
    "data": {},
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明

data

必返

调用成功后，code 为 SUCCESS，data 不返回数据。

通知接口配置查询

在配置之前或者配置之后，可以进行通知接口配置查询，以便查看现有的通知接口是否符合规则。

该接口获取的是当前项目的通知设置。

接口类型

method

Path

离线 /offline

GET

/api/v3/focus/v1/express-notify/get

请求示例

curl -X 'GET' \
 'http://{offline-domain}/api/v3/focus/v1/express-notify/get' \
 -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
 -H 'X-Organization-Id: org-sep-3164dp4' \
 -H 'sensorsdata-project: default'

参数说明

无

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "5cb25c615a524faf805723db827c72fa",
    "data": {
        "notify_config": {
            "id": 3,
            "notify_id": "test_notify",
            "project_ref_id": 2,
            "notify_address": "http://{host}:8095/audience/notify_no_auth",
            "auth_type": "NO_AUTH_UNSPECIFIED",
            "auth_configs": [],
            "send_mode": "RETRYABLE"
        }
    },
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明

data

必返

参数含义同通知接口配置

通知接口配置清除

如果不想继续接收通知，则可以通过清除接口清除当前项目的通知配置。

接口类型

method

Path

离线 /offline

POST

/api/v3/focus/v1/express-notify/delete

请求示例

curl -X 'POST' \
 'http://{offline-domain}/api/v3/focus/v1/express-notify/delete' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'sensorsdata-project: default'

参数说明

无

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "5cb25c615a524faf805723db827c72fa",
    "data": {},
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明

data

必返

调用成功后，code 为 SUCCESS，data 不返回数据。

调用成功后，系统将不再发送当前项目的通知。

通知内容解析

注册通知接口以后，已订阅的属性状态会及时通过通知的形式发送到业务系统。

协议：HTTP

请求方式：POST

Content-Type: application/json

请求示例

curl -X 'POST' \
  'http://{offline-domain}/{path} \
  -H 'Content-Type: application/json' \
  -H '{key1}: {value1}' \
  -H '{key2}: {value2}' \
  -d '{
     ...// 通知内容
  }'

通知内容

通知状态（type_code）
状态含义
通知示例
BATCH_AUDIENCE_COMPUTE_SUCCESS T+1 受众（批受众）计算成功。 
{
    "type": 2001,
    "type_code": "BATCH_AUDIENCE_COMPUTE_SUCCESS",
    "notify_time": "1687937204745",
    "context_id":"context_test_session_xxxxxxx01",
    "batch_audience_info":{
        "audience_biz_id": "audience_biz_xxxxxx"
        "user_group_name": "user_group_xxx",
        "base_time": "1687937200000",
        "start_computing_time": "1687937204745",
        "end_computing_time": "1687937205102",
        "sync_finish_time": "1687937205102",
        "support_abilities": ["CHECK_ENTITY_EXIST_IN_AUDIENCE", "PULL_AUDIENCE"]
    }
}
BATCH_AUDIENCE_COMPUTE_FAILED T+1 受众（批受众）计算失败。 
{
    "type": 2002,
    "type_code": "BATCH_AUDIENCE_COMPUTE_FAILED",
    "notify_time": "1687937204745",
    "context_id":"context_test_session_xxxxxxx01",
    "batch_audience_info":{
        "audience_biz_id": "audience_biz_xxxxxx"
        "user_group_name": "user_group_xxx",
        "base_time": "1687937200000",
        "support_abilities": ["CHECK_ENTITY_EXIST_IN_AUDIENCE", "PULL_AUDIENCE"]
    },
    "error_notify_content": {
        "error_msg": "xx原因导致失败"
    }
}
BATCH_AUDIENCE_QUERY_READY T+1 受众同步成功，此时可用于在线判定 
{
    "type": 2003,
    "type_code": "BATCH_AUDIENCE_QUERY_READY",
    "notify_time": "1687937204745",
    "context_id":"context_test_session_xxxxxxx01",
    "batch_audience_info":{
        "audience_biz_id": "audience_biz_xxxxxx"
        "user_group_name": "user_group_xxx",
        "base_time": "1687937200000",
        "start_computing_time": "1687937204745",
        "end_computing_time": "1687937205102",
        "sync_finish_time": "1687937205102",
        "support_abilities": ["CHECK_ENTITY_EXIST_IN_AUDIENCE", "PULL_AUDIENCE"]
    }
}
BATCH_AUDIENCE_SYNC_FAILED T+1 受众同步失败，此时不可用于在线判定 
{
    "type": 2004,
    "type_code": "BATCH_AUDIENCE_SYNC_FAILED",
    "notify_time": "1687937204745",
    "context_id":"context_test_session_xxxxxxx01",
    "batch_audience_info":{
        "audience_biz_id": "audience_biz_xxxxxx"
        "user_group_name": "user_group_xxx",
        "base_time": "1687937200000",
        "support_abilities": ["CHECK_ENTITY_EXIST_IN_AUDIENCE", "PULL_AUDIENCE"]
    },
    "error_notify_content": {
        "error_msg": "xx原因导致失败"
    }
}
REALTIME_AUDIENCE_COMPUTE_FAILED 实时受众计算失败，此时不可用于在线判定 
{
    "type": 3001,
    "type_code": "REALTIME_AUDIENCE_COMPUTE_FAILED",
    "notify_time": "1687937204745",
    "context_id":"context_test_session_xxxxxxx01",
    "realtime_audience_info":{
        "audience_biz_id": "audience_biz_xxxxxx",
        "support_abilities": ["CHECK_ENTITY_EXIST_IN_AUDIENCE"]
    },
    "error_notify_content": {
        "error_msg": "xx原因导致失败"
    }
}
REALTIME_AUDIENCE_QUERY_READY 实时受众计算成功，此时可用于在线判定 
{
    "type": 3002,
    "type_code": "REALTIME_AUDIENCE_QUERY_READY",
    "notify_time": "1687937204745",
    "context_id":"context_test_session_xxxxxxx01",
    "realtime_audience_info":{
        "audience_biz_id": "audience_biz_xxxxxx",
        "start_computing_time": "1687937204745",
        "sync_finish_time": "1687937204745",
        "support_abilities": ["CHECK_ENTITY_EXIST_IN_AUDIENCE"]
    }
}

受众创建

受众创建使用前端 H5 接入，暂不支持 API 方式创建受众。

业务系统需要在业务前端嵌入神策 H5 的方式来进行受众创建，流程如下：

通过前端 H5 iframe 接入

业务系统内嵌入的 iframe 的 url 格式为：

http://{offline-domain}/sf/h5/audience?project=default&audience_biz_id=test_1&mode=create&language=zh-cn

其中，host 与离线接口的 host 保持一致。

在请求 url 时还需要一些参数：

参数

是否必传

参数说明
project 必传

需要调用的项目英文名称，如 default /production
mode 非必传 标识是创建受众还是查看受众配置，创建时传入 create，查看受众配置时传入 view，默认为 create
audience_biz_id 必传 受众业务 ID，由业务方生成且不可重复，格式支持大小写字母、数字和下划线组合，最大长度为 64
language 非必传 多语言设置，支持中文简体（zh-cn）、中文繁体（zh-tw）、英语（en-us）、日语（ja）和泰语（th），默认为 zh-cn

使用 iframe 的时候有一些注意事项：

  • 受 Cookie Same-Site Lax 限制，需要业务系统的主域名与离线接口（神策系统）的 host 保持一致，比如：
    • 神策系统的域名为 xxx.example.com，则需要业务系统与神策的 example.com 的部分与神策保持一致，否则可能会出现跨域问题等报错。
  • 如果业务系统内嵌的 iframe 需要对接业务系统的 OAuth 认证，则在打开 iframe 的时候需要在 iframe 内部弹出 OAuth 登录，这种情况下也需要如上保持 host 配置一致。

前端 H5 接收创建成功通知

受众创建成功后会使用 postMessage 向业务系统前端发送创建成功通知，业务系统可使用 window.addEventListener ('message', event => {}) 方法接收消息。

发送数据示例：

{
    "key": "SENSORS_SF_AUDIENCE_SEND", // 消息来源标识
    "value": {
        "type": "CREATE_SUCCESS", // 创建成功标识
        "data": {
          "audience_biz_id": "test_1", // 受众业务 ID
          "audience_biz_name": "test1" // 受众业务名称
        },
     }
}

业务员系统接收消息代码示例：

window.addEventListener('message', event => {
  const data = event.data;
  if (data?.key === 'SENSORS_SF_AUDIENCE_SEND') {      // 触发来源为 SF 受众引擎
    if (data?.value?.type === 'CREATE_SUCCESS') {     // 创建成功后执行自己的业务逻辑
      console.log(data?.value)
    }
  }
});

注意事项：window.addEventListener ('message') 该事件应该只注册一次，若重复注册多次，会接受到多次消息。可以在业务系统页面初始化时进行监听，也可以在打开 iframe 时监听关闭 iframe 时删除监听事件。

 

受众信息查询

通过受众信息查询接口可以查询创建的受众信息。

接口类型

method

Path
离线 /offline POST /api/v3/focus/v1/express-audience-meta/rule/query

请求示例

curl -X 'POST' \
  'http://{offline-domain}/api/v3/focus/v1/express-audience-meta/rule/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-O26BiOzc2ZdUPQBbyTGulGnncUY7rFq0' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \ 
  -d '{
    "query_type": "QUERY_ALL"
  }'

或者：

curl -X 'POST' \
  'http://{offline-domain}/api/v3/focus/v1/express-audience-meta//rule/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-O26BiOzc2ZdUPQBbyTGulGnncUY7rFq0' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \  
  -d '{
    "query_type": "QUERY_BY_BIZ_ID_LIST",
    "audience_biz_ids":[
        "test_12"
    ]
  }'

参数说明

参数位置

参数

是否必传

参数说明
body query_type 必传

表示查询类型，可选择不同的查询类型：

  • QUERY_ALL：全量查询，此时会将项目下的所有受众信息一并查询；
  • QUERY_BY_BIZ_ID_LIST：根据 audience_biz_ids 来查询，需要传 audience_biz_ids 参数。
body audience_biz_ids 可选 表示需要查询的受众业务 ID，当 query_type 为 QUERY_BY_BIZ_ID_LIST 的时候，根据传入的 ids 来进行查询。

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "e546d53725b344b39f78e230f55c02fe",
    "data": {
        "rules": [
            {
                "audience_biz_id": "test_12",
                "rule_status": "ENABLE",
                "audience_data_ready": false,
                "create_time": "2023-06-27T06:18:54Z",
                "update_time": "2023-06-27T06:18:54Z",
                "support_abilities": [
                    "CHECK_ENTITY_EXIST_IN_AUDIENCE"
                ],
                "audience_biz_name": "test12",
                "audience_rule_type": "BATCH_RULE",
                "audience_batch_rule": {
                    "user_group_name": "user_group_pj2_o_1687846730155"
                }
            }
        ]
    },
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明
rules 必返 表示查询出来的各个受众 id 对应的受众信息，内部为对象列表，下面说明 rules 中的各个字段。
audience_biz_id 必返 受众业务 ID（唯一标识）
audience_biz_name 必返 受众业务名称（项目中唯一，用户自己填写的）
rule_status 必返 受众的状态，固定值 ENABLE（可用）、UNABLE（不可用）。
audience_data_ready 必返 受众数据是否就绪，受众就绪后才能做 support_abilities 中的动作。
create_time 非必返 受众创建时间
update_time 非必返 受众更新时间
support_abilities 必返

声明支持的能力，当前支持的能力如下：

  • CHECK_ENTITY_EXIST_IN_AUDIENCE：在线判断某实体是否在受众中，有该能力的受众支持进行在线判定；
  • PULL_AUDIENCE：受众可以被全量下载（仅对批受众生效）。
audience_rule_type 必返

受众的类型，不同类型的受众具有不同的能力，包括：

  • BATCH_RULE：非实时受众（T+1 受众，通过规则创建）
  • REALTIME_RULE ：实时规则受众
  • REALTIME_MARK_RULE：实时标记受众
  • BATCH_USER_GROUP_REFERENCE_RULE：非实时受众（T+1 受众，通过引用分群创建）
  • INSTANT_RULE ：即时受众（即仅显示即时事件）
audience_batch_rule 非必返 当受众类型为 BATCH_RULE 时，该字段用于获取分群名称（user_group_name）

 

受众在线判定 - 单用户多受众的命中判定

提供受众是否命中受众规则的查询，判断一个用户有没有在多个受众中。

接口类型

method

Path
在线 /online POST /api/v3/focus/v1/express-audience-online/audience-entity/exists
 

请求示例

curl -X 'POST' \
  'http://{online-domain}/api/v3/focus/v1/express-audience-online/audience-entity/exists' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-3rC3cssQ0pX6TnaOk80aHBOH8pqg3DHf' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \  
  -d '{
    "audience_biz_ids": ["9999", "ddw"],
    "audience_entity_id":{
       "entity_name": "user",
       "entity_id": {
           "int_value": "2345353434"
       },
       "identity_id_map": {
          "distinct_id": "lsj_7"
        }
      }
  }'

参数说明

参数位置

参数

是否必传

参数说明
body audience_biz_ids 必传 业务方定义的受众唯一标识列表
body audience_entity_id 必传

表示该实体的唯一标识符，比如用户实体的用户 ID。

  • entity_name 表示实体名称，不传表示 user
  • entity_id 表示实体 id（entity_id 和 identity_id_map 只需要设置一个即可）：
    • 实体 ID 目前只支持 user_id，为 int 类型，值可表示为（具体值替换为具体的实体 id）："int_value": 123
  • identity_id_map：查询的用户标识符，值为业务主键 map，key: id_name（业务 id 字段名）, value: id_value（具体的 id 值）; id_name，如 distinct_id（传用户唯一标识，可支持 IDMapping 2.0 和 IDMapping 3.0 环境）, first_id, second_id, $identity_mobile 等。例：distinct_id 为 lsj_7 表示查询 distinct_id 为 lsj_7 的用户在不在该受众中；identity_id_map 中 idm3 的属性如 $identity_login_id  需要单独执行命令订阅：sfnadmin section_id_mapping subscribe -h
  • 如果 entity_id 和 identity_id_map 同时传，则以 entity_id 为准。

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "cb932c13d2f140f9ad44e6d2c43eff1d",
    "results": {
      "9999": true,
      "ddw": false
    },
    "error_info": null
}

返回结果说明

参数

必要性

参数说明
data 必返 为 json 结构，key 表示受众的 audience_biz_id，value 表示该用户有没有命中该受众。

 

受众在线判定 - 多用户单受众的命中判定

批量判定多个用户有没有在一个受众中。

接口类型

method

Path
在线 /online POST /api/v3/focus/v1/express-audience-online/audience-entities/exists

请求示例

curl -X 'POST' \
  'http://{online-domain}/api/v3/focus/v1/express-audience-online/audience-entities/exists' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-3rC3cssQ0pX6TnaOk80aHBOH8pqg3DHf' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \  
  -d '{
    "audience_biz_id": "9999",
    "audience_entity_ids": [
      {
        "entity_name": "user",
        "entity_id": {"int_value": 123}
      },
      {
        "entity_name": "user",
        "entity_id": { "string_value": "account_xx_81672273"}
      },
      {
        "entity_name": "user",
        "identity_id_map": { "distinct_id": "account_xx_81672273"}
      }
    ]
  }'

参数说明

参数位置

参数

是否必传

参数说明
body audience_biz_id 必传 业务方定义的受众唯一标识
body audience_entity_ids 必传

表示该实体的唯一标识符，比如用户实体的用户 ID。

  • entity_name 表示实体名称，不传表示 user
  • entity_id 表示实体 id（entity_id 和 identity_id_map 只需要设置一个即可）：
    • 实体 ID 目前只支持 user_id，为 int 类型，则值可表示为（具体值替换为具体的实体 id）："int_value": 123
  • identity_id_map：查询的用户标识符，值为业务主键 map，key: id_name（业务 id 字段名）, value: id_value（具体的 id 值）; id_name，如 distinct_id（传用户唯一标识，可支持 IDMapping 2.0 和 IDMapping 3.0 环境）, first_id, second_id, $identity_mobile 等。例：distinct_id 为 lsj_7 表示查询 distinct_id 为 lsj_7 的用户在不在该受众中；identity_id_map 中 idm3 的属性如 $identity_login_id  需要单独执行命令订阅：sfnadmin section_id_mapping subscribe -h
  • 如果 entity_id 和 identity_id_map 同时传，则以 entity_id 为准。

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "cb932c13d2f140f9ad44e6d2c43eff1d",
    "results": {
      [true, false]
    },
    "error_info": null
}

返回结果说明

参数

是否bi fan

参数说明
data 必返 返回不同用户在该受众内的命中情况，bool 值的列表顺序与传入参数的 audience_eneity_ids 一致。

请注意传入参数和返回参数的顺序对应关系。

 

以上仅列举重要接口，剩余接口请参考接口手册。

上一个
OpenAPI 服务接入
下一个
属性标签订阅服务接入
最近修改: 2025-09-05