Create a shortcut entry (group plugin)

This article describes how to create a shortcut entry.

​

What is a shortcut entry (group plugin)

When a user clicks a plugin entry inside a group, the relevant group parameters are carried along, allowing developers to determine who clicked which specific plugin in which group at what time. Based on this, solution providers can deliver highly intelligent and clearly targeted business services.

1. Sign in to the DingTalk Developer Console.
2. On the Developer Console page, select Scenario group and click Create group plugin.
3. Create a group plugin, click Create, and wait for approval. Note
   • Approval is completed within 12 hours on business days.
   Different group plugin links can be configured. The link can be opened in the DingTalk workbench, sidebar, external browser, and more:

   Open method	Link configuration
   Open the group plugin in the DingTalk workbench	dingtalk://dingtalkclient/action/openapp?corpid=dingxxxxxxxxxxx&container_type=work_platform&app_id=0_140444xxxxx&redirect_type=jump&redirect_url=https%3A%2F%2Fding-doc.dingtalk.io%2F
   Open the group plugin in the sidebar	dingtalk://dingtalkclient/action/openapp?corpid=dingxxxxxxxxxxx&container_type=slide_panel&app_id=0_140444xxxxx&redirect_type=jump&redirect_url=https%3A%2F%2Fding-doc.dingtalk.io%2F
   Open the group plugin in an external browser	dingtalk://dingtalkclient/action/openapp?corpid=dingxxxxxxxxxxx&container_type=browser&app_id=0_140444xxxxx&redirect_type=jump&redirect_url=https%3A%2F%2Fding-doc.dingtalk.io%2F

​

Build the shortcut entry link

A shortcut entry (group plugin) is a DingTalk link with business capabilities. Developers must assemble a shortcut entry link based on the actual scenarios of their micro app and the specific needs of users in the group. The shortcut entry name supports up to four characters. The shortcut entry link offers extensive capabilities, but developers must assemble them through link parameters. For example, the open method on the mobile side (push page, pop page, etc.) and the page navigation logic on the PC side (open a new container or slide the page left) are all implemented through link parameter configuration.

• Redirect to an H5 page link (sidebar / container slide-out) Example:
  dingtalk://dingtalkclient/page/link?dd_mode=push&pc_slide=true&url=http%3a%2f%2fomsdevdingtalkf.zjk.taeapp.com%2findex.html%3fcorpid%3d$CORPID$%26dd_nav_bgcolor%3dffff943e%2f%23%2fgroup-plugin%3fcorpid%3d$CORPID$%26openConversationId%3d$DOUBLE_ENCCID$%26dd_nav_bgcolor%3dffff943e%26pluginType%3d3%26appid%3d6397
  
  Parameter descriptions:

  Parameter	Description
  url	The page URL. URL encoding is required.
  dd_mode	Used on iOS. - push: pushes a container from left to right on iOS. - present: pops a container from bottom to top on iOS.
  pc_slide	When pc_slide=true, the URL opens inside the app on the PC side.

• Redirect to a micro app openapp (such as workbench, browser, or left-slide panel) Example:
  dingtalk://dingtalkclient/action/openapp?corpid=$CORPID$&container_type=work_platform&app_id=3204&redirect_type=emit_params&params=&redirect_url=https%3A%2F%2Ftestt2.wmnetwork.cc%2Fmanage%2Findex%3Fmid%3Dwfp40mx9
  
  Parameter descriptions:

  Parameter	Description
  container_type	The container in which the page is displayed: - browser: browser. - slide_panel: left-slide panel. - work_platform: workbench.
  corpid	The organization ID.
  app_id	- For a Third-party enterprise app, fill in the appId. See how to view the appId. - For an internal app, fill in 0_agentId, which is composed of the digit 0, an Underline, and the agentId. The agentId can be viewed in the app details.
  redirect_type	The redirect type: - jump: opens the redirect_url directly. - emit_params: uses the event-emitting method.
  params	Parameters. When opening for the first time, add this parameter to the parameter list of the redirect URL.
  redirect_url	The redirect URL. URL encoding is required.
  slide_panel_option	Parameters for the left-slide panel, exclusive to the PC version. For example: {"width":500,"showAppPage":true} (width is the sidebar width, and showAppPage indicates whether to show the web page).

