본문으로 건너뛰기

북마크 연동

개요​

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

북마크 종류​

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

요구 사항​

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

데이터 전송 시점​

플랫폼전송 시점
모바일 앱앱이 완전히 종료되는 시점에 누적된 데이터를 전송합니다.
PC (JavaScript)브라우저 탭을 닫거나 이동할 때 발생하는 페이지 종료 확인 시점에 데이터를 전송합니다.
Flash플레이어 실행 중 시스템이 설정한 주기마다 자동으로 전송합니다.

API 명세​

공통 파라미터​

API 요청 시 공통으로 포함되는 파라미터 항목입니다.

파라미터타입설명
upload_file_keystring콘텐츠 업로드 시 부여되는 콘텐츠 고유 식별자
media_content_keystring채널 내 콘텐츠의 고유 식별자
client_user_idstring고객사 서비스의 사용자(시청자) ID
positioninteger북마크 위치(단위: 초)
localtimeinteger북마크 생성 시각(Unix timestamp)
valuestring북마크 제목(& 문자 제외)
labelstring북마크 명칭
{uservalue0~9}string고객사 정의 값(uservalue0~uservalue9)
ℹ️참고
  • localtime은 서버 시간이 아닌 시청자 기기의 로컬 시간을 나타냅니다. 서버와 시간 동기화 문제가 발생할 수 있으므로 사용을 권장하지 않습니다.
  • value 및 label 필드의 플레이어 UI 표시 위치플레이어 북마크 표시 위치

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

북마크 목록 조회 API는 플레이어 실행 시 저장된 북마크 데이터를 호출하여 JSON 형식으로 반환합니다.
모든 응답 데이터는 반드시 UTF-8 인코딩을 사용해야 합니다.

요청 파라미터​

공식 북마크만 조회​

항목값
MethodGET
Parameters
  • upload_file_key (string)
  • media_content_key (string, 선택)

공식 북마크 + 내 북마크 모두 조회​

항목값
MethodGET
Parameters
  • media_content_key (string)
  • client_user_id (string)

동적 파라미터 치환(uservalue)​

등록된 List URL에 {uservalue0} ~ {uservalue9} 형식이 포함된 경우, 요청 시점에 실제 값으로 자동 치환됩니다.

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

응답 필드​

필드타입설명
errorintegerAPI 처리 결과(0: 정상)
resultobject북마크 데이터를 담은 객체
result.bookmark_labelsarray북마크 목록에 표시될 북마크 제목(예: ["Bookmark", "Index"])
result.bookmark_positionsarray북마크 데이터 리스트

bookmark_positions 항목​

필드타입설명
positioninteger북마크 위치(단위: 초)
valuestring북마크 제목
kindinteger북마크 종류
  • 0: 내 북마크
  • 1: 공식 북마크
labelstring공식 북마크 명칭(내 북마크의 경우 비어 있음)
localtimeinteger북마크 생성 시각(Unix timestamp)

응답 예시​

{
  "error": 0,
  "result": {
    "bookmark_labels": [
      "Bookmark",
      "Index"
    ],
    "bookmark_positions": [
      {
        "position": 3,
        "value": "Bookmark",
        "kind": 0,
        "label": "",
        "localtime": 1417568260
      },
      {
        "position": 5,
        "value": "Bookmark",
        "kind": 0,
        "label": "test",
        "localtime": 1417568265
      },
      {
        "position": 7,
        "value": "Index",
        "kind": 1,
        "label": "김강사님 북마크",
        "localtime": 1417538260
      },
      {
        "position": 12,
        "value": "Bookmark",
        "localtime": 1417568270
      },
      {
        "position": 13,
        "value": "Index",
        "kind": 1,
        "label": "최강사님 북마크",
        "localtime": 1417538260
      }
    ]
  }
}

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

Update URL은 다수의 북마크 변경 사항(등록 및 삭제)을 하나의 HTTP 요청으로 처리하기 위한 API입니다.
전달된 Action Block 배열 내의 액션들은 배열에 포함된 순서대로 실행됩니다.

ℹ️참고

update URL이 호출될 경우, register 및 remove URL은 별도로 호출되지 않습니다.

요청 파라미터​

항목값
MethodPOST
Content-Typeapplication/x-www-form-urlencoded
Parametersbookmarks (string) - Action Block 배열의 JSON 문자열

Action Block 구조​

액션 종류(register, remove)와 북마크 종류(공식 북마크/내 북마크)에 따라 포함되는 필드가 다릅니다.

액션 종류​

액션설명
register신규 북마크 등록 또는 기존 북마크 업데이트
remove북마크 삭제

공식 북마크​

필드타입설명registerremove
actionstring액션 종류(register 또는 remove)◯◯
upload_file_keystring업로드 파일 키◯◯
positioninteger북마크 위치◯◯
labelstring공식 북마크 명칭◯◯
valuestring북마크 제목◯-
localtimeinteger북마크 생성 시각◯◯

내 북마크​

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

북마크 삭제(remove ) 요청 시에는 북마크 제목(value) 필드가 제외됩니다.

동적 파라미터 치환(uservalue)​

등록된 Update URL에 {uservalue0} ~ {uservalue9} 형식이 포함된 경우, 요청 시점에 실제 값으로 자동 치환됩니다.

  • 등록된 URL 예시: http://abc.com/bookmark/update?LC={uservalue0}&device={uservalue9}
  • 치환 값
    • uservalue0: LC001
    • uservalue9: mobile
  • 실제 호출 URL: http://abc.com/bookmark/update?LC=LC001&device=mobile

응답 예시​

[
  {
    "action": "register",
    "media_content_key": "x53gaH3a",
    "client_user_id": "test_user_id",
    "position": 45,
    "value": "새 북마크 제목",
    "localtime": 1414538260,
    "LC": "LC001",
    "device": "mobile"
  },
  {
    "action": "remove",
    "media_content_key": "x53gaH3a",
    "client_user_id": "test_user_id",
    "position": 67,
    "localtime": 1417538260,
    "LC": "LC001",
    "device": "mobile"
  }
]

연동 흐름​

북마크 목록 조회 흐름​

북마크 목록 조회 흐름

북마크 등록/삭제 흐름​

북마크 등록/삭제 흐름

구현 가이드​

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

List API​

  • GET 요청을 수신하고 처리할 수 있어야 합니다.
  • upload_file_key 또는 media_content_key + client_user_id 파라미터를 식별하고 처리해야 합니다.
  • 응답 데이터는 반드시 JSON UTF-8 형식을 준수해야 합니다.
  • 요청이 정상적으로 처리됐을 때 응답 객체의 error 필드 값은 반드시 0이어야 합니다.

Update API​

  • POST 요청을 수신하고 처리할 수 있어야 합니다.
  • bookmarks 파라미터로 전달되는 JSON 문자열을 올바르게 파싱해야 합니다.
  • register 및 remove 액션을 전달된 순서대로 처리해야 합니다.
  • URL 내 {uservalue0~9} 파라미터를 실제 값으로 치환할 수 있어야 합니다.

에러 처리​

상황권장 처리 방식
존재하지 않는 북마크 삭제 요청해당 액션을 무시하되, 성공(0)으로 응답하여 클라이언트 측의 예외 발생을 방지합니다.
중복된 북마크 등록 요청기존 값을 새 값으로 업데이트하거나, 중복 에러 없이 요청을 무시한 뒤 성공(0)으로 응답합니다.
잘못된 파라미터 전달응답 객체의 error 필드에 0이 아닌 에러 코드를 반환합니다.