헤드리스 프론트엔드에 멤버 로그인 및 디지털 콘텐츠 배포 통합하기

온라인 코스, 유료 뉴스레터, 오디오 프로그램 또는 디지털 다운로드 서비스를 자체 프론트엔드에서 운영할 때 가장 유지보수가 까다로운 부분은 보통 "구매자 로그인", "이용 권한 확인(누가 어떤 유닛에 접근할 수 있는지)", "비공개 영상/PDF의 불법 복제 방지 서명", "기기 간 학습 진도 동기화"입니다.

Kanorio는 이러한 핵심 기능을 두 가지 레이어로 캡슐화하여, 사용자의 커스터마이징 요구사항에 맞춰 선택할 수 있도록 지원합니다.

1. Drop-in <kanorio-*> 요소 (@kanorio/elements, 가장 빠른 방법): 단일 태그나 React 컴포넌트를 사용하여 Kanorio의 내장 패스워드리스 로그인, 공개 커리큘럼, 보호된 플레이어를 외부 웹사이트에 직접 도입합니다.
2. 직접적인 Customer API 호출 (https://{your-site}/api/v1/customer/*): 자체 UI를 사용하여 패스워드리스 인증을 호출하고, 구매한 콘텐츠의 트리 구조를 가져오며, 600초간 유효한 서명된 URL로 교환하고, 학습 진도를 보고합니다.

전체 사양 참조 (SSOT):

• 모든 고객 엔드포인트, 파라미터 및 응답 구조: Customer API 참조
• 컴포넌트 속성, 커스텀 이벤트 및 CSS 변수: Kanorio Elements 참조

옵션 1: @kanorio/elements 임베딩 (권장)

@kanorio/elements는 표준 웹 컴포넌트(모든 프레임워크 또는 일반 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="en" theme="auto">
      <KanorioLogin siteName="My Online Academy" />
      <KanorioUnit
        deliverable="react-masterclass"
        onProgress={(e) => console.log("Progress updated:", e)}
      />
    </KanorioProvider>
  );
}

옵션 2: Customer API를 통한 학습 인터페이스 커스터마이징

커리큘럼과 학습 인터페이스를 처음부터 직접 설계하고 싶다면, 브라우저에서 직접(프론트엔드 도메인을 "사이트 설정 › 개발자"의 "허용된 오리진"에 추가한 후) 또는 서버에서 Customer API를 호출할 수 있습니다:

1. Bearer 토큰을 위한 패스워드리스 로그인:
   • POST /api/v1/customer/auth/challenge를 호출하여 6자리 인증 코드와 로그인 링크를 전송합니다.
   • 구매자가 코드를 입력한 후, POST /api/v1/customer/auth/verify를 호출하여 구매자의 sessionToken(knr_cat_*, 사이트와 연락처에 이중으로 결합됨)을 획득합니다.
2. 콘텐츠 및 챕터 트리 가져오기:
   • 헤더에 Authorization: Bearer knr_cat_...을 포함하여 GET /api/v1/customer/deliverables를 호출하면 구매자가 유효한 을 가진 모든 콘텐츠 목록을 확인할 수 있습니다.
   • GET /api/v1/customer/deliverables/{key}를 호출하여 전체 챕터 트리, 각 유닛의 잠금 해제 상태 및 현재 시청 진도를 가져옵니다.
3. 600초간 유효한 서명된 URL 교환 및 진도 보고:
   • 구매자가 유닛을 클릭하면 POST /api/v1/customer/units/{id}/open을 호출합니다(서버가 이용 권한을 확인하고 releaseAt/releaseAfterDays 조건이 충족되었는지 검사함). 그러면 600초간 유효한 비공개 미디어 서명 URL을 받을 수 있습니다.
   • 재생 중에 주기적으로 POST /api/v1/customer/progress를 호출하여 positionSeconds를 보고합니다. 서버는 콘텐츠 규칙에 따라 완료 여부를 판단하고 deliverables.progress.completed Webhook을 트리거합니다.

세 가지 명확한 권한 경계

헤드리스 프론트엔드를 설계할 때, Kanorio는 다음 세 가지 유형의 권한을 엄격하게 분리하고 있음을 유의하십시오:

• 고객 이용 권한 (Customer Entitlement): 특정 콘텐츠나 유닛을 볼 수 있는 권한으로, 구매 후 또는 사이트 소유자가 수동으로 할당하여 부여됩니다. Customer API 및 <kanorio-unit>을 통해 확인됩니다.
• 팀 운영 (RBAC): 사이트 소유자, 관리자, 편집자가 대시보드 및 관리 API(knr_pat_)에 접근할 수 있는 권한입니다. "코스를 볼 수 있는 능력"이 "커리큘럼을 수정할 수 있는 능력"을 의미하지는 않습니다.
• 외부 애플리케이션 커스텀 역할: 특정 역할이 필요한 시스템(예: "지점 강사는 자신의 학생만 볼 수 있음", "조교는 과제 채점만 가능")을 구축하는 경우, 이러한 애플리케이션 계층의 역할은 Kanorio 플랫폼 기본 기능의 범위를 벗어납니다(기능 매트릭스 참조). 이러한 기능은 자체 백엔드에서 구현하고 관리 API를 사용하여 학생의 진도를 읽어오십시오.

관련 문서