• Redirect to a mini program
  1. Common parameters (supported by both open_micro_app and open_mini_app)

     Parameter	Required	Description
     appId	Choose one between appId and agent_id. If both are present, app_id takes precedence.	The micro app ID. Note that this is not the mini program ID. ISV apps use this ID.
     page	No	The page path of the mini program. GET parameters can be appended. Defaults to the mini program home page.
     query	No	The startup parameters of the mini program, which can be obtained in the App.onLaunch / onShow callback. When the mini program is started, the Client-side adds the corpId parameter by default. Therefore, the business side cannot set corpId, as it will be overwritten.
     containerType	No	A PC-only parameter. The following options are available: - browser: browser. - slide_panel (Default): left-slide panel. - work_platform: workbench. - mobile: redirects to the mobile side.
     title	No	A PC-only parameter used to display the title.
     source	No	The Source (used only when the package needs to be pulled from the Server-side): - debug: real-device debug version. - trial: trial version.
     version	No	The version number.
     ddMode	No	The transition mode for launching the mini program. - push: push mode. - present: pop-up mode. - float: floating layer mode. - pop: pop view mode. If not specified, the Client-side launches using the default transition mode. Grayscale release starts in Client-side v4.5.8. float and pop start grayscale release in v4.6.35 (20190624).
     mainTask	No	Required only for the Android client. The value is “true” or “false”, defaulting to false. If set to “true”, the mini program runs in the same Task as the DingTalk main Task and is no longer kept alive. Supported in Client-side v4.6.3.
     ddJointNavi	No	Configures the navigation bar style. If configured, it overrides the ddMode logic. android & iOS: “0”, “1”, or “1001”. - 0: legacy navigation bar. - 1: new navigation bar. - 1001: navigation bar with only the back button and title.
     keepAlive	No	Can be set to true or false, defaulting to true. If mainTask is set to true, this key is ignored.
     ddFocus	No	Can be set to true or false, defaulting to true. If set to true, the container disables internal elements from gaining focus during initialization.
     ddEnableWX	No	Whether Weex rendering is supported. When Weex rendering is supported, if the page is configured with Weex rendering mode, Weex can be launched to load the page.
     ddForceAsync	No	Whether to force asynchronous startup. With forced asynchronous startup, if a local offline package exists, synchronous updates are not triggered and the app is started with forced asynchronous updates (to address startup issues in offline environments).
     animated	No	Value is 0 or 1. Indicates whether a transition animation is used for asynchronous startup (ignored for synchronous startup scenarios). Defaults to 1. Available since v4.6.36.

​

Parameters supported when ddMode=float (floating window)

​

Parameters supported when ddMode=pop (pop layer)

2. Open a micro app scheme (scheme exclusive to enterprise mini programs) Scheme: dingtalk://dingtalkclient/action/open_micro_app Basic parameters are the same as in the common parameters list. The grayscale control logic should be placed in the handler of this scheme. ​

   Parameter	Required	Description
   corpId	Yes	The organization ID. Important This parameter has high priority and overrides corpId in the query.
   appId	Choose one between appId and agent_id. If both are present, appid takes precedence.	The micro app ID. Note that this is not the mini program ID. ISV apps use this ID.
   agentId	Choose one between agentId and app_id.	The agent_id of the internal app.
   fallbackUrl	No. Not required for micro apps that do not support H5. Required for micro apps in the grayscale phase between H5 and mini programs.	The H5 address. Micro apps that do not support mini programs use this address directly.
   ddFocus	No	If set to true, the container disables internal elements from gaining focus during initialization. Defaults to false.
   ddForceAsync	No	Whether to force asynchronous startup. With forced asynchronous startup, if a local offline package exists, synchronous updates are not triggered and the app is started with forced asynchronous updates (to address startup issues in offline environments).

   PC-side test cases:
   • Open a URL in the slide panel without a title.
     dingtalk://dingtalkclient/action/open_micro_app?corpId=11233&app_id=123&fallback_url=https%3A%2F%2Fwww.dingtalk.io&container_type=slide_panel
     
   • Open a URL in the slide panel without a title.
     dingtalk://dingtalkclient/action/open_micro_app?corpId=11233&app_id=123&fallback_url=https%3A%2F%2Fwww.dingtalk.io
     
   • Open a URL in the browser.
     dingtalk://dingtalkclient/action/open_micro_app?corpId=11233&app_id=123&fallback_url=https%3A%2F%2Fwww.dingtalk.io&container_type=browser
     
   • Open a URL in the slide panel with a title.
     https://www.dingtalk.io?micro_app_scheme=dingtalk%3A%2F%2Fdingtalkclient%2Faction%2Fopen_micro_app%3F%0AcorpId%3D11233%26app_id%3D123%26container_type%3Dslide_panel%26title%3Dtest_title
     
   • Open a URL in the browser.
     https://www.dingtalk.io?micro_app_scheme=dingtalk%3A%2F%2Fdingtalkclient%2Faction%2Fopen_micro_app%3F%0AcorpId%3D11233%26app_id%3D123%26container_type%3Dbrowser%26title%3Dtest_title
     
