功能概述

  • Webhook 是一个 HTTP 形式的回调接口,用以支持自定义的营销行为,该接口需要研发团队一些开发工作,详见 Webhook 对接文档。
  • 当用户被触发(满足计划中的条件)时,会去回调请求 Webhook 接口,并把该用户的基本信息或其他自定义内容以 json 格式的请求体传递给客户的服务器,客户就可以在接口中利用这些信息进行后续的操作,比如,对用户进行消息推送、权益发放等。

适用场景

  • 客户已经拥有了一套消息推送平台,那么这种情况下就可以编写一个 Webhook 进行中转,在智能运营与已对接的推送通道之间做一个适配。

  • 对接权益系统,利用神策智能运营灵活的规则定义来触发优惠券、积分的发放(受众筛选规则、行为触发规则)。

创建 Webhook

在 Webhook 通道管理列表中,点击创建 Webhook,进入创建页面。

输入请求地址

输入 Webhook 要请求的目标地址,支持 http、https。

选择发送 ID

选择发送 ID 在用户表里存储的属性字段,如,通过 Webhook 对接站内信,那发送 ID 这里选择登陆 ID。注意,创建计划进行预估受众时,会过滤掉发送 ID 为空的用户。Webhook 类型的计划里的计划触发、目标完成指标也都会过滤掉发送 ID 为空的用户。

选择是否添加回执

添加回执需要客户上报回执事件。添加成功后,当 Webhook 触达用户时,将回传触达结果(发送成功/发送失败),并展示在运营计划/流程画布的数据分析中。

添加用户属性

可添加多条用户属性,配置成功之后,运营人员在创建计划时不需要定义这部分的内容,配置好的用户属性会自动加到请求体里。

  • 参数名称:自定义发送的用户属性参数的名称,必须为英文,为请求里的 Key。

  • 属性参数:选择要发送的用户属性。

  • 默认值:当属性值为空时使用默认值。

添加模板参数

可添加多个模板参数,配置成功之后,运营人员在创建计划时可以灵活定义这些模板参数的值,比如配置了模板参数标题、内容,那么后续每次创建计划时就可以灵活定义发送的标题和内容。

  • 参数名称:自定义发送模板参数的名称,必须为英文,为请求里的 Key。

  • 显示名称:在「创建计划-触达配置」页面里显示的名称。

  • 参数类型:目前支持创建的类型为字符串型、文本型、链接、数值型、日期型、图片型、富文本、动态下拉、iframe;其中字符串型不支持插入用户属性;文本型、链接和富文本支持插入用户属性;富文本型还支持插入图片和超链接;数值型包括小数、整数、百分比三种;图片支持绝对、比例的尺寸限制。

  • 添加提示文案:提示运营人员当前参数的输入规范。
  • 添加选项:当参数类型为字符串型、文本型、数值型时,支持添加参数选项。编辑完选项后,可以设置默认项,默认项将会在运营人员配置参数时自动填充到输入框。
  • 设置必填:至少勾选 1 个模板参数作为必填项,运营人员在使用 Webhook 时,必填参数全部填写才能提交。

