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. 监听酷应用从群内停用事件，回收权限，取消绑定群，停止信息往群内的发送。
