於自建前端接入會員登入與數碼交付

當您在自建前端經營網上課程、付費專欄、音訊節目或數碼下載包時，最難自行維護的通常是「買家登入」「確認誰有權限觀看哪個單元（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 讀取學員進度。

相關文件