Frame Activity Bridge SDK 연동 가이드
본 가이드는 외부 개발자가 SchoolPT 플랫폼과 임베딩 콘텐츠 간의 원활한 통신을 위해 사용할 Frame Activity Bridge SDK의 기본 사용법을 설명합니다.
주의: 현재 문서에 기재된 이벤트 타입, 데이터 타입, 설치 방식 등은 초안 상태이며 추후 변경될 수 있습니다.
SequenceDiagram
sequenceDiagram
participant Embed as 임베디드 컨텐츠
participant Bridge as FrameActivityBridge
participant Platform as 학습 플랫폼
participant CMS as CMS 컨텐츠 입력자
CMS->>Platform: 문제 타입 및 정답 데이터 입력
Note over CMS,Platform: EmbedNode 데이터 저장
Embed->>Bridge: startStudy()
Bridge->>Platform: 학습 시작 알림
Note over Embed,Bridge: 객관식 단일 정답 제출
Embed->>Bridge: submitAnswer(questionIndex: 1, answers: {selectedOptions: [1]})
Bridge->>Platform: 사용자 응답 전송
Platform->>Platform: 정답 확인
Note over Embed,Bridge: 객관식 다중 정답 제출
Embed->>Bridge: submitAnswer(questionIndex: 0, answers: {selectedOptions: [1, 3]})
Bridge->>Platform: 사용자 응답 전송
Platform->>Platform: 정답 확인
Note over Embed,Bridge: 주관식 답안 제출
Embed->>Bridge: submitAnswer(questionIndex: 2, answers: {userAnswer: "대한민국"})
Bridge->>Platform: 사용자 응답 전송
Platform->>Platform: 정답 확인
Note over Embed,Bridge: 활동 답안 제출
Embed->>Bridge: submitAnswer(questionIndex: 1, answers: {userAnswer: "활동 결과 텍스트"})
Bridge->>Platform: 사용자 응답 전송
Platform->>Platform: 활동 결과 저장
Embed->>Bridge: endStudy()
Bridge->>Platform: 학습 종료 알림
Platform->>Platform: 학습 결과 조회
Platform->>Platform: 학습 데이터 채점Mermaid
복사
1. SDK 소개
Frame Activity Bridge SDK는 외부 임베드 콘텐츠에서 발생하는 학습 이벤트(예: 학습 시작, 답안 제출, 학습 완료 등)를 SchoolPT 플랫폼에 전달하고, 학습 데이터의 저장 및 로드를 지원하는 JavaScript 라이브러리입니다.
2. 설치
설치 방식은 아직 미정이며, 다음과 같은 방식들 중 하나로 제공될 예정입니다:
•
CDN: HTML <script>, <link> 태그를 통해 로드
•
NPM: Node Package Manager를 통한 설치
•
Minified & 난독화된 JS 파일: 직접 제공되는 파일을 포함
시작하기
import { FrameActivitySdk } from 'frame-activity-sdk';
// SDK 인스턴스 생성
const sdk = new FrameActivitySdk();
// SDK 초기화 및 학습 활동 등록
await sdk.init([
{
activityId: '1',
type: 'MULTIPLE_CHOICE',
choices: [
{ label: '서울', isCorrect: true },
{ label: '부산', isCorrect: false },
]
}
]);
TypeScript
복사
API 레퍼런스
init(activities: Activity[])
SDK를 초기화하고 학습 활동을 등록합니다.
submit(data: SubmitData[])
학습자의 답안을 제출합니다.
save(key: string, data: SaveData)
학습 진행 상태를 저장합니다.
load(key: string)
저장된 학습 상태를 불러옵니다.
학습 활동 타입
중요: 현재 객관식 type만 연동 가능합니다.MULTIPLE_CHOICE (객관식)
interface MultipleChoiceActivity {
activityId: string;
type: 'MULTIPLE_CHOICE';
choices: Array<{
label: string;
isCorrect: boolean;
}>;
}
TypeScript
복사
SHORT_ANSWER (주관식) <WIP>
interface ShortAnswerActivity {
activityId: string;
type: 'SHORT_ANSWER';
answer: string;
}
TypeScript
복사
NON_INTERACTIVE (비활동형) <WIP>
interface NonInteractiveActivity {
activityId: string;
type: 'NON_INTERACTIVE';
}
TypeScript
복사
사용 예시
객관식 문제 구현
const sdk = new FrameActivitySdk();
// 학습 활동 초기화
await sdk.init([{
activityId: '1',
type: 'MULTIPLE_CHOICE',
choices: [
{ label: '서울', isCorrect: true },
{ label: '부산', isCorrect: false },
{ label: '대전', isCorrect: false },
]
}]);
// 학습 시작
await sdk.startStudy();
// 답안 제출
await sdk.submit([{
activityId: '1',
userSelectedIndexes: [0] // 첫 번째 선택지 선택
}]);
// 학습 종료
await sdk.endStudy();
TypeScript
복사
학습 상태 저장 및 불러오기
// 상태 저장
await sdk.save('quiz-progress', {
currentQuestion: 2,
answers: [0, 1],
});
// 상태 불러오기
const savedState = await sdk.load('quiz-progress');
TypeScript
복사
주의사항
1.
모든 API 호출은 비동기(async/await) 방식으로 동작합니다.
2.
activityId는 문자열 형태의 고유 식별자여야 합니다.
3.
학습 활동은 반드시 init() 메서드를 통해 먼저 등록되어야 합니다.
API 상세 명세
init(activities: Activity[])
학습 활동을 초기화하고 등록합니다.
매개변수:
•
activities: 등록할 학습 활동 배열
반환값:
•
Promise<void>
예시:
await sdk.init([
{
activityId: '1',
type: 'MULTIPLE_CHOICE',
choices: [
{ label: '선택지 1', isCorrect: true },
{ label: '선택지 2', isCorrect: false },
]
}
]);
TypeScript
복사
submit(data: SubmitData[])
학습자의 답안을 제출합니다.
매개변수:
•
data: 제출할 답안 데이터 배열
타입:
interface SubmitData {
activityId: string;
userSelectedIndexes?: number[]; // 객관식용
userAnswer?: string; // 주관식용
}
TypeScript
복사
예시:
// 객관식 답안 제출
await sdk.submit([{
activityId: '1',
userSelectedIndexes: [0, 2] // 복수 선택 가능
}]);
// 주관식 답안 제출
await sdk.submit([{
activityId: '2',
userAnswer: '대한민국'
}]);
TypeScript
복사
save(key: string, data: SaveData)
현재 학습 상태를 저장합니다.
매개변수:
•
key: 저장할 데이터의 키
•
data: 저장할 데이터 객체
예시:
await sdk.save('progress', {
currentStep: 3,
userAnswers: ['답안1', '답안2']
});
TypeScript
복사
load(key: string)
저장된 학습 상태를 불러옵니다.
매개변수:
•
key: 불러올 데이터의 키
반환값:
•
Promise<SaveData | null>
예시:
const savedData = await sdk.load('progress');
if (savedData) {
// 저장된 데이터 처리
}
TypeScript
복사