DuckChat
私有部署   |   安全可靠   |   随意定制

DuckChat小程序

如果你已了解本文档,可直接参阅:全部API列表

介绍

通过DuckChat小程序,站长可以快速的在很多地方,如【首页】、【聊天界面】等内嵌自己的H5网站,实现已有业务与聊天功能的完美对接。

可以实现的功能有:

  • 获取正在访问页面的用户身份。
  • 代发消息
  • 其他交互

类别

DuckChat中的小程序分类有很多种,供用户在APP上的不同位置查看。

类别 位置说明 支持的打开方式
首页小程序 APP首页 新页面打开
二人聊天小程序 二人聊天 新页面打开,悬浮打开,ChatBox打开
群组聊天小程序 群组聊天 新页面打开,悬浮打开,ChatBox打开

打开方式

方式 说明 备注
新页面 新窗口
悬浮框 聊天界面上方,覆盖半个屏幕的浮层 边聊天边试用小程序
Chatbox 聊天界面,点开+号后的显示的区域 类似微信红包的图标入口

权限说明

权限类别 说明 备注
所有人可用 所有用户
群管理员可用 仅群管理员 仅针对“群组聊天小程序”有效
站点管理员可用 仅站点管理员可以

开发指南

开发小程序以前,需要了几个重要名词需要了解:

miniProgramId

小程序在站点上的唯一标识,int类型

secretKey

又叫AuthKey,是一个32位的随机字符串。如果要访问Site的小程序API,需要用此密钥对请求进行加密。具体使用方法请参考下述文档。

小程序默认使用公用的密钥,这样最简单。但是也支持配置自己独立的密钥。

duckchat_sessionid

当客户端加载小程序时,会在Cookie中植入此Cookie,以帮助站点后段业务获取当前用户是谁。

可以从 $_COOKIE["duckchat_sessionid"] 获取此值。

duckchat_page_url

当客户端加载小程序时,会在Cookie中植入此Cookie,以标识此页面是在哪一个位置打开的,在聊天小程序中非常有用,因为要获取正在和谁聊天时候打开了此小程序,以正确的代发消息。

DuckChat小程序支持的接口

duckchat.session.profile

通过duckchat_sessionid 获取用户的资料,判断当前用户是谁。

duckchat.user.profile

获取用户的资料信息。

duckchat.user.relation

获取用户之间的好友关系。

duckchat.message.send

代发各种类型消息。目前支持的类型有:

  • 文本消息 - 二人/群组 文本消息
  • 通知消息 - 二人/群组 通知消息
  • Web消息 - 二人/群组 自定义Web消息
  • Web Notice消息 - 二人/群组 自定义web通知消息

技巧:如何识别用户身份?

在小程序中如何获取当前用户的身份资料,是最常用的功能之一。

此时应该使用 duckchat.session.profile 接口。

技巧:小程序中如何识别聊天场景?

小程序中的请求当中需要获取当前连接的来源方,以至于代发消息情况下,可以获取代发的是二人消息还是群组消息。

$dcUrlPage = $_COOKIE["duckchat_page_url"];

其中duckchat_page_url的规则满足小程序中GotoUrl的规则,因此开发者在解析过程参考GotoUrl,可以通过page参数来获取来源。

二人聊天界面的goto格式(UUUUUUUUUUUUU表示userId, page=u2Msg 表示二人聊天界面)

duckchat://192.168.3.4:8888/goto?page=u2Msg&x=UUUUUUUUUUUUU

群组聊天界面的goto格式(GGGGGGGGGGGGG表示groupId,page=u2Msg 表示群组聊天界面)

duckchat://192.168.3.4:8888/goto?page=groupMsg&x=GGGGGGGGGGGGG

【重要】如何调用小程序专用API

全部API列表

调用API需要使用SecretKey,如无特殊需求,可以直接使用公用SecretKey。

获取方式:【管理平台】->【小程序】-》【公共密钥】,为一个32位的字符串。

方式一:自行拼装HTTP API请求

类型 介绍
URL.Host 咨询站点管理员
URL.Path 不同API地址不一样,参考具体API文档
URL.Get参数 body_format=json&miniProgramId=$id$
这两个参数需要加到每一个请求的URL上。
$id$ 部分,需要替换成对应的小程序ID
Method Post
Body 请参考下面的Body拼接方法

Body拼装方法

  1. 【构造Request】根据API文档,得到APIRequest的JSON结构。
  2. 【拼接数据包】 body = {"time": 1537504179, "body": requestJson}
  3. 【加密数据包】body = aes(body, AuthKey, AES-128-ECB);
    • AES的加密参数为:AES-128-ECB
  4. 【发给服务器】
  5. 【获取返回值】根据API文档,使用ResponseJson里的各项数据。

PHP Demo Code

$authKey = "okokokokokokokokokokokokokok";

//$encryptedSessionId = $_COOKIE["duckchat_sessionid"];
$encryptedSessionId = "DabcdeiweqUcpoTHZHljxkdIi892jkds092sdfaGg3B6jDEIimdsfk280fadsXqc";

