自定义企业首页文档

自定义企业首页文档

如果你还没有注册企业，请移步到https://oa.dingtalk.com/#/login注册企业。

如果你已经有企业，请移步到https://oa.dingtalk.com用你的手机版钉钉扫描登录，在第一次登录时，会要求你设置管理员密码。

接下来，你一共需要经历三个操作，配置好URL，就可以愉快的开发你自己企业首页的定制实现了。

理论上，需要填写的URL是你Web应用的真实地址，而且不要忘记了在URL地址后跟随的search参数corpId，corpId是可以在管理后台获取的。

点击新建应用，创建你的微应用：

带*号的表示必填，记录好你的AgentID，需要注意的是填写微应用的URL时，要跟你的Web应用的启动地址对应上：

开发准备阶段

一个Web应用是有两个部分组成的，整体上来说，我们推荐采用前后分离的架构，这也是我们推荐的一种应用架构类型。服务端可以自行决定采用什么语言，使用什么样的架构来定义你的接口实现。

而前端我们推荐采用Vue 2.0 做为你的base library，这是一套构建用户界面的“渐进式框架”，它的语法灵活简单，并且非常容易学习，对于构建大型应用，它的“单文件组件”，以及Vue生态系统支持的库可以让你很轻松的搭建一个复杂的单页应用（SPA），来阅读它的文档 https://cn.vuejs.org/v2/guide/，感受一下吧。如果你们企业的前端开发能力有限，我也为你准备了一份可以快速入门JavaScript的文章：https://github.com/icepy/we-writing/issues/12 了解一些基础的“元素”，你就能快速的使用起来Vue 2.0。

另一方面Vue的单文件组件依赖于vue-loader的构建，用到了webpack这样的构建工具，自然需要你略懂Node.js，不要着急，我们并不需要完全的掌握它，只需要了解一下它的npm scripts 命令行运行即可，如果你还不了，请移步阅读一下去年我为社区写的一篇文章：https://github.com/icepy/we-writing/issues/36，相信厉害的你，一定可以快速的阅读完并理解它。

如果你对webpack的配置有兴趣，也可以移步阅读它的文档 https://webpack.js.org/，不过，高兴的是，我们提供了一份完整的默认构建，这也意味着你不需要过渡的关注webpack的配置。

关于开发工具，首推WebStorm，其次是Atom编辑器，如果你是vim党，并且使用的Mac，我也为你准备了一份集成了zsh，oh-my-zsh，vim plugin，tmux，vimrc的项目，https://github.com/icepy/icepy.vim ，下载它快速完成配置吧。

业务梳理

对于自定义企业首页而言，需要重点关注的是两个部分的业务：js-api权限校验和免登。钉钉容器层面上，对于某些js-api是有权限校验的，而免登来说才是企业首页要打通自己企业员工体系的唯一入口。

重要说明

CorpID和CorpSecret是一对重要的凭证，你需要好好保护它不对外流出，接下来要做的事情都需要它们，CorpID和CorpSecret都可以在钉钉的管理后台中获取。

现在钉钉提供的服务端域名：https://oapi.dingtalk.com

js-api权限校验（业务实现，请按照我给你梳理的顺序，正序执行，2必然依赖于1，3必然依赖于2，请不要随意跳过步骤。）：

1. 通过 gettoken 接口，参数为URL?corpid=CorpID&corpsecret=CorpSecret（GET） 获取access_token，过期时间为7200秒，建议：将它全局缓存。这对于优化服务能有很大的作用，如果有时候返回了错误信息，这说明太频繁的调用了 gettoken 接口。
2. 通过 get_jsapi_ticket 接口，参数为URL?access_token=access_token（GET） 来获取ticket，过期时间为7200秒，建议：将它全局缓存，如果有时候返回了错误信息，这说明太频繁的调用了 get_jsapi_ticket 接口。
3. 对ticket进行签名，签名算法为 sha1，一共需要传入的参数有：nonceStr，timeStamp，signedUrl，ticket四个，nonceStr为随意定义的Key名，timeStamp是你当前的时间戳，signedUrl为不包含#（hash）以及其后面部分的Url，如果前端对Url进行了encodeURIComponent，那么在服务端需要对其decodeURIComponent（建议：Url在前端一定要encodeURIComponent来处理特殊字符，中文等，统一在服务端decodeURIComponent）。ticket为你通过 get_jsapi_ticket 接口获取的返回。
4. 生成了签名之后将nonceStr，timeStamp，signature，corpId，agentId 返回给前端，注意：nonceStr 和 timeStamp 一定要是你服务端刚生成签名时所用的 nonceStr 和 timeStamp。
5. 前端拿到返回后，将其添加到dd.config中。注意：当调用某些需要授权的api时，如果签名校验失败，一定要查一下URL等参数是否一致，如果不一致，很可能导致和服务端签名对应不上，而导致在Native上校验失败。必要时通过dd.error注册一下错误信息，可以看到一些必要的错误提示。

免登（业务实现，请按照我给你梳理的顺序，正序执行，2必然依赖于1，请不要随意跳过步骤。）：

1. 通过js-api runtime.permission.requestAuthCode 来获取code，需要传入的参数为：corpId
2. 如果全局缓存中拿不到access_token，请参考 js-api权限校验的第一步，通过gettoken来获取access_token。如果全局缓存中可以拿到access_token，那么通过 /user/getuserinfo 接口，参数为 URL?access_token=access_token&code=code（GET）获取userid，如果返回有错误，那么请查看一下token是否过期，以及通过Native获取code时传入的corpId是否是你企业的corpId。

免登最重要的就是要获取用户的userid，通过userid才可以调用其他跟用户相关的open api。

前端技术梳理

对于这些繁重的业务步骤，在前端上封装了一个好用的SDK，只需要简单的调用一个SDK API，就能一次性完成这些业务逻辑复杂的校验，免登等流程，将前端的小宇宙释放出来可以更关注用户界面和企业的业务逻辑。

dingWebInterfaceSDK目前提供了五个API：

• getMicroApps 获取在管理后台添加的全部应用
• getUserInfo 获取用户详细信息
• getUserId 获取用户userid
• jsApiOAuth JS-API权限校验
• axios 一个开源的请求库 https://github.com/mzabriskie/axios

前端的用户界面使用了Vue来构建，页面中的内容，全部按组件的方式来拆分，你可以很方便的随意组合，来达到你想要实现的业务。

这些渲染逻辑都是通过数据来驱动，这也意味着它是可变的，只要你自己的服务端来吐数据出来，就能很快的改变这些内容，比如营业日报，想变成“某某企业营业日报”，这些都可以轻松实现。

通过我们提供的模板项目，你不需要关心整体架构，也不需要关心构建过程，通过两个简单的命令 npm run dev 和 npm run build就能轻松实现，不管是开发环境，还是生产环境，你可以更关注于企业首页的用户界面与业务逻辑。