Dingtalk: Card Development and Capability Kit Open

Abstract: This article mainly explains the structure, interface and best practice of the card in the DingTalk application, as well as the future planning and capability suite opening of the card. Target audience: Product managers and development engineers with technical backgrounds.

Shared by: Wig, Cool Application Card & Head of Front-end Technology

Video address: https://developer.aliyun.com/live/248936

text:

1. Card structure

DingTalk provides two sets of card low-code construction platforms: Ding Card and Ding Card Pro, which are convenient for developers to quickly complete the construction. The two applicable scenarios are different, and developers can choose the appropriate solution according to their own needs.

1. Introduction to Ding Card Builder

Ding Card is an out-of-the-box, low-cost card development solution. DingTalk provides an easy-to-use and powerful card builder to help developers better debug card patterns.

The Ding Card builder consists of:
①Component and template area; ②Preview area; ③Code area
Ding Card website: https://card.dingtalk.com/card-builder

a. Component area

On the left side of the Ding Card builder is the component area. Click the component in the component area to quickly add the component to the preview area. The component area provides rich component capabilities:

• Basic display components: text, pictures, videos, etc.;
• With interactive components: buttons, drop-down selection, time selection, etc.;
• Arrange content: double-column text, graphic, text + button, etc.;

b. Preview area

In the middle of the Ding Card builder is the preview area, which can preview the final effect in real time, and can interact directly on it, while supporting real machine preview.

• The preview content is interactive:
• Drag to move the component position;
• remove any component;
• Switch between desktop and mobile modes;
• Switch between light and dark modes;

• Real device preview:
• Send test card to DingTalk account with one click;
• Simulate interactions on cards

c. Code area

In the middle of the Ding Card builder is the code area, which can modify the content of the card arbitrarily, and the changes will take effect in real time. At the same time, it can also save the current content as its own template.

• The modifiable contents of the code area include:
• Edit any component content;
• Copy and delete the entire card content;
• Provides a save function to facilitate secondary editing;

• Cards are JSON Schema:
• The JSON code represents a card;
• JSON code can be copied, shared and reused.

d. Template

On the left side of the Ding Card builder, there are templates in addition to components, including "Official Templates" and "My Templates".

• My template:
• save historical templates;
• can be shared;
• Can be edited twice;
• Official Template:
• A series of beautiful templates for specific scenarios;
• Organized based on internal best practices of DingTalk;
• Quick secondary development based on templates.

2. Advanced: Use Ding Card Pro to build a card template

In addition to Ding Card, Dingding also provides Ding Card Pro to meet the needs of developers with customized layout and style.

The Ding Card Pro builder consists of:
① Component, template, data area; ② Preview area; ③ Property setting area
Ding Card Pro URL: https://h5.dingtalk.com/interactive-card-builder/index.html

Performance advantages of Ding Card Pro:

• Provides a large number of more atomic components to implement custom styles;

• Provide layout components to implement special layout structures;

• Provide more configurable component properties to achieve richer functions;

• Realize dynamic changes of content through templates + data;

3. Ding Card vs Ding Card Pro

Ding Card and Ding Card Pro differ in applicable scenarios, component types, layout methods and card forms.

builder
Applicable scene
component type
layout
card form
Ding Card
Open to all developers, out-of-the-box, low development cost, and suitable for scenarios without customization requirements. The official provides a series of templates for specific scenarios to help developers access more easily. Ding Card is recommended if there are no special needs.
block component
top and bottom layout
JSON Schema
Ding Card Pro
For advanced developers and developers with strong customization requirements, it has rich and powerful capabilities, supports custom layouts and more refined component attribute configuration, and has a certain threshold for getting started.
Atomic components
up and down
about
Nested layout
template + data

2. Card interface

DingTalk provides a series of open APIs to provide developers with the following card capabilities:
• Card sending: After the card is set up, it can be called through an HTTP interface to complete the card sending;
• Card update: Developers can update cards that have been sent to DingTalk sessions according to their own business logic;
• Event processing: Users can interact on the card, and developers can sense user interaction events by registering a callback interface, thereby executing related business logic;
• Thousands of people and thousands of faces: Dingding cards support thousands of people and thousands of faces, and set different card content for different people to realize dynamic content.

1. Card sending

DingTalk Card provides an open interface in the form of HTTP, and the card can be sent through a simple HTTP API call (you can also use the packaged SDK to call).
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", // send using standard card
"openConversationId" : "conversation_id", // target session ID
"robotCode" : "robot_code", //The robot ID sent
"cardData" : "..." // Card JSON content, that is, the JSON structure content generated by the builder
...
}

For more configurable parameters, please refer to the API documentation: https://open.dingtalk.com/document/group/robots-send-interactive-cards

2. Event processing & data update

The DingTalk card supports users to interact directly on the card. Developers can obtain the relevant context of the user interaction and make corresponding updates, as shown in the following figure:

• The user interacts on the card, such as clicking a button;
• The card initiates an interaction event request to the DingTalk server;
• The DingTalk server calls the developer's callback address to notify the developer server of interactive events;
• According to the event type, the developer server executes business logic to return the latest data to the DingTalk server;
• The DingTalk server synchronizes the latest data to the end and user side through a common infrastructure channel;
For more configurable parameters, please refer to the API documentation: https://open.dingtalk.com/document/group/update-dingtalk-interactive-cards-1

3. Thousands of people and thousands of faces

Dingding cards support thousands of people and thousands of faces, including two schemes:
• Indicate who to send the card to when sending the card;
• Send to everyone, but different people see the card differently.

Example: People who like and don't see different card content:


Card style seen by people who have not liked Card style seen by people who have liked

