创建快捷入口（群插件）

本文介绍如何创建快捷入口。

​

什么是快捷入口（群插件）

用户在群内点击插件入口时，将会带上群的相关参数，开发者将据此确定是谁在哪个群内在什么时间点击了哪个具体插件。以此，产品方案商能够实现高度智能化和指向明确的业务服务。

1. 登录钉钉开发者后台。
2. 在开发者后台页面，选择场景群，点击创建群插件。
3. 新建群插件并点击新建，等待审核通过。 说明
   • 审核时效，工作日12小时内审批完成。
   设置不同的群插件链接不同，支持在钉钉工作台、侧边栏、外部浏览器等打开链接：

   打开方式	设置链接
   在钉钉工作台打开群插件	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
   侧边栏打开群插件	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
   外部浏览器打开群插件	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

​

构造快捷入口链接

快捷入口（群插件）为一个具有业务能力的钉钉链接，开发者需要基于自己微应用的实际场景和在群内用户使用时的具体需求来拼装一个快捷入口链接。 快捷入口名字最多支持4个字符，快捷入口链接所具有的能力非常多，但需要开发者通过链接参数来组装。例如从移动端页面的打开方式(推入页面、弹出页面等)，到PC端的页面跳转逻辑(打开新容器或者左滑页面)，都是通过链接参数的配置来实现的。

• 跳转到H5页面 link(侧边栏/容器划出) 示例：
  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
  
  参数说明：

  参数	说明
  url	页面URL，必须做urlencode。
  dd_mode	iOS端使用。 - push：iOS从左向右推入一个容器 - present：iOS从下向上弹出一个容器
  pc_slide	pc_slide=true 时，PC 端会在应用内打开这个 URL。

• 跳转到微应用 openapp(如工作台、浏览器、左划面板) 示例：
  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
  
  参数说明：

  参数	说明
  container_type	展现的容器： - browser: 浏览器 - slide_panel：左划面板 - work_platform：工作台
  corpid	企业的corpid。
  app_id	- 第三方企业应用 应填写appId，appId查看。 - 企业自建应用 应填写0_agentId，由数字0、下划线和agentId拼接组成。agentId可在应用详情中查看。
  redirect_type	跳转类型： - jump：直接打开redirect_url - emit_params: 发射事件的方式
  params	参数，首次打开要将此参数加到跳转url的参数列表内。
  redirect_url	跳转url，需要urlEncode。
  slide_panel_option	左划面板的参数 PC 版独有。例如：{"width":500,"showAppPage":true}（width 为侧边栏宽度，showAppPage 为是否显示网页）

• 跳转到小程序
  1. 通用参数 (open_micro_app 和 open_mini_app 都支持)

     参数	是否必填	说明
     appId	和 agent_id 二选一，如果同时存在，优先用 app_id	微应用id，注意不是小程序ID，isv应用使用此id。
     page	否	小程序的page地址，可以加get参数。默认为小程序首页。
     query	否	小程序的启动参数，可以在 App 的 onLaunch / onShow 回调里获取。 启动小程序时，客户端默认加上corpId参数，所以业务方不可以填corpId，会被覆盖掉。
     containerType	否	PC 端专用参数，有以下几个选项： - browser: 浏览器 - slide_panel（默认值）：左划面板 - work_platform：工作台 - mobile: 引导到移动端
     title	否	PC端专用参数，用来显示title。
     source	否	来源（只用于需要从服务端拉取包时用）： - debug：真机调试版 - trial：体验版
     version	否	版本号。
     ddMode	否	小程序启动转场方式。 - push： 推入方式 - present：弹出方式 - float：浮层方式 - pop：弹框方式(pop view) 如果不传，客户端按照默认转场方式启动。客户端v4.5.8版本开始灰度。float和pop，v4.6.35(20190624)版本开始灰度
     mainTask	否	仅安卓客户端需要。 取值为“true”或者“false”，默认false。 如果传值为“true”,表示和钉钉主Task一个Task，不再保活 客户端4.6.3版本支持
     ddJointNavi	否	配置导航栏样式。如果配置这个会覆盖ddMode的逻辑。 android & iOS：“0”或者“1”、“1001”。 - 0：老的导航栏 - 1：新的导航栏 - 1001：只有返回键和标题的导航栏
     keepAlive	否	可配置true或者false，默认true。 如果配置了mainTask 为true，不再处理这个key。
     ddFocus	否	可配置true或者false，默认true。 如果配置为true，容器会在初始化时先禁止内部元素获取焦点的行为。
     ddEnableWX	否	是否支持weex渲染。 支持weex渲染的情况下，如果页面有配置weex渲染模式，则可以启动weex加载页面
     ddForceAsync	否	是否强制异步启动。 强制异步启动时，如果本地有离线包，则不会触发同步更新，强制异步更新启动（解决断网环境启动问题）。
     animated	否	取值0和1，异步启动是否有转场动画(同步启动场景忽略此参数)，默认1。 v4.6.36版本上线。

​

ddMode=float 浮窗时，可支持的参数

​

ddMode=pop 弹层时，可支持的参数

