菜单

实时标签服务接入

接口文档列表

实时标签接口列表

使用流程

在实际使用实时标签 open api 时，需要按照一定的流程使用，确保使用的流程正确才能达到想要的效果。

实时标签状态流转过程：

常规的使用流程是：

iframe 创建实时标签 → 接口调用启用标签 → 标签计算完成后 → 根据用户调用结果查询结果查询实时标签的值。

 

实时标签的创建

实时标签的创建可以使用前端 H5 接入。

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

通过前端 H5 iframe 接入

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

http://{host-domain}/sf/h5/iframe-app/sf/realtime-tag?project=default&mode=create&language=zh-cn

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

参数

是否必传

参数说明
project 必传

需要调用的项目英文名称，如 default /production
mode 非必传 标识是创建、编辑还是查看配置，创建时传入 create，查看受众配置时传入 view，编辑受众传入 edit，默认为 create
tag_name 非必传 实时标签的名称，当 mode 是编辑或者查看的时候必传
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_REALTIME_TAG_SEND", // 消息来源标识
    "value": {
        "type": "CREATE_SUCCESS", // 创建成功标识，编辑保存成功后此处数据为 EDIT_SUCCESS
        "data": {
          "tag_name": "user_rt_tag_a232", // 实时标签名称
          "tag_cname": "2323"             // 实时标签显示名
        }
     }
}

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

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

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

 

实时标签的启动

method

Path
POST /api/v3/focus/v1/real-time-tag/start

请求示例

curl -X 'POST' \
  'http://{host-domain}/api/v3/focus/v1/real-time-tag/start' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \ 
  -d '{
  "name": "user_rt_tag_if1"
}'

返回结果示例

{
    "code": "SUCCESS",
    "request_id": "1817324224e122e36e58a32109d5b844",
    "data": {}
}

返回结果说明

参数

是否必返

参数说明
data 不必须

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

 

实时标签的停用

查询触发策略的额度使用信息

method

Path
POST /api/v3/focus/v1/real-time-tag/stop

请求示例

curl -X 'POST' \
  'http://{host-domain}/api/v3/focus/v1/real-time-tag/stop' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \ 
  -d '{
  "name": "user_rt_tag_if1"
}'

返回结果示例

{
    "code": "SUCCESS",
    "request_id": "18173335a669bc98b14f3d2ec81bf9d0",
    "data": {}
}

返回结果说明

参数

是否必返

参数说明
data 不必须

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

 

实时标签的查看

查询触发策略的额度使用信息

method

Path
GET /api/v3/focus/v1/real-time-tag/get

请求示例

curl -X 'GET' \
  'http://{host-domain}/api/v3/focus/v1/real-time-tag/get' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \ 
}'

参数说明

参数位置

参数

是否必传

参数说明
query name 必传 实时标签名称

返回结果示例

{
    "code": "SUCCESS",
    "request_id": "22174851c5359c51d11746be2ac7edd3",
    "data": {
        "realtime_tag": {
            "id": 73,
            "name": "user_rt_tag_if1",
            "cname": "iframe 创建11121",
            "project_id": 2,
            "group_id": 5,
            "comment": "1",
            "type": "GROUP_BASED",
            "use_instant_event": false,
            "data_type": "STRING",
            "status": "STOPPED",
            "time_zone": "",
            "rule": "{\"segment_based_rule\":{\"groups\":[{\"segment\":{\"type\":\"GROUP_EXPRESSION_BASED\",\"group_expression_rule\":{\"groups\":[{\"type\":\"EQL_BASED\",\"eql_segment_rule\":{\"eql\":\"(user.age == 11)\"}}],\"group_expression\":\"\\\"$1\\\"\"}},\"tag\":\"分层 1\"}]},\"tag_type\":\"SEGMENT_BASED\",\"version\":2.0}",
            "create_time": "2025-04-18 17:29:44",
            "update_time": "2025-04-18 17:39:42"
        }
    }
}

返回结果说明

参数

是否必返

参数说明
data 必须

调用成功后，code 为 SUCCESS，data 数据：

  • id ：实时标签 id
  • name：实时标签名称
  • cname: 实时标签显示名
  • project_id：项目 id
  • comment：备注
  • type：标签类型
  • use_instant_event：是否使用即时事件
  • data_type：数据类型
  • status：状态
  • rule：实时标签规则
  • create_time：创建时间
  • update_time：更新时间

 

实时标签的删除

查询触发策略的额度使用信息

method

Path
POST /api/v3/focus/v1/real-time-tag/delete

请求示例

curl -X 'POST' \
  'http://{host-domain}/api/v3/focus/v1/real-time-tag/delete' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \ 
  -d '{
  "name": "user_rt_tag_if1"
}'

返回结果示例

{
    "code": "SUCCESS",
    "request_id": "181733171b236e47faf08fcdf5e157e4",
    "data": {}
}

返回结果说明

参数

是否必返

参数说明
data 不必须

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

 

查询实时标签额度

查询触发策略的额度使用信息

method

Path
POST /api/v3/focus/v1/real-time-tag/quota/query

请求示例

curl -X 'POST' \
  'http://{host-domain}/api/v3/focus/v1/real-time-tag/quota/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default'

返回结果示例

