북마크 연동

개요

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

북마크 종류

내 북마크("kind": 0): 시청자가 직접 추가한 개인용 데이터입니다.
공식 북마크("kind": 1): 고객사가 설정한 목차, 챕터 또는 핵심 요약 정보입니다. 모든 시청자에게 공통으로 노출됩니다.

ℹ️참고

계정 단위 설정: 북마크 연동 URL은 서비스 계정당 1개만 등록 가능합니다. (채널별 개별 설정 불가)
기능 활성화: 북마크 연동 기능은 기본적으로 비활성화되어 있습니다. 해당 기능을 활성화하려면 기술 지원팀(PE, tech_support@catenoid.net)으로 문의해 주세요.

요구 사항

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

데이터 전송 시점

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

API 공통 파라미터

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

파라미터	타입	설명
`upload_file_key`	string	콘텐츠 업로드 시 발급된 고유 식별자
`media_content_key`	string	채널 내 콘텐츠 고유 식별자
`client_user_id`	string	시청자 ID
`position`	integer	북마크 위치 (s)
`localtime`	integer	북마크가 추가된 시각 (Unix Timestamp)
`label`	string	북마크 레이블
`value`	string	북마크 내용
`uservalue{0~99}`	string	고객사 정의 값 (`uservalue0`~`uservalue99`)

ℹ️참고

시간 동기화: localtime은 서버 시간이 아닌 시청자 디바이스의 로컬 시간을 나타냅니다. 네트워크 환경에 따라 서버와 오차가 발생할 수 있으므로 기록용 외의 로직 활용은 권장하지 않습니다.
UI 매핑: label은 북마크의 상위 카테고리 이름, value는 개별 북마크의 제목을 결정합니다.

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

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

요청 규격

구분	공식 북마크	공식 북마크 + 내 북마크
Method	`GET`	`GET`
Parameters	`upload_file_key` (string) `media_content_key` (string, 선택)	`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

응답 필드

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

bookmark_positions 항목

필드	타입	설명
`position`	integer	북마크 위치 (s)
`value`	string	북마크 내용
`kind`	integer	북마크 종류 `0`: 내 북마크 `1`: 공식 북마크
`label`	string	공식 북마크 레이블 (내 북마크인 경우 빈 문자열)
`localtime`	integer	북마크가 추가된 시각 (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로 통합 관리됩니다.

요청 규격

구분	내용
Method	`POST`
Content-Type	application/x-www-form-urlencoded
Parameters	`bookmarks` (`Action Block` 배열의 JSON 문자열)

Action Block 구조

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

액션 종류

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

공식 북마크

필드	타입	설명	`register`	`remove`
`action`	string	액션 종류 (`register` 또는 `remove`)	◯	◯
`upload_file_key`	string	업로드 파일 키	◯	◯
`position`	integer	북마크 위치	◯	◯
`label`	string	공식 북마크 레이블	◯	◯
`value`	string	북마크 내용	◯	-
`localtime`	integer	북마크가 추가된 시각 (Unix Timestamp)	◯	◯

내 북마크

필드	타입	설명	`register`	`remove`
`action`	string	액션 종류 (`register` 또는 `remove`)	◯	◯
`media_content_key`	string	미디어 콘텐츠 키	◯	◯
`client_user_id`	string	고객사 서비스의 사용자(시청자) ID	◯	◯
`position`	integer	북마크 위치	◯	◯
`value`	string	북마크 내용	◯	-
`localtime`	integer	북마크가 추가된 시각 (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이 아닌 에러 코드 반환

개요​

북마크 종류​

요구 사항​

데이터 전송 시점​

API 공통 파라미터​

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

요청 규격​

동적 파라미터 치환​

응답 필드​

bookmark_positions 항목​

응답 예시​

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

요청 규격​

Action Block 구조​

액션 종류​

공식 북마크​

내 북마크​

동적 파라미터 치환​

응답 예시​

연동 흐름​

북마크 목록 조회 흐름​

북마크 추가/삭제 흐름​

구현 가이드​

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

List API (목록 조회)​

Update API (일괄 수정)​

에러 처리​

개요

북마크 종류

요구 사항

데이터 전송 시점

API 공통 파라미터

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

요청 규격

동적 파라미터 치환

응답 필드

bookmark_positions 항목

응답 예시

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

요청 규격

Action Block 구조

액션 종류

공식 북마크

내 북마크

동적 파라미터 치환

응답 예시

연동 흐름

북마크 목록 조회 흐름

북마크 추가/삭제 흐름

구현 가이드

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

List API (목록 조회)

Update API (일괄 수정)

에러 처리