Skip to main content

북마크 연동

개요​

북마크 연동은 Kollus 플레이어에서 생성된 북마크 데이터를 API를 통해 외부 서버(고객사 데이터베이스)와 동기화하는 기능입니다.

북마크 종류​

  • 내 북마크 ("kind": 0): 시청자가 직접 추가한 개인용 데이터입니다.
  • 공식 북마크 ("kind": 1): 고객사가 설정한 목차, 챕터 또는 핵심 요약 정보입니다. 모든 시청자에게 공통으로 노출됩니다.
참고
  • 기능 활성화: 북마크 연동 기능은 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.
  • 계정 단위 설정: 북마크 연동 URL은 서비스 계정당 1개만 등록 가능합니다. (채널별 개별 설정 불가)

요구 사항​

  • 오프라인 동기화: 시청자가 오프라인 상태에서 생성한 북마크 데이터는 온라인 전환 즉시 서버에 전송되어야 합니다.

데이터 전송 시점​

플랫폼데이터 전송 시점
모바일 앱앱 프로세스가 종료되는 시점에 누적 데이터 전송
PC (JavaScript)브라우저 탭 종료 또는 페이지 이동(unload) 시점에 전송

API 공통 파라미터​

북마크 관련 API 요청 시 공통으로 포함되는 파라미터 명세입니다.

파라미터타입설명
upload_file_keystring콘텐츠 업로드 시 발급된 고유 식별자
media_content_keystring채널 내 콘텐츠 고유 식별자
client_user_idstring시청자 ID
positioninteger북마크 위치 (sec)
localtimeinteger북마크가 추가된 시각 (Unix Timestamp)
labelstring북마크 레이블
valuestring북마크 내용
uservalue{0~99}string커스텀 변수 (uservalue0~uservalue99)
참고
  • 시간 동기화: localtime은 서버 시간이 아닌 시청자 디바이스의 로컬 시간을 나타냅니다. 네트워크 환경에 따라 서버와 오차가 발생할 수 있으므로 기록용 외의 로직 활용은 권장하지 않습니다.
  • UI 매핑: label은 북마크의 상위 카테고리 이름, value는 개별 북마크의 내용을 결정합니다.

북마크 목록 조회 API (List URL)​

플레이어 실행 시 저장된 북마크 데이터를 호출하여 JSON 형식으로 반환하는 인터페이스입니다. 모든 응답은 UTF-8 인코딩을 준수해야 합니다.

요청 규격​

구분공식 북마크공식 북마크 + 내 북마크
MethodGETGET
Parameters
  • upload_file_key (string)
  • media_content_key (string, optional)
  • media_content_key (string)
  • client_user_id (string)

동적 파라미터 치환​

등록된 List URL 내 {uservalue0} ~ {uservalue9} 형식은 요청 시점에 실제 데이터로 자동 치환됩니다.

  • 등록 URL
http://abc.com/bookmark/read?LC={uservalue0}&device={uservalue9}
  • 실제 호출 URL
http://abc.com/bookmark/read?LC=LC001&device=mobile

응답 필드​

필드타입설명
errorintegerAPI 처리 결과 (0: 정상, 그 외: 에러)
resultobject북마크 데이터를 포함하는 객체
result.bookmark_labelsarray북마크 목록에 표시될 북마크 그룹 명칭 (예: ["내 북마크", "공식 북마크"])
result.bookmark_positionsarray북마크 데이터

bookmark_positions 항목​

필드타입설명
positioninteger북마크 위치 (sec)
valuestring북마크 내용
kindinteger북마크 종류
  • 0: 내 북마크
  • 1: 공식 북마크
labelstring공식 북마크 레이블 (내 북마크인 경우 빈 문자열)
localtimeinteger북마크가 추가된 시각 (Unix Timestamp)

응답 예시​

{
  "error": 0,
  "result": {
    "bookmark_labels": [ "My Bookmark", "Official Bookmark"],
    "bookmark_positions": [
      {
        "position": 3,
        "value": "Review items",
        "kind": 0,
        "label": "",
        "localtime": 1417568260
      },
      {
        "position": 5,
        "value": "Core formula summary",
        "kind": 1,
        "label": "Instructor Recommended",
        "localtime": 1417538265
      }
    ]
  }
}

북마크 일괄 수정 API (Update URL)​

