진도·출결 데이터 설계

• position · duration

  현재 위치와 전체 길이

  단위는 밀리초입니다. 탐색을 허용한 영상은 위치가 앞뒤로 움직이므로, 어디까지 봤는지의 근거로 쓰려면 실행할 때 탐색 금지(seekable: false)를 함께 거는 편이 안전합니다.

• playTime

  재생 시간: 영상이 흐른 양

  비디오 시간 기준입니다. 2배속으로 1초를 재생하면 2초로 셉니다. 영상 분량 중 얼마를 재생했는지 볼 때 씁니다.

• watchTime

  시청 시간: 학습자가 들인 시간

  실제 시간 기준입니다. 2배속으로 1초를 재생하면 1초입니다. 학습 시간을 실제 경과 시간으로 인정하는 과정이라면 이 값을 씁니다.

• sessionId

  값은 세션마다 따로 옵니다

  progress는 현재 세션의 진행 상태입니다. 같은 차시를 여러 번 열면 sessionId가 다른 보고가 섞여 올 수 있으므로 sessionId별로 저장한 뒤 차시 단위로 합산합니다.

• Unit Check

  첫 테스트에서 단위 확정

  playTime·watchTime과 오프라인 로그의 startedAt·stoppedAt은 문서에 단위가 없습니다. createdAt과 expiresOn은 Unix epoch time입니다. 1분짜리 테스트 재생 값을 받아 자릿수로 단위를 확정하세요.

• Interval

  보고 주기와 생략 규칙

  진행 보고 주기는 콘솔의 Interval로 정합니다. Android·iOS SDK는 2026년 8월 25일 배포본부터 진행 상태에 변화가 없으면 진행 보고를 건너뜁니다. 보고 공백을 이탈로 보지 말고 종료는 Stopped와 종료 보고로 판단하세요.

앱과 PC 커스텀 페이지의 오류 목록에도 접근 권한 만료, 접근 권한 없음, 디바이스 제한 초과, 재생 제한 초과에 해당하는 항목이 있으니 응답마다 안내 문구를 짝지어 두세요.

1. 식별값부터 설계

   실행할 때 userData에 수강 신청 ID와 차시 ID를 넣습니다. 같은 영상을 여러 과정에 쓰면 미디어 URL만으로는 어느 과정의 진도인지 가를 수 없습니다.

2. 세션 단위로 저장

   sessionId를 키로 시작·종료 시각, 마지막 진행 값, 종료 원인을 한 행에 모읍니다. 같은 세션의 진행 보고는 마지막 값으로 덮어쓰고, 같은 sessionId가 다시 와도 한 번만 반영되게 합니다.

3. 차시 단위로 합산

   진도율은 세션별 playTime 합을 duration으로 나누고, 학습 시간은 watchTime 합으로 둡니다. 같은 구간을 반복해 진도율이 부풀지 않게 하려면 탐색을 막은 영상에서 최대 position을 함께 씁니다.

4. 완강 판정

   진도율 기준 충족과 Ended 종료를 함께 요구합니다. Error로 끊긴 세션의 학습자에게는 이어보기를 안내합니다.

5. 정책 응답 연결

   배수 제한이나 재생 횟수 한도를 넘으면 진행 보고에 PlaybackLimitExceeded로 답합니다. 배수는 세션별 playTime 합을 duration과 비교해 판정할 수 있습니다. 플레이어는 응답에 따라 동작하므로 무거운 집계는 따로 돌리고 응답은 바로 돌려줍니다.

업종별 운영 예시는 온라인 교육·LMS, 도입 단계와 테스트 시나리오는 도입 실행 가이드, 용어 정의는 용어집에서 확인하세요.