Implementation principle: By returning cardData and userPrivateData in the callback interface, the data can be widely used.

3. Best Practices

Case: The company's restaurant solved the cumbersome problem of employees ordering meals by using the cool app for healthy meal ordering in the entire staff group.

1. User process:

• The restaurant staff opens the ordering cool app in the group and initiates the ordering card of the day;
• The employee receives the order card, directly selects the desired dishes on the card, and finally clicks the reservation button to complete the order;
• After the meal ordering is successful, the employee meal ordering information will be synchronized to the card in real time, showing the ordered meal content;
• After the meal, employees can like the restaurant staff through cards;

2. Business logic demonstration

a. Card sending

• In this cool meal ordering application, there are two folders: front-end application (frontend) and server-side application (backend) (the demo source code will be released to developers to learn later).
card sending

• The user initiates a card sending request through the cool application portal, fills in the information on the front end, sends the orderer information to the server, calls the sending card API, and passes in the relevant context data;

Important fields:
• title:string - the title
• deadline:Moment - order time
• maximum:number - the number of meals ordered
• openConversationId – refer to the figure below

• The server processes the data, sends the card, and the user receives the card information;

• For the code of the cardData part of the card information, you can use the generated JSON schema of the Ding Card template as a template, and then set personalized parameters;
Note: For first-time developers, it is recommended to do verification first, and then use dynamic parameters instead.

b. Card interaction/update
Card update

• The user submits the order information on the order card;
• The server records the order information, constructs the latest data and returns to DingTalk;
• Dingding platform performs data processing and pushes the latest card content;
• Users can see the latest order information and their own order information on the DingTalk client.

Important fields:
• outTrackId: cardBizId
• Location: the location information of the user to pick up the meal
• userPrivateData: constructs the orderer's own information
• updateCard: there is a new user reservation, broadcast in the group

c. Incident handling / thousands of people

• User likes the healthy meal on the card;
• Dingding card accepts user likes and calls the developer card callback address
• The developer handles the user's like behavior, obtains the latest like data, and returns the data of thousands of people and thousands of faces;
• Dingding card receives and calls back the latest data and pushes the latest card content;
• Users see thousands of likes from thousands of people;


Important fields:
• userPrivateData: the orderer's own information
• like/dislike: like/dislike

4. Card future planning

• Rich component capability upgrade
DingTalk will continue to provide more practical components. In addition to basic components, it will also provide a series of advanced components in the future, such as charts, tables, etc. At the same time, it will also open up the ability to customize components in the future, allowing enterprises to create Custom components to meet your own needs;
• Template Market
The ecology of DingTalk is inseparable from the participation of three-party developers. In order to allow the card templates developed by developers to be reused and circulated as much as possible, a template market will be provided in the future, so that developers can develop cards at a lower cost and encourage excellent development. Continue to develop high-quality card templates;
• Multi-field
In addition to the DingTalk cards that can be placed in group chats and exist in the form of group cards and group tops, DingTalk will also provide multi-field capabilities in the future, so that the same card can be used both in groups and in DingTalk. It can be used in other important scenarios, such as schedules, documents, etc., to achieve multi-field collaboration.

5. Capability Suite Open

Cool Application Capability Suite is a series of capabilities that can interact with the DingTalk system. By accessing JSAPI on the front end, developers can provide users with functions with stronger capabilities and better experience.

Add cool apps to group chats Send messages as a user Create group chats and install cool apps

1. Example of capability access: adding cool apps to the group

Example: Adding Cool Apps to a Group

2. Sample code:

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

installCoolAppToGroup({
coolAppCode: 'cool_app_code', // cool app ID to install
clientId: 'client_id', // App ID to which cool apps belong
corpId: 'corp_id', // id of the organization to install cool apps
}).then(res => {
if (res?.code === '0') {
// Successful installation
}
}).catch(e => {
// The user actively exits the installation
});
Install cool apps to other groups

3. Important parameters:
• Button: add a button that applies to other groups
• useCallback

4. Logical steps:

• Users trigger cool apps to join the group;
• pass Diku application related information;
• Display the list of selected groups and cool application information;
• Select Group Chat and confirm installation;
• Install cool apps to group chats;
• return installation results;
• show the installation results;
• return installation information;

5. More scenes will be opened soon

Focusing on high-frequency collaboration scenarios such as group chats, workbenches, and documents, DingTalk will open up more capability suites based on JSAPI to help cool apps better integrate with DingTalk products and provide users with an immersive experience. Let information be coordinated in real time and efficiently around high-frequency scenarios and specific matters.


6. Q&A

Q: Where is the entrance to Ding Card and Ding Card Pro?
A: Ding Card Pro already has an entry in the developer's backend. The Ding Card's entry is listed in the first part of this article, and will be synchronized to the developer's backend in the future.

Q: Where can I find the documentation for the ability kit of Dingding cards?
A: The first phase of the capability kit has just been developed, and the relevant documents will be launched in the near future. You can follow the push information of the developer service window.

Q: Will some case codes of Dingdingku applications be open sourced?
A: Yes, you can pay attention to the developer service window, the relevant code and documents of the cool application will be synchronized one after another.

Q: How to do the data loop of the cool application?
A: In Ding Card, you need to do some dynamic logic for the relevant parameters according to the business requirements of the enterprise; in Ding Card Pro, you can select the loop container in the component, and create a variable together, here you need to do For some packages, you can refer to the corresponding demo code.

Q: How does DingTalk support all formats?
A: In the Ding Card component, you can select the "Rich Text" component, refer to the relevant development documents, which can basically be aligned with the rendering capabilities of most Markdown, and then iterate and adjust according to user needs.