参数类型-动态下拉参数

  •  能力:
    • 下拉参数为从客户接口实时获取。
    • 下拉除了一级下拉,还支持多级目录树,支持搜索;比如可以做实时可用的优惠券、模板的动态下拉。
    • 下拉参数支持配置参数描述,描述信息会以卡片形式展示在下拉窗口旁,为业务人员选择参数时提供参考。
    • 建议合理设置筛选条件,维持在500个选项以内,以保证易用性和速度。
  • 参数配置:需配置下拉参数获取的地址。支持http和https,统一为Get请求。特别提示:URL常需要携带参数,请注意配置完整。
  • 数据结构示例如下:
    [
        {
            "name":"宠物",
            "value":1,
            "detail":{
                "subtitle":"热销宠物用品",
                "description":"最近1个月的宠物用品销量统计",
                "others":[
                    {"label":"猫砂","value":1000}
                ]
            }
        },
        {
            "name":"办公用品",
            "value":2,
            "children":[
                {
                    "name":"电脑",
                    "value":3, 
    				"detail":{
                        "subtitle":"MacBook Pro",
                        "description":""
                    }             
    	        }
            ]
        }
    ]
    JS
  • 参数说明:
    参数名参数类型是否必需样例值备注
    nameString"name": "选项名称"

    下拉菜单中,选项的显示名称。同时该名称与参数信息卡片的标题一致。

    value

    String | Number

    "value": 1

    选项值,值必须唯一。

    children

    Arrey

     "children": [
    {"name": "选项名称1", "value": 3}
    ]

    数组成员为对象,对象结构及属性与外层数据的一致

    detail

    Object

    "detail":{
         "subtitle":"参数副标题",
         "description":"描述",
         "others":[
              {
                "label":"补充信息",
                "value":1000
               }
           ]
     }

    参数信息卡片中展示的内容,未填写则不展示对应卡片

  • detail:
    参数名参数类型是否必需样例值备注
    subtitleString"subtitle": "参数副标题"未填写则不显示
    descriptionString"description": "参数说明"若填写则显示,未填写则显示:“未填写说明”
    othersArray

    "others": [
    {"label": "这是字段一", "value": 1000},
    {"label": "这是字段二", "value": 1500}

    额外的补充展示字段,未填写则不显示。

    数据结构为数组,成员为对象,对象属性如下表。

    在页面上均作为单独一行文本进行显示。

  • others:
    参数名参数类型是否必需备注
    labelString补充字段的标签名
    valueString|Number补充字段的标签值
  • 返回数据结构:前端基于此结构提供下拉选择组件(树形下拉选择),示例如下:
    interface Option {
        name: string;
        value: string | number;
        detail?: {
          subtitle?: string;
          description?: string;
          others?: {
            label: string,
            value: string | number
          }[];
        };
        children?: Option[];
    }
    
    type Data = Option[];
    JS
  • 注意:只有具有「detail」字段的尾结点才会展示卡片
  • 页面效果如下:

参数类型-iframe

  • 能力:
    • 点击配置项时,呼出页面来进行选择。可以在此页面中定制各种复杂操作,页面逻辑,最终返回一个选择的最终结果。

    • 结果会以字符串形式回显。
    • 再次打开时,之前的选择操作会回传到 iframe页面,iframe自行处理(例如定位到之前的选项位置)。
  • 参数配置:需配置下拉参数获取的地址。支持http和https,统一为Get请求。
  • 数据交互:
    • 打开 iframe 时 url 上会携带参数,参数可以自定义名称,但必须是静态值。例如 type,value,`${url}?type=${XXX}&value=${value}` 。
    • iframe 向 Webhook 配置页传递数据:

      window.parent.postMessage({
          type: 'XXX', // url 链接上传过来的 type 字段
          value: '来自 iframe 的消息' // 需要传递给 Webhook 的字符串
      }, '*');
      JS
  • 特别提示:URL常需要携带参数,请注意配置完整。

高级设置 - 配置参数

Webhook为开发者提供更灵活的参数配置,可添加多个参数,满足企业更多使用上的需求

  • 一个batch包含的消息数量:支持自定义每次对接口调用传输的消息量。默认为50,支持输入正整数,限制为 1-1000 如有调整需求,建议联系神策技术进行
  • SecretToken:支持接口认证密钥。输入无特殊限制。
  • 超时判断:支持自定义接口调用的超时时间。毫秒级的时间粒度,默认为10000毫秒,支持切换正整数输入;增加或者减少的箭头是按照秒单位来进行增加或者减少,最大上限为1分钟。
  • 开启压缩请求:支持对下游传输数据进行压缩。默认为否,不开启。
  • 是否校验批量请求结果:支持是否进行校验的设置。
    • 如果选是,即对下游接口的调用成功后(HTTP 200),会对 response body 做解析,来检查每条消息的发送状态,从而计算发送成功和发送失败的条数。注意,返回的 body 格式需符合神策规范。
    • 默认为否,即对下游接口的调用成功后(HTTP 200),认为所有消息都发送成功。需要注意的是,在该选项下,若测试发送的消息最终送达失败,则不会展示失败信息。
  • 发送频率限制(次/秒):支持发送频率的限制。支持正整数的切换,默认为不限制;切换到自定义时,默认为 1。支持在通道开启时编辑。
  • Batchsize 最大值:支持配置每批消息包含的最大消息数,默认 50。支持在通道开启时编辑。
  • 引擎异常重发:
    • 高速模式:默认选项。如果某批数据发到一半引擎异常,会导致未发的数据丢弃,不再重发。
    • 可靠模式:由于系统问题导致的数据发送异常,同批数据会整体重新发送。请注意:重发的同批数据可能部分已经成功传输到下游,下游系统要做好去重工作。

保存

  • 完成所有设置以后,提交保存,以下为配置的一个样例,供参考:

  • 在创建计划-触达配置选择该 Webhook 的配置界面,如下图:

测试发送

  • 账号创建之后,默认关闭,可以先进行测试发送,确定能发送成功后再开启账号。
  • 点击测试发送,填写测试发送信息。
  • 点击下一步,预览之后发送,稍后右上角会返回发送回执,若发送成功,会返回成功信息;若仍未收到,可点击下载日志查看原因。

Webhook 管理

开启关闭 Webhook 账号

添加 Webhook 账号后,默认关闭,需要手动开启。

  • 账号开启后,新建计划或流程画布时可使用该账号。
  • 账号关闭后,新建计划或流程画布时不可使用该账号,已建计划或流程画布的处理逻辑如下
    • 关闭时将出现弹窗提醒,其会展示受影响的计划或流程,确认关闭后将暂停受影响的计划和流程。同时对于使用了已关闭账号的计划或流程,以下几种情况将引导用户切换通道或重新开启通道
      • 启动暂停中的计划或流程,且这些计划或流程使用了已关闭通道。
      • 编辑暂停中的计划或流程,且这些计划或流程使用了已关闭通道。
      • 复制使用了已关闭通道的计划或流程。
      • 编辑使用了已关闭通道的流程画布的草稿。

编辑 Webhook

  • 已添加账号支持查看、编辑
    • 编辑账号需要:将账号关闭后,才可以编辑。若编辑操作(如透传字段增减)影响了已建计划或流程,则对这些受影响的计划或流程进行编辑、启动、复制等操作时提醒用户进行确认或修改。
  • 根据实际运营需求,可添加多个 Webhook,如对接站内信、对接权益系统等。

删除 Webhook

删除账号需要:将账号关闭后,才可以删除。删除账号后,使用了该账号的计划和流程仍支持查看,若对这些受影响的计划或流程进行编辑、启动、复制等操作将引导切换账号。

接口和数据格式

Webhook 的接口对接文档详见 Webhook 通道接入 。