メインコンテンツまでスキップ

ブックマーク連携

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

ブックマークの種類​

  • マイブックマーク ("kind": 0): ユーザーが直接追加した個人用データです。
  • 公式ブックマーク ("kind": 1): お客様が設定した目次、チャプター、またはキーサマリー情報です。すべてのユーザーに共通で表示されます。
参考
  • 機能の有効化: ブックマーク連携機能はデフォルトで無効になっています。この機能を有効にするには、営業担当者(jp_sales@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は個別ブックマーク項目のテキストです。 bookmark UI

ブックマーク一覧取得 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
https://abc.com/bookmark/read?LC={uservalue0}&device={uservalue9}
  • 実際の呼び出し URL
https://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)​

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