第三方对接指南

流程一览

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

准备材料

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

5 步对接

{
  "code": 1,
  "data": { "url": "https://open.weixin.qq.com/connect/qrconnect?..." }
}

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

复制以下代码，填入你的 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 联邦身份说明