在自建前端接入会员登录与数字交付

当您在自建前端经营在线课程、付费专栏、音频节目或数字下载包时，最难自行维护的通常是“买家登录”“确认谁有权限看哪个单元（Entitlement）”“私有影音与 PDF 防盗链签名”以及“跨设备观看进度同步”。

Kanorio 将这些底层能力封装为两层，您可以依定制化程度自由选择：

1. 直接放入 <kanorio-*> 组件（@kanorio/elements，最快）：一行标签或 React 组件，直接把 Kanorio 内置的无密码登录框、公开课纲与受保护播放器搬进您的外部网站。
2. 直接调用 Customer API（https://{您的网站}/api/v1/customer/*）：用您自己的 UI 调用无密码认证、读取已开通的交付物树状结构、换取 600 秒短效签名网址并回报进度。

完整规格参考（SSOT）：

• 所有顾客端点、参数与响应结构：Customer API 参考页
• 组件属性、自定义事件与 CSS 变量：Kanorio Elements 参考页

方式一：嵌入 @kanorio/elements 组件（推荐）

@kanorio/elements 提供标准 Web Components（任何框架或纯 HTML 皆可用）与 React 组件，内置 58 种语系与深浅色主题变量：

React 项目嵌入示例

import { KanorioProvider, KanorioLogin, KanorioUnit } from "@kanorio/elements";
import "@kanorio/elements/elements.css";

export function CoursePlayerPage() {
  return (
    <KanorioProvider siteUrl="https://s-k4m9x2p7q8w3.kanorio.com" locale="zh-Hant" theme="auto">
      <KanorioLogin siteName="拾光在线学院" />
      <KanorioUnit
        deliverable="react-masterclass"
        onProgress={(e) => console.log("进度更新：", e)}
      />
    </KanorioProvider>
  );
}

方式二：直接调用 Customer API 自定义学习界面

如果您希望百分之百自行设计课程大纲与学习画面，可以直接从浏览器（需先在“网站设置 › 开发者”将外部前端域名加入“允许的来源”）或您的服务器调用 Customer API：

1. 无密码登录换取 Bearer 令牌：
   • 调用 POST /api/v1/customer/auth/challenge 寄出 6 位数验证码与登录链接。
   • 买家输入验证码后，调用 POST /api/v1/customer/auth/verify，取得买家本人的 sessionToken（knr_cat_*，双重绑定该网站与该名联系人）。
2. 读取买家已开通的交付物与章节树：
   • 在 Header 带上 Authorization: Bearer knr_cat_...，调用 GET /api/v1/customer/deliverables 列出该买家拥有有效的所有交付物。
   • 调用 GET /api/v1/customer/deliverables/{key} 取得完整章节树、每个单元的解锁状态与目前观看进度。
3. 换取单元的 600 秒签名网址并回报进度：
   • 当买家点击某个单元时，调用 POST /api/v1/customer/units/{id}/open（服务器会实时检查存取权是否有效、是否已达定时解锁日期 releaseAt／releaseAfterDays），换取 600 秒有效的私有媒体签名网址。
   • 播放过程中定期调用 POST /api/v1/customer/progress 回报 positionSeconds，由服务器依交付物的结业规则判定是否完成并触发 deliverables.progress.completed Webhook。

三种权利的清晰边界

在设计自建前端时，请留意 Kanorio 将三种权利严格分开：

• 顾客商业权益（Entitlement）：买家购买商品或由站主手动开通后取得的“可观看某套交付物／单元”权利，由 Customer API 与 <kanorio-unit> 检查。
• 团队运营权限（RBAC）：网站拥有者、管理员、编辑者等操作后台与 Management API（knr_pat_）的权限，“能观看课程”绝不等于“能修改课纲”。
• 外部应用自定义角色：若您要打造含“分校老师只能看自己班级学生、助教只能批改作业”的专属应用系统，这类应用层角色不在 Kanorio 平台原语范围内（详见功能支持状态总表），请在您自己的应用后端实现，并透过 Management API 读取学员进度。

相关文件