Mixin Messenger 小程序接入指南

简介

Mixin Messenger 是 Mixin Network 上第一个 DApp，使用简单功能强大：

• 安全：端对端加密保障消息安全，强大的 Mixin Network 保障钱包安全
• 免费：免费收发消息，免费转账
• 易用：手机号注册即可使用，6 位数字 PIN 码方便使用且易于记忆
• 快速：实时收发消息，实时享受转账服务
• 丰富：支持文字、贴纸、图片、语音、视频等消息；支持 BTC、ETH、Ripple、BCH、Siacoin等数万种代币

前言

Mixin Messenger 不会主动向用户推荐任何小程序（包括官方自己开发的小程序），也没有专门的界面来显示推荐小程序列表，需要开发者自己想办法推广自己的小程序。早期在 Mixin Messenger 里推广自己的小程序是很容易的，做好了往大群一发大家都知道了，能帮你获得珍贵的种子用户，Exin（7000101276）就是一个很好的例子。

接入

0、准备

• 下载 Mixin Messenger，体验设置 PIN、充值、转账、提现流程，便于理解 API 文档
• 阅读官方开发指南：https://developers.mixin.one/guides

1、注册成为 Mixin 的 Developer

通过 Mixin Messenger 扫码登录 https://developers.mixin.one （点右上角）。

2、为您的小程序创建一个 Mixin App

点 Create New App 按提示创建就行， 创建完即可在 Mixin Messenger 里搜索找到你创建的小程序（首页右上角联系人 -> 添加联系人 -> 输入 Mixin App Id 点搜索 -> 打开小程序）

• The home uri. —— 小程序的入口，Mixin Messenger 里打开小程序实际上打开一个内置 WebView 的弹窗，WebView 会默认加载你设置的 home uri。
• The OAuth redirect uri. —— OAuth 授权回调，必填项。

3、生成 Mixin App 相关的 Session

点 Click to generate a new session 生成 PIN、Session Id 、Pin Token、Private Key，这些都要记下来后面要用，服务器和浏览器都不会保存这些敏感信息（注意刷新再次点又会生成一个新的，会覆盖旧的）。

4、OAuth 授权

要访问用户个人资料、资产列表、联系人列表和手机号码，你需要通过 Mixin Messenger 向用户申请授权
https://developers.mixin.one/api/beta-mixin-message/oauth-scopes/

4.1、申请授权

检测到用户没有授权时跳转页面至 https://mixin.one/oauth/authorize?client_id=b7347ca4-186e-4e54-9db6-755a4ab0b5d4&scope=PROFILE:READ+ASSETS:READ&response_type=code 引导用户授权，在浏览器里打开这个链接会显示一个二维码，在 Mixin Messenger 中打开就会直接唤起请求授权弹窗。

• client_id 步骤 3 图中的 User Id，替换成你的就行
• response_type 固定写 code 就行

4.1、授权成功回调

Mixin Messenger 授权成功后会回调步骤 2 填写的 redirect uri ，并且返回一个 authorization code ，通过 https://api.mixin.one/oauth/token 验证成功后会返回 access_token ，这个很重要需要保存起来，据此可以判断当前用户是否已经授权过了。参考官方开发者指南里 Request Access Token 章节： https://developers.mixin.one/guides

5、通过 API 访问授权用户的数据

访问授权用户的个人资料、资产列表等 API 都需要设置 Authorization Token， 直接用上面取到的 access_token 即可。

GET -H "Authorization: Bearer ACCESS_TOKEN" https://api.mixin.one/me 
{
  "data": {
    "type": "user",
    "user_id": "773e5e77-4107-45c2-b648-8fc722ed77f5",
    "name": "Team Mixin",
    "identity_number": "7000"
  }
}

访问以下 API 都需要相应的授权，需要在步骤 4.1 申请授权时设置：

• /me 获取授权用户的个人信息，例如 user_id、name 等，如果后续需要和用户交互可以把用户信息保存到你服务端的数据库里，例如给用户发消息，记录用户的支付信息等。参考 API：https://developers.mixin.one/api/beta-mixin-message/read-profile/
• /assets 获取授权用户的资产列表，包含余额信息，参考 API ：https://developers.mixin.one/api/alpha-mixin-network/read-assets/
• /friends 获取授权用户的好友列表，参考 API ：https://developers.mixin.one/api/beta-mixin-message/friends/

当 API 返回 401 时你需要清理旧的 access_token 然后重新请求授权

6、Mixin Messenger 支持的 Schema

