DingTalk「开发者说」- 酷应用开发之卡片开发和能力套件开放

DingTalk「开发者说」

酷应用开发之卡片开发和能力套件开放

 

摘要：本篇主要讲解钉钉酷应用中卡片的构造、接口和最佳实践，以及卡片未来的规划和能力套件开放。适用对象：产品经理和有技术背景的开发工程师。

 

分享人：假发，酷应用卡片&前端技术负责人

 

视频地址：https://developer.aliyun.com/live/248936

 

正文：

 

一、 卡片构造

 

钉钉提供了两套卡片低代码搭建平台：Ding Card 和 Ding Card Pro，方便开发者快速完成搭建，二者所适用场景有所不同，开发者可以根据自身需求选择合适的方案。

 

1.  Ding Card搭建器使用介绍

 

Ding Card是一个开箱即用的、低成本的卡片开发解决方案。钉钉提供了简单易用且功能强大的卡片搭建器来帮助开发者更好地调试卡片样。

 

Ding Card搭建器组成：

①组件、模板区；②预览区；③代码区

Ding Card网址：https://card.dingtalk.com/card-builder

 

a.  组件区

 

Ding Card搭建器左侧是组件区，点击组件区中的组件，能够快速添加组件到预览区中。组件区提供了丰富的组件能力：

 

• 基础展示组件：文本、图片、视频等；
• 带交互组件：按钮、下拉选择、时间选择等；
• 排内容：双栏文本、图文、文字+按钮等；

 

b.  预览区

 

Ding Card搭建器中间是预览区，能够实时预览最终效果，且可以直接在上面进行交互，同时支持真机预览。

 

• 预览内容可交互：

• 拖拽移动组件位置；
• 删除任意组件；
• 切换桌面、移动模式；
• 切换浅色、深色模式；

 

• 真机预览：

• 一键发送测试卡片到钉钉账号；
• 可在卡片上模拟交互

 

c.  代码区

 

Ding Card搭建器中间是代码区，能够任意修改卡片内容，改动实时生效，同时也能保存当前内容为自己的模板。

 

• 代码区可修改内容包括：

• 编辑任意组件内容；
• 可复制、删除整体卡片内容；
• 提供保存功能，方便二次编辑；

 

• 卡片即 JSON Schema：

• JSON 代码即代表一张卡片；
• JSON 代码可复制、可分享、可复用。

 

d.  模板

 

Ding Card搭建器左侧是除了组件还有模版，包括“官方模板”和“我的模版”。

 

• 我的模板：

• 保存历史模板；
• 可被分享；
• 可二次编辑；

• 官方模板：

• 一系列面向具体场景的精美模板；
• 基于钉钉内部最佳实践整理而成；
• 可快速基于模板二次开发。

 

2.  进阶：使用 Ding Card Pro 搭建卡片模板

 

除了 Ding Card 之外，钉钉还提供了 Ding Card Pro 来满足对布局、样式有定制化需求的开发者。

 

Ding Card Pro搭建器组成：

①组件、模板、数据区；②预览区；③ 属性设置区

Ding Card Pro网址：https://h5.dingtalk.com/interactive-card-builder/index.html

 

Ding Card Pro的性能优势：

 

• 提供大量更加原子化的组件来实现自定义样式；

 

• 提供布局组件来实现特殊的布局结构；

 

• 提供更多可配置的组件属性来实现更加丰富的功能；

 

• 通过模板+数据的方式来实现内容的动态变化;

 

3.  Ding Card vs Ding Card Pro

 

Ding Card和Ding Card Pro在适用场景、组件类型、布局方式和卡片形式上有所不同。

 

 

二、 卡片接口

 

钉钉提供一系列开放 API ，为开发者提供以下卡片能力：

• 卡片发送：卡片搭建好之后，即可通过一个HTTP 接口调用，来完成卡片的发送；
• 卡片更新：开发者可以根据自身业务逻辑，来更新已经发送到钉钉会话里的卡片;
• 事件处理：用户可以在卡片上进行交互，开发者通过注册回调接口，即可感知到用户交互事件，从而执行相关业务逻辑；
• 千人千面：钉钉卡片支持千人千面，为不同人设置不同的卡片内容，实现动态内容。

 