북마크 추가, 수정, 삭제 요청을 하나의 요청으로 결합하여 처리하는 API입니다. 전달된 Action Block 배열 내의 액션들은 배열에 포함된 순서대로 실행됩니다.

참고

일괄 수정(update) URL이 활성화된 경우, 개별 액션 URL(register, remove)은 호출되지 않고 이 API로 통합 관리됩니다.

요청 규격​

구분내용
MethodPOST
Content-Typeapplication/x-www-form-urlencoded
Parametersbookmarks (Action Block 배열의 JSON 문자열)

Action Block 구조​

액션 종류(register, remove)와 북마크 종류(공식 북마크/내 북마크)에 따라 요구되는 필드 구성이 상이합니다.

액션 종류​

  • register: 신규 북마크 추가(등록) 또는 기존 북마크 업데이트
  • remove: 특정 시점(position)의 북마크 삭제

공식 북마크​

필드타입설명registerremove
actionstring액션 종류 (register 또는 remove)◯◯
upload_file_keystring업로드 파일 키◯◯
positioninteger북마크 위치◯◯
labelstring공식 북마크 레이블◯◯
valuestring북마크 내용◯-
localtimeinteger북마크가 추가된 시각 (Unix Timestamp)◯◯

내 북마크​

필드타입설명registerremove
actionstring액션 종류 (register 또는 remove)◯◯
media_content_keystring미디어 콘텐츠 키◯◯
client_user_idstring고객사 서비스의 사용자(시청자) ID◯◯
positioninteger북마크 위치◯◯
valuestring북마크 내용◯-
localtimeinteger북마크가 추가된 시각 (Unix Timestamp)◯◯
참고

북마크 삭제(remove ) 요청 시에는 북마크 내용(value) 필드는 전달되지 않습니다.

동적 파라미터 치환​

등록된 Update URL 내 {uservalue0} ~ {uservalue9} 형식은 요청 시점에 실제 데이터로 자동 치환됩니다.

  • 등록 URL
http://abc.com/bookmark/read?LC={uservalue0}&device={uservalue9}
  • 실제 호출 URL
http://abc.com/bookmark/read?LC=LC001&device=mobile

응답 예시​

[
  {
    "action": "register",
    "media_content_key": "{MEDIA_CONTENT_KEY}",
    "client_user_id": "{END_USER_ID}",
    "position": 45,
    "value": "Key concept",
    "localtime": 1414538260,
    "LC": "LC001",
    "device": "mobile"
  },
  {
    "action": "remove",
    "media_content_key": "{MEDIA_CONTENT_KEY}",
    "client_user_id": "{END_USER_ID}",
    "position": 67,
    "localtime": 1417538260,
    "LC": "LC001",
    "device": "mobile"
  }
]

연동 흐름​

북마크 목록 조회 흐름​

북마크 추가/삭제 흐름​

구현 가이드​

고객사 서버 구현 체크리스트​

안정적인 연동을 위해 고객사 백엔드 시스템에서 반드시 준수해야 할 기술적 요구 사항입니다.

List API (목록 조회)​

  • Method: GET 요청 수신 및 처리 로직 구현
  • 파라미터 식별: upload_file_key 또는 media_content_key + client_user_id 기반의 데이터 필터링
  • 응답 규격: JSON (UTF-8) 형식 준수 및 루트(Root) 객체 구성
  • 상태 코드: 정상 처리 시 응답 객체 내 error 필드 값을 반드시 0으로 반환

Update API (일괄 수정)​

  • Method: POST 요청 수신 및 처리 로직 구현
  • 데이터 파싱: bookmarks 파라미터로 전달된 JSON 문자열 파싱
  • 순차 처리: Action Block 배열 내의 register 및 remove 액션을 인덱스 순서대로 실행
  • 데이터 치환: URL 내 포함된 uservalue{0~99} 동적 파라미터의 실제 데이터 치환 처리

에러 처리​

상황권장 처리 방식
미존재 북마크 삭제 요청요청을 무시하되 응답은 성공(error: 0)으로 반환
중복 북마크 추가 요청기존 값을 업데이트하거나, 요청을 무시하고 성공(error: 0)으로 반환
잘못된 파라미터 전달응답 객체의 error 필드에 0이 아닌 에러 코드 반환