• 支付链接： https://mixin.one/pay?recipient=&asset=&amount=&memo=&trace= ，recipient 是收款人的 User Id，asset 是具体支付资产 id，amount 支付金额，memo 支付备注（可以不传），trace 支付唯一编号 UUID，可以用来防止重复支付，每一笔交易都应该生成一个新的 trace。你可以用轮询的方式根据 trace 调用 https://api.mixin.one/transfers/trace/trace_id 接口来检测是否已经完成支付，参考 js 代码：https://github.com/over140/mixcoin/blob/master/web/src/market/index.js 的 handleOrderCreate 方法。例子：

https://mixin.one/pay?recipient=b26b9a74-40dd-4e8d-8e41-94d9fce0b5c0&asset=965e5c6e-434c-3fa9-b780-c50f43cd955c&amount=1000.00000000&memo=hKFUoUyhUKowLjAxMDAwMDAwoVOhQaFB3AAQzIFbCxonZDc2zI/MqkLM1syUzPpiCg==&trace=a8b135d7-f757-4eea-9c47-060ad8804945
测试如果显示已支付了给 trace 参数换一个新的 UUID 然后刷新一下即可

• 转账链接：https://mixin.one/transfer/user_id ，可以直接唤起对某个用户转账界面，即 Mixin Messenger 里面收款码的功能，但是不支持设置具体的资产和转账金额，例子：

https://mixin.one/transfer/b26b9a74-40dd-4e8d-8e41-94d9fce0b5c0

• 用户链接：https://mixin.one/users?user_id ，可以在 Mixin Messenger 直接弹窗显示某个用户，例如：

https://mixin.one/users/b26b9a74-40dd-4e8d-8e41-94d9fce0b5c0

• 分享文字消息链接：https://mixin.one/users?text= ，可以分享文字内容到 Mixin Messenger 里，客户端这边会唤起 Send To 界面

7、给用户发消息

你可以给用户发各种文字、贴纸、图片、语音、视频等消息，实现订阅号类似的功能，参考 https://github.com/MixinNetwork/bot-api-go-client/blob/master/message.go 的 PostMessage 方法发送消息，参考 https://developers.mixin.one/api/beta-mixin-message/websocket-messages/ 设置具体消息类型和相关参数。

• 1v1 聊天也需要 Conversation Id，参考 https://github.com/MixinNetwork/bot-api-go-client/blob/master/message.go 的 UniqueConversationId 方法生成。
• APP_CARD 类似的消息很有用，可以生成抢红包的样式
  
• 小程序发给用户的消息都是不加密的，只能发以 PLAIN_ 开头的消息类型。

当一个新用户添加你的小程序为好友时，小程序监听 WebSocket 会收到“Hi”的消息（Mixin Messenger 服务端替用户发的，用户自己看不见），据此小程序可以给用户发一些引导信息或者欢迎信息。注意不能根据这个来判断用户是否添加了你的小程序为好友，因为用户也可以直接给小程序发“Hi”。

8、接收用户发给小程序的消息

使用 WebSocket 监听消息，参考文档 https://developers.mixin.one/api/beta-mixin-message/authentication/ ，参考源码 https://github.com/crossle/hacker-news-mixin-bot 的 blaze.go 和 message.go 。

• 即使将小程序添加到多人群组，小程序也收不到群组产生的消息，群组的消息都是加密的，小程序只能处理未加密的消息。
• 注意收到消息处理完以后一定要发 ACKNOWLEDGE_MESSAGE_RECEIPT 类型的消息告诉 Mixin Messenger 服务器你已经收到了消息，否则每次给服务器发 LIST_PENDING_MESSAGES 都会再次发给你的小程序。（Go 的 SDK 已经默认处理了）

9、优化小程序

强烈推荐学习使用 PWA 来改善您小程序的体验（https://developers.google.com/web/ilt/pwa/）

10、资源

• Golang SDK：https://github.com/MixinNetwork/bot-api-go-client
• Mixin Messager Android 源码：https://github.com/MixinNetwork/android-app
• Mixin Messager iOS 源码：https://github.com/MixinNetwork/ios-app
• Nodejs Demo （非官方）: https://github.com/virushuo/mixin-node
• Python Demo（非官方）: https://github.com/myrual/mixin_client_demo
• Java Demo（非官方）: https://github.com/qige-one/mixin_java_sdk
• Go 开源小程序 Hacker News (Mixin ID: 7000100124) ： https://github.com/crossle/hacker-news-mixin-bot
• Mixin 官方开发者群：https://mixin.one/codes/0f2a743d-d86b-4a6c-b26c-14e320799311