触发策略服务接入

名词解释

接口文档列表

触发策略接口列表

使用流程

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

在实际使用中，触发策略引擎与业务系统之间交互的地方主要有：

• 业务系统需要先创建一个 webhook 通道实例，用于接收满足触发策略的触达通知；
• 业务系统需要创建触发策略，创建方式当前提供两种形式：1、内嵌 iframe 的方式进行创建；2、调用触发策略创建接口进行创建；
• 触发策略就绪通知接收地址的配置（此处和受众引擎通知配置是一致的），项目级别配置通知接收地址；
• 触发策略创建成功后，需要业务系统调用触发策略的启动接口，之后触发策略才会启动开始处理；当触发策略一切准备就绪，真正启动成功（用户属性同步成功，受众计算成功）时，神策会通过通知的方式通知到业务系统；
• 另外提供触发策略终止、删除、查询、编辑、额度查询、触发策略 id 校验接口供业务系统按需调用。

通道实例创建

创建触发策略之前需要首先确定要使用的通道实例，通道实例是在项目上线之前一次性创建完毕。

通道实例的创建可以通过神策系统页面进行创建，也可以通过接口的形式进行创建。

界面创建通道实例

进入神策系统， 在 数据服务 -> 触发策略服务 -> 通知通道管理

点击创建 Webhook，参数按如下要求填写：

创建完通道之后，即可在配置触发策略的页面选择该通道。

消息接收服务

消息接收服务主要是用来接收推送的数据，代码开发可参考：Web Java 快速入门

url 地址可以自定义，在创建通道实例的时候填充进去即可。

神策系统的 sender 模块，会以 post 的方式调用接口， 输入参数格式如下（重点关注里面的 user_profile 和 plan_info 里面的 strategy_biz_id， 通过 strategy_biz_id 关联业务信息）：

[{
    "project_name": "default",
    "sf_version": "4.0",
    "user_profile": {
        "user_id": 7085654471715153826,
        "first_id": "test_user_1",
        "second_id": "test_user_1"
    },
    "receipt_properties": {
        "sf_msg_id": "msg_id_4582_4_7085654471715153826_1716435495176",
        "sf_plan_id": 4582,
        "sf_plan_audience_id": null,
        "sf_plan_strategy_id": 0,
        "sf_strategy_unit_id": 4,
        "sf_plan_type": "\u65b0\u6d41\u7a0b\u753b\u5e03",
        "sf_channel_id": 89,
        "sf_channel_category": "WEBHOOK",
        "sf_enter_plan_time": 1716435495176,
        "sf_plan_version": "1",
        "sf_component_id": 4,
        "sf_send_time": 1716435510264
    },
    "params": {
        "content": "test content"
    },
    "send_id": "7085654471715153826",
    "plan_info": {
        "cname": null,
        "type": null,
        "schedule_type": null,
        "finish_time": null,
        "component_cname": null,
        "strategy_biz_id": "test_biz_id"
    }
},
{
    "project_name": "default",
    "sf_version": "4.0",
    "user_profile": {
        "user_id": 7085654471715153826,
        "first_id": "test_user_1",
        "second_id": "test_user_1"
    },
    "receipt_properties": {
        "sf_msg_id": "msg_id_4582_4_7085654471715153826_1716435495176",
        "sf_plan_id": 4582,
        "sf_plan_audience_id": null,
        "sf_plan_strategy_id": 0,
        "sf_strategy_unit_id": 4,
        "sf_plan_type": "\u65b0\u6d41\u7a0b\u753b\u5e03",
        "sf_channel_id": 89,
        "sf_channel_category": "WEBHOOK",
        "sf_enter_plan_time": 1716435495176,
        "sf_plan_version": "1",
        "sf_component_id": 4,
        "sf_send_time": 1716435510264
    },
    "params": {
        "content": "test content"
    },
    "send_id": "7085654471715153826",
    "plan_info": {
        "cname": null,
        "type": null,
        "schedule_type": null,
        "finish_time": null,
        "component_cname": null,
        "strategy_biz_id": "test_biz_id"
    }
}
 
]

返回格式为：（返回空 body）

触发策略嵌入 iframe 创建

触发策略的创建可以使用前端 H5 接入。

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

通过前端 H5 iframe 接入

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

http://{host-domain}/sf/h5/iframe-app/sf/trigger-strategy?project=default&trigger_biz_id=test&mode=create&language=zh-cn

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

使用 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_TRIGGER_SEND", // 消息来源标识
    "value": {
        "type": "CREATE_SUCCESS", // 创建成功标识，编辑保存成功后此处数据为 EDIT_SUCCESS
        "data": {
          "trigger_biz_id": "324234234234" // 触发策略业务 ID
        }
     }
}

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

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

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

嵌入 iframe 查看指标

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

http://{host-domain}/sf/h5/iframe-app/sf/trigger-strategy?project=default&trigger_biz_id=test&mode=statistics&language=zh-cn

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

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

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

指标页面如下：

触发策略状态机

