DingTalk「开发者说」
酷应用开发之群扩展基础开发
摘要:本篇主要讲解钉钉酷应用在群内的功能,群内酷应用的接入、开发演示和最佳实践。
分享人:云欢,酷应用开发后端技术专家
视频地址:
正文:
一、 酷应用能力演示
1. 群内酷应用的作用
酷应用的核心是让钉钉用户在钉钉群实现边聊边干,从而提升工作效率。
酷应用是一种基于沉浸式、场景化、网络协同和数据普惠理念的全新应用形态,通过群内的酷应用,让沟通和业务协同在群内沉浸式的完成。
上图是钉钉群内应用市场
2. 群内玩转酷应用演示:叮当OKR
叮当OKR是一款已上架的群内酷应用,在群聊场景下,可以实现边沟通边创建OKR、以及互动的功能。它具有7个核心能力点:感知安装事件,打开半浮层页面,互动卡片发送,点击互动,更新互动卡片点赞数,发送吊顶,更新吊顶。
- 功能1:安装酷应用
群内访问酷应用市场安装酷应用,叮当OKR会监听到钉钉侧安装OKR事件,通过感知安装事件 ,发送欢迎语;
- 功能2:打开OKR
通过会话应用栏的群应用入口,在群内打开半浮层页面;
- 功能3:新建OKR
将新OKR内容以互动卡片形式发送到群内;
- 功能 4:给OKR点赞
卡片点击互动,并更新互动卡片点赞数;
- 功能 5:OKR吊顶汇总
群内创建OKR后会在群内发送吊顶,常驻显示OKR汇总信息,并实时更新吊顶。
二、 接入指南
1. 核心能力概要
酷应用有五个核心能力:
酷应用核心功能
a. 事件回调
- 感知酷应用和群的各类生命周期事件;
- 主要的5个事件是:酷应用启用、酷应用停用、群解散、添加群成员、删除群成员;
b. 互动卡片
- 在开放区块内嵌开发者页面呈现数据、提供用户交互能力;
- 卡片类型包括消息卡片、群置顶卡片等,达到用户交互、主动更新、千人千面的效果;
c. 群应用入口
- 应用功能的快捷入口,用户通过点击可快速访问功能页面;
- 其功能特性包括:多端定制、多模式打开、动态参数、红点引导、多机菜单等;
d. 机器人
- 消息收、发通道,具备对话式交互能力;
- 主要能力包括:发送消息、接收消息、撤回消息、差已读未读等;
e. 能力套件
- 可内嵌到开发者自己页面内部的一系列钉钉前端组件;
- 将钉钉原生能力如:启动酷应用、建群、用户发消息、群内加人等以一方体验的交互集成到自己的页面内;
2. 事件回调
钉钉酷应用生命周期的各类事件,都会在事件发生后,通过事件回调通知开发者。
a. 事件分类
酷应用生命周期的各类事件大概可以分成三类:
- 酷应用启用
- 最先感知到的生命周期事件,建议开发者进行数据与群绑定等初始化操作,对用户推送欢迎语和操作指引;
- 群原生事件
- 包括添加/删除群成员、群名称变更等,建议开发者在自己的功能中进行数据同步,权限、规则更新;
- 终止类事件
- 最后感知到的生命周期事件,如:群解散、酷应用停用,建议开发者进行合理的数据、权限更新;
b. 酷应用启动/停用事件内容示例
- 启动酷应用事件:
{
"syncAction": "im_cool_app_install",
"OpenConversationCorpId": "ding9bd1bfb59xxxxxxxxxxxxxxxxxxx",
"OperateTime": "1641866135051",
"OpenConversationId": "cidT461wC7yvGJxxxxxxxxxxxxxx",
"CoolAppCode": "COOLAPP-1-1018xxxxxxxxxxxxxxxx",
"RobotCode": "rBLBXuiaA2rn3xxxxxxxxxxxxxx"
}
- 停用酷应用事件:
{
"syncAction": "im_cool_app_uninstall",
"OpenConversationCorpId": "ding9bd1bfb59xxxxxxxxxxxxxxxxxxx",
"OperateTime": "1641866135051",
"OpenConversationId": "cidT461wC7yvGJxxxxxxxxxxxxxx",
"CoolAppCode": "COOLAPP-1-1018xxxxxxxxxxxxxxxx",
"RobotCode": "rBLBXuiaA2rn3xxxxxxxxxxxxxx"
}
语句说明:
syncAction:区分事件类型;
OpenConversationCorpId:事件归属的企业;
OperateTime:事件实际发生时间;
OpenConversationId:发生事件所对应的群ID,是事件中最重要的信息,代表酷事件在这个群被启用或停用;
CoolAppCode:开放平台酷应用的唯一ID;
RobotCode:酷应用在群内发消息的机器人的唯一标识。
c. 三种事件回调方案
下图是钉钉事件回调网关的三种主要技术回调方案,包括接入方式以及简单的技术特性。
HTTP推送
- 简介:钉钉开放平台早期的事件推送方式,使用HTTP的方式注册钉钉的回调事件,用于接收钉钉推送的消息;
- 适用应用:企业内部应用;
- 安全性:公网通道,有流量花费;
- 数据同步:不支持同步协议,当网络异常或开发者服务出现问题时会出现数据丢失;
- 数据结果:不是最终态数据,需反查最新数据;
RDS推送
- 简介:RDS推送在保障数据安全的前提下,通过简化传输协议,减少传输次数,提高速度和稳定性;
- 适用应用:第三方企业应用(强烈推荐);
- 安全性:内网通道,无流量花费;
- 数据同步:支持同步协议,若开发者的RDS出现故障,数据会永久存储在钉钉;
- 数据结果:最终态数据,可以直接使用;
SyncHTTP推送
- 简介:与HTTP推送方式比,SyncHTTP推送的是业务数据的最终状态,开发者可以直接使用推送的数据;
- 适用应用:第三方企业应用;
- 安全性:公网通道,有流量花费;
- 数据同步:不支持同步协议,当网络异常或开发者服务出现问题时会出现数据丢失;
- 数据结果:最终态数据,可以直接使用。
参考资料:https://open.dingtalk.com/document/isv/callback-events-overview
3. 互动卡片
a. 互动卡片的三个重点特性:
卡片内容动态更新
- 开发者更新卡片数据,钉钉多端实时刷新卡片内容。
- 两种可触发更新数据的方式:
点击更新:用户点击卡片按钮触发回调,开发者返回最新卡片数据;
主动更新:开发者调用API主动更新卡片数据;
用户点击交互
- “实时互动”能力:让用户通过点击按钮的方式直接在卡片内进行交互,促进沟通互动,并且无需进入二级页面,能够缩短用户操作路径,提升效率。
注:用户交互通过http回调给开发者的服务进行处理,服务调用rt长时间低于1200ms,可能会被限流。
- 千人千面
群聊是一个特殊的交互场景,会有很多人同时在进行群聊页面的互动。当一张互动卡片出现在群内时,操作者可以是群里所有的人,因此在对群内数据透出时,酷应用支持让不同的人看到不同的数据并操作不同功能。
【示例】
以一个会议邀请的卡片为例(见下图),对于staff001,在他没有任何操作之前,他看到的卡片是有“拒绝”和“接受”两个按钮;对于staff002,他已经接受了,因此他看到的卡片只显示“已接受”。
互动卡片示例
开发者提供的卡片数据,会用于卡片布局渲染和数据内容填充,分为公有数据和私有数据。借助公有和私有数据,实现卡片布局和内容的千人千面。
- 公有数据:默认卡片对每个用户渲染优先使用的数据;
- 私有数据:对部分用户指定私有数据,优先用私有数据渲染卡片。
注:单张卡片最多支持500个用户的私有数据,单词调用建卡片和更新卡片接口,最多支持传递20个用户的私有数据。
b. 互动卡片开发流程
钉钉互动卡片是通过低代码的形式,在卡片搭建平台建立模板,模板支持预览工具,可以预览卡片的实际效果。
互动卡片的开发工程主要分为三个步骤:
- 第一步:在搭建平台建立模板;
- 第二步:在搭建平台根据需求和前端要求调试卡片;
- 第三步:将实际业务数据通过卡片的开放API发送卡片到群内。
参考资料:https://open.dingtalk.com/document/group/create-message-template
c. API重要参数讲解
cardTemplateId
- 互动卡片的消息模板ID;
- 创建消息模板后可获取模板ID;
outTrackId
- 开发者指定的卡片外部唯一编码;
- 说明:由开发者自己生成并作为入参传递给钉钉,钉钉只在对应使用到outTrackId的场景,如:后续根据outTraceId主动更新卡片内容;
robotCode
- 机器人唯一编码;
- 说明:可以为空,以机器人发卡片消息时需指定;
callbackRouteKey
- 用户触发交互时查找的 http 回调地址的路由Key,一个callbackRouteKey可注册一个callbackUrl 用于回调,卡片开发者会根据收到的回调信息进行卡片回复或更新卡片数据;
- 说明:可以为空,不填写默认无需回调;
cardData
- 卡片公有数据;
privateData
- 用户差异部分数据,如:卡片按钮。
注:此处列举的字段说明,对于互动卡片消息和互动卡片吊顶的发送接口都适用。
d. 群置顶卡片的开发流程
- 第一步:创建卡片模板——选择“吊顶卡片”;
- 第二步:创建互动卡片实例;
- 第三步:调用开启互动卡片实例置顶接口,发送互动卡片实例到置顶区域。
e. 开发注意事项
- outTrackId是更新卡片的唯一凭证,注意保存;
- outTrackId建议根据自己的业务模型生成,如:订单ID+群cid;
- 建议用移动端进行卡片的开发调试,如果使用桌面端,在卡片模板编辑后需重启才能更新已收到的该模板卡片。
另外,群置顶卡片开发注意事项:
- 需先创建卡片实例,然后再调用接口;
- 调用关闭互动卡片实例置顶接口,可关闭置顶区域的互动卡片,建议在接入互动卡片置顶时一定要接入这个接口,这个能力保障在出现紧急舆情或风险时可以撤回互动卡片实例。
4. 群应用入口
a. 产品描述
群应用入口是群会话的快捷栏入口,用户通过点击可以快速访问功能页面。
- 支持动态参数
开发者在配置链接时,可以带上群id、组织id动态参数,用户点击插件访问时可以将指定的动态参数带回到服务端;
- 可运营
开发者可以通过API,在指定的群应用入口上发送红点提示(规划中)。
b. 产品demo
以叮当OKR酷应用为例,将“我的OKR”、“创建OKR”作为入口放在群快捷栏上,让内部群的用户可以直接在群内查看OKR和创建OKR,同时借助蓝条和红点提示能力,在插件上做信息的提示。
c. 元数据介绍
在群应用入口会涉及到以下字段:
- 名称: 用于群快捷栏展示提示用途,最多支持4个字;
- 移动端跳转地址:不填写则移动端不显示群应用入口;
- 桌面端跳转地址:不填写则桌面端不显示群应用入口;
- 图标:快捷栏内展示的图标,按照规范上传;
d. 构造跳转地址 - 指定打开方式
开发者可以通过Dingtalk的url协议来包装自己的实际页面链接,通过url参数的配置,可以指定实际页面链接的打开方式,如半浮层、侧边栏、常驻第四栏等。
【示例】用50%高度的半屏模式打开
dingtalk://dingtalkclient/page/link?dd_mode=float&pannelHeight=percent50&pc_slide=true&url=https%3A%2F%www.dingtalk.com%2F%3Fcorpid%3D$CORPID$%26openConversationId%3D$ENCCID$
参数说明:
- url:以dingtalk开头代表这个url是DingTalk协议,url后面跟的是开发者的实际页面地址,必须做urlencode;
- ddmode:指定客户端打开链接的方式,这里指定是“float”浮层方式;
- pannelHeight:指定浮层的打开比例,这里指定是50%的比例;
- pc_slide:当pc_slide=true时,PC端会在应用内打开这个URL。
e. 构造跳转地址 – 配置需要的动态参数
为了在开发者页面中可以感知到访问的用户所属企业、点击来源的群信息,可以在跳转地址中配置动态参数,当从会话应用栏打开改地址时,动态会实时替换成真实值。
【示例】
dingtalk://dingtalkclient/page/link?dd_mode=push&pc_slide=true&url=https%3A%2F%2Fwww..com%2F%3Fcorpid%3D$CORPID$%26openConversationId%3D$ENCCID$
参数说明:
- $CORPID$:动态替换企业ID(corpId);
- $ENCCID$:动态替换企业群ID(openConversation),仅在不使用钉钉统一跳转协议时使用此动参。
当打开页面时,以上两个参数就会被动态替换成实际的企业ID和群ID。
注:
虽然url后面的实际值被encode,但$CORPID$和$ENCCID$无需被encode;
如果地址是dingtalk协议地址,并且要打开的页面是小程序,为了对容器进行兼容,需要用$DOUBLE_ENCCID$来代替$ENCCID$。
f. 群应用入口更新的原理图示
- 除安装酷应用外,群应用入口的更新有15分钟缓存;
- SPI模式(规划中):通过SPI接口形式让开发者感知用户点击快捷入口的操作,并提供对应的功能;
- 蓝条/红点(规划中):开发者向自己的快捷入口上推送蓝条和红点功能。
5. 群聊机器人
a. 消息触达能力介绍
- 接收用户消息
用户at机器人的消息以Http 回调的形式回调给开发者;
- 发送消息
可用API发送互动卡片等各种内容到群内;
- 查询已读/未读
通过消息id 查询已发送消息的已读未读数据;
- 撤回消息
通过消息id 撤回已发送的消息;
- 机器人管理
机器人是随酷应用一起安装到群内,同时,机器人也随酷应用一起从群内卸载。
b. 发送互动卡片消息API关键参数
- openConversationId
群的唯一标示,可从酷应用启用事件中获得;
- robotCode
机器人的唯一标示,可以在开发者后台获取到;
- cardTemplateId、outTrackId、callbackRouteKey、cardData、privateData
互动卡片本身相关参数;
- receiverUserIdList
消息的重点特性,是消息接收者的userId清单,仅清单内用户可见消息,字段为空则群内所有人可见;
- atOpenIds
消息重点特性,消息at人的userId清单,清单内的人有对应被at的消息提示效果;
- supportForward
消息重点特性,指定消息是否可被转发;
- processQueryKey
接口返回的消息id,用于查询消息已读情况以及撤回消息使用,是查询和撤回消息的关键字段,这个参数非常重要,建议在接入时保存。
完整接口文档:https://open.dingtalk.com/document/group/send-interactive-dynamic-cards
c. 机器人消息收发链路图
下图是钉钉机器人消息收发链路图,钉钉所有机器人消息链路都符合这个关键链路的设计范式。
- 在这个设计范式中,开发者具有发送、查询、撤回机器人消息、以及收到机器人消息回调的能力;
- 钉钉内部对发送的消息进行消息限流、内容安全检查、消息体格式检测等操作,因此,开发者需对消息发送频次和内容进行管控;
- 机器人消息回调时,也会对消息体进行解析和处理,处理后的消息是统一的数据格式。
d. 机器人发群聊消息的一些限制
- 可用范围:
企业自建和三方应用机器人都有组织属性,群聊机器人只有在组织属性的群中才可使用,如内部群;
- 限流:
为保障会话体感,机器人一分钟发送消息条数有所限制,使用开放平台sdk发机器人消息,每个会话(单聊、群聊)会有120次/分钟的限制;通过webhook方式发消息限流为20次/分钟;
- 酷应用发送群聊普通消息(规划中):
酷应用发送群聊(文本、图片、markdown)消息入参需要填写酷应用的code。
注:酷应用使用机器人发送群聊消息,需要在调用接口的同时,复制接口中酷应用的code,目的是标识机器人发消息的使用场景所对应的酷应用服务,当酷应用从群内卸载后,将无法发送消息。
e. 关键API文档
- 机器人查询群聊消息已读情况:敬请期待。
6. 能力套件
a. 在开发者自己的页面集成钉钉前端组件
通过使用“酷应用前端套件”JSAPI,在页面内集成“钉钉前端组件”,实现的能力更多、体验更好、更安全、开发成本更低。
在上图的示例中:
- 左一图是开发者在自己的页面中引导用户安装酷应用入群;
- 中间图是在自己的页面中引导用户创建一个群,创建的群会自动安装开发者指定的酷应用;
- 右一图是以用户的身份向群内发消息。
关于钉钉前端组件使用和酷应用能力套件的前瞻性规划,将会在后期分享中详细介绍,敬请期待。
三、 开发演示
需求:做一个简单的群内投票酷应用
1. 创建酷应用
a. 在开发者后台创建酷应用扩展
在应用详情页,单击应用扩展,然后选择开启应用扩展到群会话;
开发者后台 - 应用 - 应用扩展页图示
b. 编辑群应用入口信息
开发者后台 - 应用 - 应用扩展页图示
c. 发布酷应用
可以在等待酷应用发布的同时,进行事件回调操作。
2. 监听酷应用安装事件
a. 订阅回调事件;
点击事件回调进入事件订阅页面,填写相关信息,订阅2个事件:群内安装酷应用和群内卸载酷应用;
开发者后台事件订阅页图示
b. 群内安装酷应用
订阅完成后回到应用扩展页面,这时刚才发布的酷应用还未上架,钉钉为开发者提供了未上架酷应用的群内安装测试方式。
- 在扩展页面群应用信息中,找到酷应用的编码(COOLAPP code)并复制;
- 进入钉钉移动端,打开一个测试群,点击“更多”打开酷应用市场,多次点击“已启用”上面部分进入调试;
- 进入调试功能入口,将复制的COOLAPP编码填入并点击确认,即可在群内安装酷应用;
c. 服务端收到事件回调
由于订阅了群内安装酷应用事件回调,并且设置了回调请求地址是本地启动服务地址,在本地的代码工程中已经通过回调接口监听到安装事件。
3. 设计并发送互动卡片
a. 进入互动卡片搭建平台,开发者可以通过拖拉拽的方式进行卡片设计搭建,完成后点击“发布”;
互动卡片编辑平台图示
b. 发布后会生成卡片ID,调用接口发送互动卡片到群内;
4. 响应互动卡片交互
a. 注册回调地址接口:回调到callbackRouteKey
请求方式:POST
请求地址:
https://oapi.dingtalk.com/topapi/im/chat/scencegroup/interactivecard/callback/register
参数:
- “call back_url”: “http://”卡片点击回调的HTTP地址;
- “callbackRouteKey”:如“yunhuan_vote”,这个由开发者自行设计;
获取一个access_token并复制到注册页面,点击“注册”。
b. 操作互动卡片交互
参数:
- cardTemlateId:刚发布的卡片ID;
- openConversationId:群ID;
- outTrackId:用于更新卡片的唯一ID;
- robotCode:机器人编码,在开发者后台-消息推送-机器人找到;
参数配置完成后点击“发送”,发送互动卡片,发送成功后即可在群内收到卡片;
c. 处理用户交互的回调并更新卡片数据
用户收到卡片后可以选择“接受”或“拒绝”,点击后开发者服务端就会收到回调并更新卡片;
d. 显示卡片实时更新
通过主动调用API实现卡片的更新,更新卡片需要指定outTrackId以及最新的CardData即可。
5. 打开群快捷入口
在钉钉群会话窗口找到群投票按钮,即可打开在开发者后台录入的地址,这个地址和后台录入的dingtalk协议地址对比发现,其中的动参已经转变为实际的群ID了。
四、 最佳实践
1. 产品相关
构建沉浸式体验层面:
a. 使用互动卡片直接交互能力,减少跳转;
b. 页面跳转打开方式用半屏模式,根据信息复杂性设计半屏容器高度;
c. 利用消息的分人可见和卡片的千人前面特性对目标人重点提示,对非重点人简化内容或不可见;
d. 群应用入口地址区分桌面端和移动端配置,用两个页面更好做差异化交互视觉适配;
在钉原生体验质量层面:
a. 回调接口RT控制不超过1200ms ,尽量异步处理回调,如超出比较多钉钉会根据情况限流;
b. 使用互动卡片更新能力和置顶卡片更新能力,减少主动发送新群聊消息的骚扰;
c. 主动推送消息一个群不超过20条/分钟;
d. 置顶卡片提供关闭按钮,让用户按需关闭。
2. 系统相关
在安全可控方面:
a. 保留所有消息的processQueryKey以便随时可撤回消息;
b. 所有发送的图片上传钉钉云,并使用对应的mediaId发出,避免在图片托管在外部图层被错误的删除或修改;
c. 控制页面和功能权限,并为无权者访问时提供申请途径。
在系统稳定性方面:
a. 发送互动卡片时合理使用outTrackId,保证互动卡片的幂等;
b. 互动卡片私有数据的数量单卡片不超过500份,单次更新不超过20份,降低数据扩散比,避免被流控;
c. 监听酷应用从群内停用事件,回收权限,取消绑定群,停止信息往群内的发送。