$request = array(
    "body" => array(
        "@type" => "type.googleapis.com/plugin.DuckChatSessionProfileRequest",
        "encryptedSessionId" => $encryptedSessionId
    ),
    "timeMillis" => microtime(true)*1000
);

$body = json_encode($request);
$body = openssl_encrypt($body, "AES-128-ECB",  $authKey, OPENSSL_RAW_DATA);

$apiSessionProfile = "http:/192.168.3.20/index.php?action=duckchat.session.profile&body_format=json&miniProgramId=100";
$ch = curl_init($apiSessionProfile);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
$result = curl_exec($ch);

$realResult = openssl_decrypt($result, "AES-128-ECB",  $authKey, OPENSSL_RAW_DATA);
var_dump($realResult);

请求不同的API,需要设置不同的$apiURL,以及$requestBody。具体Body请参考具体API文档。

方法二:使用SDK(PHP版本)

如果你想使用sdk,可以查看源码中的如下文件。

src/sdk/class.dc_open_api.php

//demo 
src/sdk/demo/class.dc_demo_controller.php

客户端JS-SDK开发教程

在DuckChat中使用小程序,可以使用一些JSAPI,以丰富功能。

1. 在页面中加载JS。

JS文件在源码包中:src/public/sdk/zalyjsNative.js

支持的本地方法有

方法 参数类型 返回值 说明 备注
zalyjsOpenPage(url) url:String 当前页面打开url 效果等同location.href = url
zalyjsOpenNewPage(url) url:String 使用新页面打开url
zalyjsLoginConfig(callback) callback:function 返回一个JSON object,字段如下:
enableInvitationCode
enableRealName
siteIdPubkBase64
这两个字段均对应站点的注册配置
zalyjsLoginSuccess(loginName,
sessionid,
isRegister,
failCallback)
loginName:string
sessionid:string
isRegister:bool
failCallback:function
开发自己的登陆功能时,在登陆完成以后需要把登陆信息提交给站点时,调用此方法 登陆小程序专用
zalyjsBackPage() 回退上一级菜单
zalyjsClosePage() 关闭当前页面
zalyjsImageUpload() 上传图片到服务器
zalyjsGoto(page,xarg) page:string xarg:string 通过gotoUrl跳转到客户端指定位置

示例:

//当前页面打开url
var url = "index.php?action=manage.miniProgram.profile&pluginId=" + miniProgramId;
zalyjsOpenPage(url);

//打开一个新的页面
var url = "index.php?action=manage.miniProgram.profile&pluginId=" + miniProgramId;
zalyjsOpenNewPage(url);

//获取站点的登陆配置信息
zalyjsLoginConfig(loginConfigResult);
function loginConfigResult(results) {
    if(typeof results == "object" ) {
        siteConfig = results;
    } else {
        siteConfig = JSON.parse(results);
    }
    //是否需要邀请码
    enableInvitationCode = siteConfig.enableInvitationCode;
    enableRealName=siteConfig.enableRealName;
    sitePubkPem = siteConfig.sitePubkPem;

}

//登陆站点
var loginName = "XXX";
var sessionid = "XXXX";
var isRegistered = false;//在自己实现的登陆系统中,是否已经注册过
zalyjsLoginSuccess(loginName, sessionid, isRegister, loginFailed);//最后一个参数为方法名称
function loginFailed(result) //用户自己实现的方法
{
    //alert(result.errorCode);
    //alert(result.errorInfo);
    if(result.hasOwnProperty('errorInfo')) {
        zalyjsAlert(result.errorInfo);
    } else {
        if(result != undefined && result !='') {
            zalyjsAlert(result);
        }
    }
}


//回退页面到上一页面
function back(){
    zalyjsBackPage();
}

//关闭页面
function close(){
    zalyjsClosePage();
}

//调用本地相册,上传图片
function uploadImage(){
    zalyjsImageUpload(uploadImageResult);
}

//客户端上传图片完成,返回结果 result是一个json Object
//fileId = Object.fileId
function uploadImageResult(result){
    var fileId = result.fileId;
    alert(fileId);
    //通过fileId展示图片
    var newSrc = "./_api_file_download_/?fileId=" + fileId;
   $("#imageId").attr("src", newSrc);
}

//通过zalyjsGoto方法调用本地的GotoClient,跳转到客户端具体位置
function jumpToU2Chat(){
    var page="u2Msg";
    var friednId = "1002238856";
    zalyjsGoto(page, friednId);
}

Goto跳转

Goto跳转的设计是为了帮助用户开发的小程序可以和客户端本地的页面进行交互对接,在小程序中可以进入添加用户好友,二人聊天,群组聊天,好友资料,群组资料等页面。DuckChat支持的Goto跳转页如下表所示:

跳转页 page xarg 说明
首页 page=home {XXX} 表示XXX变量
聊天列表 page=chats
用户资料 page=u2Profile x={friendUserId}
二人聊天页面 page=u2Msg x={friendUserId}
群组聊天界面 page=groupMsg x={groupId} groupId :群组的ID
通讯录列表 page=contracts
群组列表 page=groups
申请添加X为好友界面 page=addFriend x={friendUserId} 申请好友的用户ID

更多问题,请进入QQ群咨询。