触发策略当前共有 4 种状态：CREATED  新建、PENDING 待运行、ACTIVE 运行中、FINISHED 已终止

触发策略的启动

触发策略状态只有 CREATED（待启动）才能调用启动接口成功，否则会失败。

请求示例

curl -X 'POST' \
  'http://{host-domain}/api/v3/focus/v1/trigger-strategy/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 '{
  "biz_id": "trigger_10000001"
}'

参数说明

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "6e049dcdcad547d488d8da44a50c5056",
    "data": null,
    "error_info": null
}

返回结果说明

触发策略的终止（终止之后不允许再调用 start 接口）

除了 FINISHED 状态的触发策略不能调终止接口外，其它状态的触发策略都可以调终止接口：CREATED（待启动）、PENDING（待运行）、ACTIVE （运行中）。

策略状态解释

CREATED 已创建：iframe 创建了策略，但还没调启动接口；

PENDING 待运行：已调启动接口，但还没到策略里设置的触发开始时间；

ACTIVE 运行中：策略到了设置的触发开始时间，开始运行；

FINISHED 已终止：到了策略里设置的终止时间结束，或调终止接口结束；

请求示例

curl -X 'POST' \
  'http://{host-domain}/api/v3/focus/v1/trigger-strategy/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 '{
  "biz_id": "trigger_10000001"
}'

参数说明

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "6e049dcdcad547d488d8da44a50c5056",
    "data": null,
    "error_info": null
}

返回结果说明

触发策略列表查询

批量查询触发策略，可按照一定的过滤规则进行查询，支持分页

请求示例

curl -X 'GET' \
  'http://{host-domain}/api/v3/focus/v1/trigger-strategy/query?biz_key=trigger_10000016' \
  -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' \ 

参数说明

status

type

create_time_start

create_time_end

page_num

page_size

返回结果示例

{
    "code": "SUCCESS",
    "request_id": "18160757d9aabf6e28e447beb28f405e",
    "data": {
        "strategies": [
            {
                "canvas_id": 4235,
                "biz_id": "trigger_10000007",
                "cname": "z_strategy_onec_1",
                "entry_type": "BATCH_AUDIENCE_ONETIME",
                "event_entry_config": {
                    "process_event_type": "",
                    "start_entry_time": 0,
                    "end_entry_time": 0,
                    "origin_event_do_rule": "",
                    "origin_event_not_do_rule": ""
                },
                "audience_entry_config": {
                    "audience_type": "AUDIENCE_ONETIME",
                    "fixed_time": 1710491700000,
                    "start_date": 0,
                    "end_date": 0,
                    "cron": "",
                    "user_group_rule": {
                        "operator": "INTERSECT",
                        "groups": [],
                        "compound_groups": [
                            {
                                "operator": "INTERSECT",
                                "groups": [
                                    {
                                        "type": "PROFILE_FILTER_BASED",
                                        "profile_user_group": {
                                            "condition": {
                                                "operator": "AND",
                                                "conditions": [
                                                    {
                                                        "function": "IS_SET",
                                                        "params": [
                                                            {
                                                                "param_type": "FIELD",
                                                                "field": "user.age",
                                                                "variable": "",
                                                                "expression": ""
                                                            }
                                                        ],
                                                        "index": 0
                                                    }
                                                ],
                                                "compound_conditions": [],
                                                "index": 0
                                            }
                                        }
                                    }
                                ],
                                "compound_groups": [],
                                "limit": 0,
                                "shuffle": false
                            }
                        ],
                        "limit": 0,
                        "shuffle": false
                    },
                    "audience_template_id": 0,
                    "audience_template_type": "AUDIENCE_TEMPLATE_TYPE_UNSPECIFIED",
                    "audience_biz_id": "",
                    "estimate_count": 0,
                    "origin_audience_rule": "{\"select_all\":false,\"rule_content\":{\"type\":\"rules_relation\",\"relation\":\"and\",\"rules\":[{\"type\":\"rules_relation\",\"relation\":\"and\",\"rules\":[{\"type\":\"profile_rule\",\"field\":\"user.age\",\"function\":\"isSet\",\"params\":[],\"cname\":\"age\",\"icon\":\"\"}]}]},\"audience_type\":\"BATCH\",\"streaming_audience_config\":null}"
                },
                "msg_send_config": {
                    "channel_category": "WEBHOOK",
                    "channel_instance_id": 63,
                    "msg_content": "{\"freemarker_syntax_version\":2,\"plan_params\":[{\"name\":\"name\",\"cname\":\"必填很奇怪\",\"value\":\"z_strategy_onec_1\",\"required\":true,\"extra\":null}]}"
                },
                "re_entry_config": {
                    "reentry_strategy": "REENTRY_NO"
                },
                "finish_time": 1710498900000,
                "creator_id": 2,
                "time_zone": "+08:00",
                "create_time": "2024-03-15 16:33:56",
                "status": "FINISHED",
                "status_desc": "",
                "create_source": "SFN"
            }
        ],
        "count": 1
    }
}

返回结果说明

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