2. 打开微应用 scheme（企业小程序专用 scheme） scheme：dingtalk://dingtalkclient/action/open_micro_app 基本参数同通用参数列表。 灰度控制逻辑应该放在这个 scheme 的 handler 里 ​

   参数	是否必填	说明
   corpId	是	企业的corpid。 重要 优先级高，会覆盖掉query里的corpId。
   appId	和 agent_id 二选一 如果同时存在，优先用appid	微应用id，注意不是小程序ID，isv应用用此id。
   agentId	和 app_id 二选一	企业自建应用的agent_id。
   fallbackUrl	否 不支持 H5 的微应用，不用填此参数，在 H5 和小程序灰度阶段的，必填此参数	H5 的地址，不支持小程序的微应用，直接使用这个地址。
   ddFocus	否	如果配置为true，容器会在初始化时先禁止内部元素获取焦点的行为，默认为false。
   ddForceAsync	否	是否强制异步启动。强制异步启动时，如果本地有离线包，则不会触发同步更新，强制异步更新启动（解决断网环境启动问题）。

   PC端测试case：
   • 在slide panel打开url，无title
     dingtalk://dingtalkclient/action/open_micro_app?corpId=11233&app_id=123&fallback_url=https%3A%2F%2Fwww.dingtalk.io&container_type=slide_panel
     
   • 在slide panel打开url，无title
     dingtalk://dingtalkclient/action/open_micro_app?corpId=11233&app_id=123&fallback_url=https%3A%2F%2Fwww.dingtalk.io
     
   • 在browser打开url
     dingtalk://dingtalkclient/action/open_micro_app?corpId=11233&app_id=123&fallback_url=https%3A%2F%2Fwww.dingtalk.io&container_type=browser
     
   • 在slide panel打开url，有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
     
   • 在browser打开url
     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. 开启小程序schema (个人小程序专用 scheme) scheme：dingtalk://dingtalkclient/action/open_mini_app 基本参数同通用参数列表。

   参数	是否必填	说明
   miniAppId	是	小程序id。

4. 小程序调试scheme scheme：dingtalk://dingtalkclient/action/dev_mini_app 主要用于调试小程序，以及appx框架开发。通过此方式打开的小程序，直接通过url启动主文档。不会进入包管理流程，也不会触发保活逻辑。miniAppId仅用于做接口校验等。

​

重要

参数都已经过encode，注意解码。

​

如何通过链接获取来源群信息

• 指定特殊打开方式 快捷入口（群插件）为一个带有业务能力的dingtalk链接，开发者需要基于自己微应用的实际场景和在群内用户使用时的具体需求来拼装一个群插件链接出来。插件名字最多支持4个字，插件链接里面所具有的能力非常多，但需要开发者通过链接参数来组装。例如从移动端页面的打开方式(推入页面、弹出页面等)，到PC端的页面跳转逻辑(打开新容器或者左滑页面)，都是通过链接参数的配置来实现的。 以下以项目群的快捷入口为例，详细说明一个快捷入口链接是如何拼装出来的。 <dingtalk://dingtalkclient/page/link?url=https%3a%2f%2fding-doc.dingtalk.io%2fdoc%23%2fpqkq0u%2feluagw%2f$CORPID$%2f$DOUBLE_ENCCID$>
  • 开发者的目标页面地址：https%3a%2f%2fding-doc.dingtalk.io%2fdoc%23%2fpqkq0u%2feluagw
    • 当你使用了钉钉统一跳转协议，这一部分将作为“钉钉统一跳转协议”地址的入参，所以需要经过urlEncode。
    • 当你没有使用钉钉统一跳转协议，可直接使用原始Url作为快捷入口的地址。不需要urlEncode。
  • **钉钉统一跳转协议（可选）**dingtalk://dingtalkclient/page/link?url=
    • 这个部分决定了会以什么方式打开你指定的页面。目前支持的有“浏览器打开”、“侧边栏打开”等，每种方式对应的统一跳转协议的path不一样。
    • 部分统一跳转协议path，只在部分平台客户端可用，比如侧边栏打开只在pc和mac端可用。
  • 快捷入口地址动参（可选） $CORPID$ $DOUBLE_ENCCID$
    • 设置了这个动参，当用户点击这个快捷入口访问开发者的地址时，url里的这部分动参可以替换为群上下文的信息，比如corpid和 openConversationId。 目前可支持的动参如下：

      参数	说明
      $CORPID$	动态替换企业ID（corpId）
      $ENCCID$	动态替换成开放群ID（openConversationId）。 仅当不使用钉钉统一跳转协议时使用该动参。
      $DOUBLE_ENCCID$	动态替换成开放群ID（openConversationId），区别在于二次urlencode，用于多次协议透传跳转urldecode。 仅当使用钉钉统一跳转协议时使用该动参。

      $DOUBLE_ENCCID$二次url加解密是因为：钉钉以“dingtalk://”有一层内部协议，在解析这层协议需要加密一次；url参数后面的业务https协议透传给下游容器使用的时候也需要加解密一次；由于消费方2次解析需要，所以产生url时候也需要2次加密。 示例产生url： urlencode（钉钉url？xxx=xxx & url = urlencode（业务url）） 示例解析url： a、urldecode（钉钉url）-> 得到业务url；b、urldecode（业务url）-> 可用参数