{
    "code": "SUCCESS",
    "request_id": "18173352dc5ff1c93e4a66939f6949ff",
    "data": {
        "remain": 568,
        "use": 32
    }
}

返回结果说明

参数

是否必返

参数说明
data 必须

调用成功后，code 为 SUCCESS，data 数据：

  • remain ：实时标签剩余额度
  • use：实时标签使用额度

 

单用户的实时标签在线查询

在线查询单用户的实时标签集合，沿用查询用户属性的接口，以 HTTP API 形式接入，通过 HTTP API 方式查询单用户的实时标签集。

接口类型

method

Path
在线 /online POST /api/v3/focus/v1/express-attribute-online/get

请求示例

curl -X 'POST' \
  'http://{online-domain}/api/v3/focus/v1/express-attribute-online/get' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \
  -d '{
  "entity_name": "user",
  "audience_entity_id": {
    "identity_id_map": {
      "distinct_id": "sddd"
    }
  },
  "attribute_names": ["user_rt_tag_fencengshuzhiyunsuanfuyanzheng", "user_rt_tag_fenceng"]
}'

参数说明

参数位置

参数

是否必传

参数说明
body entity_name 非必传 实体名称，不传默认为用户实体，即 user
audience_entity_id 必传

查询的用户标识符，其中「用户标识」的字段含义如下：

  • entity_name 表示实体名称，不传表示 user
  • 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 等；identity_id_map 与 entity_id 只需设置其中一个，如果同时设置则以 entity_id 为准；identity_id_map 中本期只支持 distinct_id
  • entity_id 表示实体 id：
    • 实体 ID 目前只支持 user_id，为 int 类型，则值可表示为（具体值替换为具体的实体 id）："int_value": 123
attribute_names 必传 计算成功的实时标签名称

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "87c8382ffeed403b9c840dc448395cd3",
    "data": {
        "audience_entity": {
            "entity_id": {
                "data_type": "INT",
                "int_value": "-2443016794336717482"
            },
            "entity_name": "user",
            "audience_entity_attributes": [
                {
                    "name": "phone_number_new"
                },
                {
                    "name": "user_rt_tag_fencengshuzhiyunsuanfuyanzheng",
                    "value": {
                        "data_type": "STRING",
                        "string_value": "分层1",
                        "list_value": []
                    }
                }
            ]
        }
    },
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明
audience_entity 必返

查询的用户实体，其中 entity_id 代表用户标识
entity_name   实体名称
audience_entity_attributes  

实时标签列表，列表项字段说明：

  • name：实时标签名称
  • value：标签值

说明：当用户不存在时，请求接口会报错，提示用户不存在；当请求的实时标签不存在时，接口不会报错，返回的结果中实时标签对应的 value 无值。

 

批量用户的属性在线查询

在线查询一批用户的实时标签集，沿用查询用户属性的接口，以 HTTP API 形式接入，通过 HTTP API 方式查询一批用户的已订阅属性集。
接口类型

method

Path
在线 /online POST /api/v3/focus/v1/express-attribute-online/batch-get

请求示例

curl -X 'POST' \
  'http://{online-domain}/api/v3/focus/v1/express-attribute-online/batch-get' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \ 
  -d '{
  "entity_name": "user",
  "audience_entity_ids": [
    {
      "identity_id_map": {
        "distinct_id": "sddd"
      }
    }
  ],
  "attribute_names": ["user_rt_tag_fencengshuzhiyunsuanfuyanzheng"]
}'

参数说明

参数位置

参数

是否必传

参数说明
body entity_name 非必传 实体名称，不传默认为用户实体，即 user
audience_entity_ids 必传

查询的用户标识符，其中「用户标识」的字段含义如下：

  • entity_name 表示实体名称，不传表示 user
  • 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 等；identity_id_map 与 entity_id 只需设置其中一个，如果同时设置则以 entity_id 为准；identity_id_map 中本期只支持 distinct_id
  • entity_id 表示实体 id：
    • 实体 ID 目前只支持 user_id，为 int 类型，则值可表示为（具体值替换为具体的实体 id）："int_value": 123
attribute_names 必传 实时标签名称

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "0c7b4c998b7a4209b12ed8cc18a31ae1",
    "data": {
        "audience_entities": [
            {
                "entity_id": {
                    "data_type": "INT",
                    "int_value": "224266287"
                },
                "entity_name": "user",
                "audience_entity_attributes": [
                    {
                        "name": "user_rt_tag_fencengshuzhiyunsuanfuyanzheng",
                        "value": {
                            "data_type": "STRING",
                            "string_value": "分层 1",
                            "list_value": []
                        }
                    }
                ]
            }
        ]
    },
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明
audience_entities 必返

查询的用户实体列表，其中 entity_id 代表用户标识
entity_id 必返
  • entity_id 表示实体 id：
    • 如果实体 ID 为 int 类型，则值可表示为（具体值替换为具体的实体 id）："int_value": 123
    • 如果实体 ID 为 String 类型，则值可表示为（具体值替换为具体的实体 id）："string_value": "xxxxx"
entity_name 必返 实体名称
audience_entity_attributes 必返

实时标签列表，列表项字段说明：

  • name：实时标签名称
  • value：实时标签值，如果值不存在，则只返回 name
上一个
属性标签订阅服务接入
下一个
触发策略服务接入
最近修改: 2025-09-05