1.  卡片发送

 

钉钉卡片提供 HTTP 形式的开放接口，通过一个简单的 HTTP API 调用，即可完成卡片的发送（也可以使用封装好的 SDK 进行调用）。

POST /v1.0/im/v1.0/robot/interactiveCards/send HTTP/1.1

Host:api.dingtalk.com

x-acs-dingtalk-access-token:token

Content-Type:application/json

{

 "cardTemplateId" : "StandardCard",         // 使用标准卡片进行发送

 "openConversationId" : "conversation_id",  // 目标会话 ID

 "robotCode" : "robot_code",                //发送的机器人 ID

"cardData" : "..."  // 卡片JSON内容，即搭建器产出的JSON结构内容

 ...

}

 

更多可配置参数请查阅 API 文档：https://open.dingtalk.com/document/group/robots-send-interactive-cards

 

2.  事件处理&数据更新

 

钉钉卡片支持用户直接在卡片上进行交互，开发者可以获取到用户所交互的相关上下文，并做出相应的更新，如下图所示：

 

• 用户在卡片上进行交互，如点击按钮；
• 卡片内部发起交互事件请求到钉钉服务端；
• 钉钉服务端调用开发者的回调地址，将交互事件通知到开发者服务端；
• 开发者服务端根据事件类型，执行业务逻辑返回最新数据到钉钉服务端；
• 钉钉服务端通过通用基础设施通道将最新数据同步到端和用户侧；

更多可配置参数请查阅 API 文档：https://open.dingtalk.com/document/group/update-dingtalk-interactive-cards-1

 

3.  千人千面设置

 

钉钉卡片支持千人千面，包括两种方案：

• 发送卡片时指明发送的对象；
• 发送给所有人，但不同人看到的卡片内容不一样。

 

示例：点赞和没有点赞的人看到不同的卡片内容：

 

                         

   没有点过赞的人看到的卡片样式                   点过赞的人看到的卡片样式

 

实现原理：通过在回调接口返回cardData 以及 userPrivateData 的方式，实现数据的千人千面。

 

三、 最佳实践

 

案例：公司餐厅通过在全员群使用健康餐订餐酷应用，解决员工订餐繁琐问题。

 

1、用户使用流程：

 

• 餐厅工作人员在群里打开订餐酷应用，发起当日订餐卡片；
• 员工收到订餐卡片，直接在卡片上选择所需要的菜品，最后点击预订按钮完成订餐；
• 订餐成功后，员工订餐信息实时同步到卡片，显示已订餐内容；
• 用餐完毕后，员工可通过卡片给餐厅工作人员点赞；

 

2、业务逻辑演示

 

a. 卡片发送

 

• 在该订餐酷应用中，有前端应用（frontend）和服务端应用（backend）两个文件夹（demo源代码后续将公开给开发者学习）。

卡片发送

 

• 用户通过酷应用入口发起卡片发送请求，在前端填写信息后，将订餐人信息发送到服务端，调用发送卡片API，传入相关上下文数据；

 

重要字段：

• title:string - 标题
• deadline:Moment - 订餐时间
• maximum:number - 订餐数量
• openConversationId – 参考下图

 

• 服务端对数据进行处理，发送卡片，用户收到卡片信息；

 

• 卡片信息cardData部分代码，可以使用Ding Card模板的生成的JSON schema作为模板，然后进行个性化参数设置；

注：对于初次开发者，建议先做验证，验证通过后，再使用动态化的参数代替。

 

b. 卡片交互/更新

卡片更新

 

• 用户在订餐卡片提交订餐信息；
• 服务器端记录订餐信息，构造最新数据并返回钉钉；
• 钉钉平台进行数据处理，推送最新卡片内容；
• 用户在钉钉客户端看到最新订单信息，以及自身的订餐信息。

 

重要字段：

• outTrackId：cardBizId
• Location：用户取餐位置信息
• userPrivateData：构造订餐人自有信息
• updateCard：有新用户预定，在群内进行广播

 

c.事件处理/千人千面

 

