第三方对接指南

流程一览

你的应用                    UserMatrix                 用户
  │                            │                        │
  │── 1. 构造登录链接 ─────────→│                        │
  │                            │── 2. 跳转授权页 ───────→│
  │                            │←── 3. 用户扫码/授权 ────│
  │←── 4. 带 code 回调 ────────│                        │
  │── 5. code 换用户信息 ─────→│                        │
  │←── 返回 openid+token ──────│                        │
  │                            │                        │
  └─ 登录完成，后续用 token 调 API

准备材料

在 um.yunjii.cn/console/apps 创建应用，获得：

选择对接范式（先读这节）

UM 扫码登录有 三种 对接方式，速度、兼容性、前端改动量差别很大。新接入推荐 A（直接图片）；老系统可继续用 B（后端跳转）兼容；C（iframe 嵌入）已淘汰，请勿再用。

三种方式最终都走同一套 act=callback 换用户信息，区别只在"如何把二维码/授权页呈现给用户"。 实测参考：UM 服务端两个端点 TTFB 均在 ~0.1s（api/qrcode.php 0.095s / connect.php?act=login 0.107s），瓶颈不在服务端，而在前端流程与第三方嵌套限制——这正是 A 快、C 慢且易失败的根本原因。

30 秒选型

• 🆕 新接入 / 想最快最稳 → 用 A，照下面第 1 步开始。
• 🔧 老系统、后端拿 URL 再 302 最省事 → 用 B，见文末兼容写法。
• 🚫 任何新需求都不要再用 C（iframe 嵌入）。

5 步对接

<img src="https://um.yunjii.cn/php/api/qrcode.php?appid=1001&type=wx&redirect_uri=https://yourapp.com/callback&state=xxx&size=240&timestamp=...&sign=...">

https://yourapp.com/callback?code=CODE_xxx&state=你传的state

{
  "code": 1,
  "data": {
    "openid": "oXabc123...",
    "nickname": "张三",
    "avatar": "https://thirdwx.qlogo.cn/...",
    "social_uid": "um_a1b2c3d4e5f6",
    "login_type": "wx",
    "token": "um_token_xxx..."
  }
}

{
  "code": 1,
  "data": {
    "user_id": 12345,
    "openid": "um_a1b2c3...",
    "scope": "app",
    "expire_at": "2026-07-13 12:00:00"
  }
}

签名算法

不用 SDK 时需要手动计算签名，3 行逻辑：

// 1. 收集所有 GET 参数（除 sign 外），按 key 字典序排列
ksort($params);

// 2. 拼接成字符串，末尾加 appkey
$signStr = '';
foreach ($params as $k => $v) $signStr .= "$k=$v&";
$signStr .= "appkey=$appkey";

// 3. MD5
$sign = md5($signStr);

完整 PHP Demo（B · 后端跳转范式，老系统兼容）

下方为 B（后端跳转） 写法，便于不便改前端的老系统参考复用。 新项目推荐用上面的 A（直接图片）：照「第 1 步」用 <img src="api/qrcode.php"> 出图 + 前端轮询 query.php 拿登录态即可，无需这套 302 跳转。

复制以下代码，填入你的 appid 和 appkey，保存为 login.php 即可运行：

<?php
// ====== 配置 ======
$appid = '你的_appid';
$appkey = '你的_appkey';
$redirect_uri = 'https://yourapp.com/login.php';

// ====== 签名函数 ======
function makeSign($params, $appkey) {
    ksort($params);
    $str = '';
    foreach ($params as $k => $v) $str .= "$k=$v&";
    $str .= "appkey=$appkey";
    return md5($str);
}

// ====== 主逻辑 ======
$act = $_GET['act'] ?? 'login';

if ($act === 'login') {
    // 第一步：构造登录链接
    $params = [
        'act' => 'login',
        'appid' => $appid,
        'type' => 'wx',              // 改成你要的平台
        'redirect_uri' => $redirect_uri,
        'state' => bin2hex(random_bytes(16)),
        'timestamp' => time(),
    ];
    $params['sign'] = makeSign($params, $appkey);

    $resp = json_decode(file_get_contents(
        'https://um.yunjii.cn/php/connect.php?' . http_build_query($params)
    ), true);

    if ($resp['code'] === 1) {
        header('Location: ' . $resp['data']['url']);
        exit;
    }
    die('登录链接生成失败: ' . $resp['msg']);
}

if ($act === 'callback') {
    // 第四步：code 换取用户信息
    $params = [
        'act' => 'callback',
        'appid' => $appid,
        'code' => $_GET['code'],
        'timestamp' => time(),
    ];
    $params['sign'] = makeSign($params, $appkey);

    $resp = json_decode(file_get_contents(
        'https://um.yunjii.cn/php/connect.php?' . http_build_query($params)
    ), true);

    if ($resp['code'] === 1) {
        $user = $resp['data'];
        echo "登录成功！<br>";
        echo "昵称: {$user['nickname']}<br>";
        echo "头像: <img src='{$user['avatar']}' width=64><br>";
        echo "UMID: {$user['social_uid']}<br>";
        echo "Token: {$user['token']}<br>";
        // TODO: 在这里创建会话，跳回首页
    } else {
        die('换取用户信息失败: ' . $resp['msg']);
    }
}

使用方式：

1. 修改 $appid 和 $appkey
2. 在 UM 控制台配置回调域名为你的域名
3. 浏览器访问 https://yourapp.com/login.php?act=login
4. 用户扫码授权后会自动回调 ?act=callback&code=xxx

用 SDK（更简单）

如果你用 PHP / JS / Python / 小程序，装 SDK 后签名自动生成：

$um = new UM($appid, $appkey, $callback, 'https://um.yunjii.cn/php');
$url = $um->login('wx', $state);    // 一步生成登录链接
$user = $um->callback($_GET['code']); // 一步换取用户信息

详见 SDK 文档。

常见问题

下一步

• OAuth API 完整参考
• 错误码列表
• Playground 在线体验
• UMID 联邦身份说明