3. Launch a mini program scheme (scheme exclusive to personal mini programs) Scheme: dingtalk://dingtalkclient/action/open_mini_app Basic parameters are the same as in the common parameters list.

   Parameter	Required	Description
   miniAppId	Yes	The mini program ID.

4. Mini program debug scheme Scheme: dingtalk://dingtalkclient/action/dev_mini_app Mainly used to debug mini programs and develop with the appx framework. Mini programs opened in this way launch the main document directly through the URL. The package management process is not entered, and the keep-alive logic is not triggered. miniAppId is used only for interface verification and similar purposes.

​

Important

The parameters have all been encoded. Decode them before use.

​

How to obtain source group information through the link

• Specify a special open method. A shortcut entry (group plugin) is a DingTalk link with business capabilities. Developers must assemble a group plugin link based on the actual scenarios of their micro app and the specific needs of users in the group. The plugin name supports up to four characters. The plugin link offers extensive capabilities, but developers must assemble them through link parameters. For example, the open method on the mobile side (push page, pop page, etc.) and the page navigation logic on the PC side (open a new container or slide the page left) are all implemented through link parameter configuration. The following uses the shortcut entry for a project group as an example to explain in detail how a shortcut entry link is assembled. <dingtalk://dingtalkclient/page/link?url=https%3a%2f%2fding-doc.dingtalk.io%2fdoc%23%2fpqkq0u%2feluagw%2f$CORPID$%2f$DOUBLE_ENCCID$>
  • Developer’s target page address: https%3a%2f%2fding-doc.dingtalk.io%2fdoc%23%2fpqkq0u%2feluagw
    • When you use the DingTalk unified redirect protocol, this part is used as a parameter of the “DingTalk unified redirect protocol” address, so URL encoding is required.
    • When you do not use the DingTalk unified redirect protocol, you can use the original URL directly as the shortcut entry address. URL encoding is not required.
  • DingTalk unified redirect protocol (optional) dingtalk://dingtalkclient/page/link?url=
    • This part determines how your specified page is opened. Currently supported methods include “open in browser”, “open in sidebar”, and more. The path of the unified redirect protocol differs for each method.
    • Some unified redirect protocol paths are available only on certain platform clients. For example, “open in sidebar” is available only on the PC and Mac clients.
  • Shortcut entry address dynamic parameters (optional) $CORPID$ $DOUBLE_ENCCID$
    • When these dynamic parameters are set, the corresponding parts in the URL are replaced with the group Context information (such as corpId and openConversationId) when a user clicks the shortcut entry to access the developer’s address. The currently supported dynamic parameters are as follows:

      Parameter	Description
      $CORPID$	Dynamically replaced with the Organization ID (corpId).
      $ENCCID$	Dynamically replaced with the open group ID (openConversationId). Use this dynamic parameter only when the DingTalk unified redirect protocol is not used.
      $DOUBLE_ENCCID$	Dynamically replaced with the open group ID (openConversationId). The difference is that it is URL-encoded twice, which is used for URL decoding during multiple protocol pass-through redirects. Use this dynamic parameter only when the DingTalk unified redirect protocol is used.

      The reason for the double URL encoding/decoding of $DOUBLE_ENCCID$ is as follows: DingTalk uses an internal protocol with the “dingtalk://” prefix, which requires one round of encoding to be parsed. The business HTTPS protocol passed through after the URL parameters also requires another round of encoding/decoding when consumed by the downstream container. Because the consumer needs to perform two rounds of decoding, two rounds of encoding are required when generating the URL. Example of generating the URL: urlencode (DingTalk URL?xxx=xxx & url = urlencode (business URL)) Example of parsing the URL: a. urldecode (DingTalk URL) -> get the business URL; b. urldecode (business URL) -> get the usable parameters.