ブックマーク連携

お知らせ

このドキュメントは機械翻訳で作成された下書きであり、現在レビュー中です。機械翻訳の特性上、一部の内容が不正確であったり、韓国語の原文と異なる場合があります。より正確な情報については、韓国語のドキュメントをご参照ください。

概要

ブックマーク連携は、Kollus プレイヤーで生成されたブックマークデータを API を通じて外部サーバー（お客様のデータベース）と同期する機能です。

ブックマークの種類

マイブックマーク ("kind": 0): ユーザーが直接追加した個人用データです。
公式ブックマーク ("kind": 1): お客様が設定した目次、チャプター、またはキーサマリー情報です。すべてのユーザーに共通で表示されます。

参考

機能の有効化: ブックマーク連携機能はデフォルトで無効になっています。この機能を有効にするには、営業担当者(jp_sales@catenoid.net)までお問い合わせください。
アカウント単位の設定: ブックマーク連携 URL はサービスアカウントごとに 1 つのみ登録可能です。（チャンネルごとの個別設定は不可）

要件

オフライン同期: ユーザーがオフライン状態で作成したブックマークデータは、オンラインに切り替わった時点で即座にサーバーに送信される必要があります。

データ送信タイミング

プラットフォーム	データ送信タイミング
モバイルアプリ	アプリのプロセスが終了するタイミングで累積データを送信
PC (JavaScript)	ブラウザのタブを閉じるか、ページ移動(unload)のタイミングで送信

API 共通パラメーター

ブックマーク関連の API リクエスト時に共通で含まれるパラメーターの仕様です。

パラメーター	タイプ	説明
`upload_file_key`	`string`	コンテンツアップロード時に発行された一意の識別子
`media_content_key`	`string`	チャンネル内コンテンツの一意の識別子
`client_user_id`	`string`	ユーザー ID
`position`	`integer`	ブックマーク位置(sec)
`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, optional)`	`media_content_key (string)` `client_user_id (string)`

動的パラメーターの置換

登録済みの List URL 内の{uservalue0}〜{uservalue9}形式は、リクエスト時点で実際のデータに自動的に置換されます。

登録 URL

https://abc.com/bookmark/read?LC={uservalue0}&device={uservalue9}

実際の呼び出し URL

https://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`	ブックマーク位置(sec)
`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)

ブックマークの追加・更新・削除リクエストを 1 つのリクエストにまとめて処理する 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

https://abc.com/bookmark/read?LC={uservalue0}&device={uservalue9}

実際の呼び出し URL

https://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（一括更新）

エラー処理