• 用户在卡片上给健康餐点赞；
• 钉钉卡片接受用户点赞行为，调用开发者卡片回调地址
• 开发者处理用户点赞行为，获取最新点赞数据，返回千人千面数据；
• 钉钉卡片接收回调最新数据，推送最新卡片内容；
• 用户看到千人千面的点赞效果；

 

 

重要字段：

• userPrivateData：订餐人自有信息
• like/dislike：点赞/不满意

 

四、 卡片未来规划

 

• 丰富组件能力升级

钉钉卡片会持续不断地提供更多实用的组件，除了基础组件之外，未来也会提供一系列高级组件，如图表、表格等；同时未来也会开放自定义组件的能力，让企业能够创建满足自身需求的自定义组件；

• 模板市场

钉钉的生态少不了三方开发者的参与，为了让开发者开发的卡片模板能够尽可能复用和流通，未来会提供模板市场，让开发者能够以更低的成本来开发卡片，同时激励优秀开发者持续开发优质卡片模板；

• 多场域

钉钉卡片除了可以投放在群聊中，以群卡片以及群置顶的方式存在之外，未来也会提供多场域的能力，让同一个卡片既能在群里面使用，同时也能在钉钉其他重要场景，如日程、文档等上使用，做到多场域协作。

 

五、 能力套件开放

 

酷应用能力套件是一系列可与钉钉系统交互的能力，开发者通过在前端接入 JSAPI，即可给用户提供能力更强、体验更好的功能。

                       

         添加酷应用到群聊              以用户身份发消息            创建群聊并安装酷应用

 

1、能力接入示例：添加酷应用到群

 

示例：添加酷应用到群

 

2、示例代码：

 

import 'dingtalk-jsapi/entry/union';

import { installCoolAppToGroup } from 'dingtalk-jsapi/plugin/coolAppSdk';

 

installCoolAppToGroup({

 coolAppCode: 'cool_app_code', // 要安装的酷应用标识

 clientId: 'client_id', // 酷应用归属的应用标识

 corpId: 'corp_id', // 要安装酷应用的组织id

}).then(res => {

 if (res?.code === '0') {

   // 安装成功

 }

}).catch(e => {

 // 用户主动退出安装

});

将酷应用安装到其他群

 

3、重要参数：

• Button：添加应用到其他群内的按钮

• useCallback

 

4、逻辑步骤：

 

• 用户触发酷应用入群动作；
• 传递酷应用相关信息；
• 展示选群列表和酷应用信息；
• 选择群聊并确认安装；
• 将酷应用安装到群聊；
• 返回安装结果；
• 展示安装结果；
• 返回安装信息；

 

5、更多场景即将开放

 

围绕酷应用在群聊、工作台、文档等高频协作场景，钉钉将基于 JSAPI 开放更多一方能力套件，帮助酷应用更好的与钉钉产品融合，为用户提供沉浸式的使用体验，让信息围绕高频场景和具体事项做实时高效协同。

 

 

六、 Q&A

  

Q：Ding Card和Ding Card Pro的入口在哪里？

A：Ding Card Pro在开发者后台已经有入口了，Ding Card的入口在本文第一部分已经列出，后续也会同步到开发者后台。

 

Q：钉钉卡片的能力套件在哪里有文档可以查看？

A：目前刚开发了第一期能力套件，相关文档将于近期上线。大家可以关注开发者服务窗的推送信息。

 

Q：钉钉酷应用的一些案例代码是否会开源？

A：会的，大家可以关注开发者服务窗，酷应用的相关代码和文档将会陆续同步出来。

 

Q：酷应用的数据循环要如何来做？

A：在Ding Card里，需要根据企业自身的业务诉求，将相关参数做一些动态化的逻辑即可；在Ding Card Pro里，可以在组件中选择循环容器，配套去创建一个变量，这里需要做一些包装，可以参考相应的demo代码。

 

Q：钉钉卡片如何支持所有格式？

A：在Ding Card组件中，可以选择“富文本”组件，参考相关开发文档，基本可以和大部分Markdown的渲染能力对齐，后续根据用户需求再进行迭代和调整。