钉钉开发文档

PHP版-HTTP回调方式

更新时间: 2019-6-3

注意:本QuickStart是以HTTP回调URL的方式来做示例的。同时,我们也提供了钉钉云推送的QuickStart,关于钉钉云推送,可以参考此文档详细了解。

开发者需要对以下技术栈有最基本了解,环境配置合理。

项目 内容 备注
演示者OS MacOS 与linux/unix接近。windows执行命令会有较大不同,开发者酌情调整。
代码库 Github 请自行配置好git,也可以直接用http形式从代码仓库下载demo代码。
服务端语言 PHP 请自行安装php5.6或以上,apache或者nginx的最新版作为server容器,php需要安装mcrypt扩展,以保证消息体加解密的函数的正常运行保证apache/nginx服务目录的可读写权限(写log需要)
内网穿透 内网穿透工具 非必需。本demo代码包含钉钉回调应用示例(但本文不演示),若需在没有公网IP或域名的服务器上(比如您自己的办公电脑)调试回调URL,可借助本工具映射一个可公网访问的地址,注意仅用于测试开发阶段。测试类型的应用,回调的验证和调试对于快速体验demo为非必需,本文不再赘述,开发者可后续调试回调URL时详细了解。

通过四大步骤即可完成应用的开发体验,最终本应用会获取到用户信息和企业基础信息展示在前端:

  1. 创建和设置应用
  2. 下载前后端示例代码
  3. 设置和启动服务端
  4. 前端设置和应用开通体验

1.创建和设置应用

建议创建测试应用,以免正式应用强制校验suiteTicket。可省去验证钉钉回调应用+应用获取正式suiteTicket环节。

1.1 创建应用

参考此文档:创建应用

1.2 获取本机IP并设置安全域名

应用前端向服务端发起网络请求时是直连安全域名或IP的,因此假如您的前端demo和服务端demo都在一个办公环境内(比如都在您的PC电脑上),是可以直接互通的,因此可以设置任何您的前端所在环境能连接到的域名或IP为安全域名。
您也可以通过钉钉提供的内网穿透工具生成一个临时二级域名给测试应用使用。

image.png

2.下载代码

使用命令git clone下载代码,也可以直接用HTTP形式从代码仓库下载。

服务端代码
git clone https://github.com/opendingtalk/eapp-isv-quick-start-php.git

前端代码
git clone https://github.com/opendingtalk/eapp-isv-quick-start-fe.git

3.设置和启动服务端

3.1 配置服务端项目

修改config.php文件
在您的php服务端代码根目录下找到config.php,修改以下配置

/**
 * 应用的SuiteKey,登录开发者后台,点击应用管理,进入应用详情可见
 */
define("SUITE_KEY", "");
/**
 * 应用的SuiteSecret,登录开发者后台,点击应用管理,进入应用详情可见
 */
define("SUITE_SECRET", "");
/**
 * 回调URL签名用。应用的签名Token, 登录开发者后台,点击应用管理,进入应用详情可见
 */
define("TOKEN", "");
/**
 * 回调URL加解密用。应用的数据加密密钥,登录开发者后台,点击应用管理,进入应用详情可见
 */
define("ENCODING_AES_KEY", "");

SUITE_KEY、SUITE_SECRET、TOKEN、ENCODING_AES_KEY参数请在开发者后台-第三方企业应用获取。
进入开发者后台,点您创建的应用可以查看应用的详细信息。如下图所示:
image.png
image.png
点击应用信息后面的“查看详情”,可以查看应用的信息,包括创建后得到的suiteId、suiteKey和suiteSecret。
image.png

3.2 运行服务端代码

配置好php的环境,并将php服务端代码放入apache或者nginx容器下即可。

3.3 启动服务端程序

检查服务端启动成功页面,访问 http://localhost/index.php 地址,打开页面如下图所示:

4.前端设置和应用开通体验

4.1 下载IDE并导入前端代码

请参考小程序前端IDE使用,下载、安装、使用IDE。
打开IDE后选择您下载的前端项目eapp-isv-quick-start-fe文件夹,选择开发的应用类型,
打开后在右上角点击登录,出现扫码登录界面,使用钉钉扫码登录IDE。

注意:如果开发者已经打开IDE,请关闭重新打开,初次打开才可以选择打开新工程。

选择项目类型即要开发的应用类型。

点击右上角登录按钮使用钉钉扫码登录。

4.2 修改前端配置

修改文件eapp-isv-quick-start-fe/page/index/index.js。
IP端口为本机的IP和PORT,注意url中的IP或域名必须是开发者平台中设置的本应用的安全域名。

let url = "http://30.xxx.xx.54:80/login.php";

4.3 添加体验组织并开通应用

重要:面向企业的应用必须企业开通才能进行体验,您需要创建专门的体验组织并为此组织开通本应用。
请注意:此处添加的体验组织是创建全新的测试组织,并不能添加已有组织为体验组织-比如本应用所在的开发组织。
测试应用可以直接开通。而正式应用需要验证回调有效性并设置好回调URL才能开通。本demo建议创建的是测试应用,因此可以暂时忽略验证回调有效性,可直接开通本应用。

依照本节前述的示例,进入到开发者后台的左侧菜单的应用菜单,并选择进入应用详情页找到版本管理,可通过“添加体验组织”来创建全新体验组织和开通应用。
image.png

4.4 在IDE模拟器上体验应用

在IDE上方,选择已经开通本应用的体验组织(如未出现尝试重启IDE),如下图所示:

然后再选择关联应用,IDE会重新编译前端代码并载入页面,

如果获取到用户信息userid则表示应用运行成功。
祝贺您已经成功体验本quick start。

以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!