API Specifications for ULIZA Player (Cloud) (v1.2.1)

本書は ULIZA Player (Cloud) が提供する API 仕様について記述しています。ULIZA Player (Cloud) の機能や管理画面の操作方法については ULIZA Player (Cloud) User Guide を参照してください。

なお、本書に掲載しているコードサンプル(Request samples)は、具体的な実装例を示すことで開発者を支援することを目的としていますが、掲載しているコードがすべての環境において正常に動作することを保証するものではありません。また、コードサンプル内で使用している関数やライブラリの安全性に関して、弊社は何ら責任を負うものではありません。

CHANGELOG

バージョン 改版日 改版内容
v1.0.0 2019/11/02 初版
v1.0.1 2019/11/25 「プレイリストタグ API」の「リクエスト」および「レスポンス」に関する記述を追加しました。
v1.1.0 2020/01/30 仕様書を Web 形式に変更しました。
v1.1.1 2020/06/15 「プレイヤータグ API」および「Option Parameters」の項目を追加しました。
v1.1.2 2020/10/07 「プレイヤータグ API」の項目を追加しました。
v1.1.3 2020/11/11 「Option Parameters」の項目を追加しました。
v1.1.4 2020/12/23 「Option Parameters」の項目を追加しました。
v1.1.5 2021/02/15 「プレイヤータグ API」および「Option Parameters」の項目を追加しました。
v1.1.6 2021/04/28 「プレイヤータグ API」および「Option Parameters」の項目を追加しました。
v1.1.7 2021/10/19 「Option Parameters」の項目を追加しました。
v1.1.8 2022/02/07 「Option Parameters」の項目を追加しました。
v1.1.9 2022/03/16 「プレイヤータグ API」および「Option Parameters」の項目を追加しました。
v1.2.0 2023/10/18 「プレイリストタグ API」および「Option Parameters」の項目を変更しました。
v1.2.1 2024/04/11 「プレイヤータグ API」の項目を変更しました。

Authentication

認証について以下に記述します。

BearerAuth

特に断りのない限り、本書に記載されている全ての API に対するリクエストの Authorization ヘッダに下記の形式で有効な API 認証キーを含める必要があります。API 認証キーの取得方法については ULIZA プロダクトアカウント User Guide を参照してください。リクエストに有効な API 認証キーが含まれていない場合は、401 Unauthorized が返却されます。

Security Scheme Type HTTP
HTTP Authorization Scheme Bearer

Publish

プレイヤータグ API およびプレイリストタグ API について以下に記述します。

プレイヤータグ API

get /players/{player-id}
https://player-api.p.uliza.jp/v1/players/{player-id}

プレイヤータグ API は ULIZA Player (HTML5) を読み込む JavaScript を取得します。

Authorizations:
path Parameters
player-id
required
string <= 50 characters ^[0-9a-zA-Z-_%]+$

プレイヤーID

query Parameters
video
string <uri>

動画ファイルのURL

video, name, code のいずれかが 必須 です。

poster
string <uri>

再生前画像ファイルのURL

name
string

ULIZA VMS (Cloud) のコンテンツ名

video, name, code のいずれかが 必須 です。

ss
string

ULIZA VMS (Cloud) のストリームセット名

指定する場合は name の指定が 必須 です。

code
string

ULIZA VMS Generation 4.0 のエピソードコード

video, name, code のいずれかが 必須 です。

指定する場合はプレイヤープリセットのG4 事業者 ID の指定が 必須 です。

targetid
string

ターゲットエレメント ID 指定した ID を持つ HTML エレメント( div エレメントなど)の子エレメントとしてプレイヤーを埋め込みます。

playerobjectname
string

プレイヤーオブジェクト名

プレイヤーオブジェクトが指定した名前で JavaScript のグローバルオブジェクトとして定義されます。

アカウントに「プレイヤーインスタンスの取得」権限が 必須 です。

options
string

オプションパラメータの変数名

type
string
Enum: "normal" "modal" "floating" "presentation" "chapter" "subtitlelist" "multiAngle"

プレイヤータグタイプ

mobileNormal
boolean

モバイル再生時プレイヤータグタイプ標準

Responses

200

成功/非配信時/ドメイン制限時

Response Schema: text/javascript
any

成功
ULIZA Player (HTML5) を読み込む JavaScript を返却

非配信時
非配信時に表示する画像をプレイヤープリセットの設定と同じサイズで表示する JavaScript を返却

ドメイン制限時
ドメイン制限時に表示する画像をプレイヤープリセットの設定と同じサイズで表示する JavaSript を返却

400

パラメータの不足

401

許可されていないリクエスト

404

存在しないプレイヤー/存在しない連携プリセット/「プレイヤーの取得」権限の不足

500

サーバ内部エラー

Request samples

Copy
curl \
  -H 'Authorization: Bearer <your-token>' \
  'https://player-api.p.uliza.jp/v1/players/sample_player?video=https%3A%2F%2Fhost%2Fpath%2Fplaylist.m3u8'

プレイリストタグ API

get /playlists/{player-id}
https://player-api.p.uliza.jp/v1/playlists/{player-id}

プレイリストタグ API は ULIZA Player (HTML5) 及びプレイリストを読み込む JavaScript を取得します。プレイヤーの取得がAPIに限定されているプレイヤーは指定できません。

Authorizations:
path Parameters
player-id
required
string <= 50 characters ^[0-9a-zA-Z-_%]+$

プレイヤーID

query Parameters
name
string

ULIZA VMS (Cloud) のプレイリスト名

name, code, playlistItems のいずれかが 必須 です。

code
string

ULIZA VMS Generation 4.0 のプレイリストコード

name, code, playlistItems のいずれかが 必須 です。

指定する場合はプレイヤープリセットのG4 事業者 ID の指定が 必須 です。

ss
string

ULIZA VMS (Cloud) のストリームセット名

指定する場合は name の指定が 必須 です。

options
string

オプションパラメータの変数名

Responses

200

成功/ドメイン制限時

Response Schema: text/javascript
any

成功
ULIZA Player (HTML5) を読み込む JavaScript を返却

ドメイン制限時
ドメイン制限時に表示する画像をプレイヤープリセットの設定と同じサイズで表示する JavaSript を返却

400

パラメータの不足/APIに限定されているプレイヤーを指定

401

許可されていないリクエスト

404

存在しないプレイヤー/存在しない連携プリセット/「プレイヤーの取得」権限の不足

500

サーバ内部エラー

Request samples

Copy
curl \
  -H 'Authorization: Bearer <your-token>' \
  'https://player-api.p.uliza.jp/v1/playlists/sample_player?options=mySettings'

Option Parameters

for Player Tag API

プレイヤータグ API を使用したページ内の JavaScript でプレイヤーを設定できます。プレイヤータグのレスポンスより前にクエリパラメータ options で指定した変数名で JavaScript のグローバルオブジェクトとして定義してください。指定できるプロパティは以下のとおりです。

  • posterSlideShow

    プロパティ 説明 タイプ
    enable 再生前スライドショー機能の有効/無効 boolean
    posters 画像ファイルの URL のリスト array <string>
    interval 再生前スライドショーのインターバル(ミリ秒) integer
  • seekpreview

    プロパティ 説明 タイプ
    enable シークプレビュー機能の有効/無効 boolean
    url シークプレビュー画像ファイルの URL string <uri>
  • subtitles

    プロパティ 説明 タイプ
    enable 字幕機能の有効/無効 boolean
    src 字幕のリスト
    labelurl をキーとし、字幕ラベルと字幕ファイル URL を値とした object を 1 セットとし配列に格納します。
    • label
      字幕ラベル
    • url
      字幕ファイル URL
    array <object>
    defaultIndex 初期字幕インデックス integer
    subtiteDisplay 字幕リスト表示の有効/無効 boolean
    listType 字幕リスト表示位置 enum:
    "right" 右に字幕リスト
    "bottom" 下に字幕リスト
    "left" 左に字幕リスト
    "top" 上に字幕リスト
    parentElementId 字幕リスト領域ターゲットエレメント ID string
    fontColor 字幕リスト文字色 string
    selectedFontColor 選択時の字幕リスト文字色 string
    hoverFontColor ホバー時の字幕リスト文字色 string
    timeFontColor 字幕リストの時間文字色 string
    selectedTimeFontColor 選択時の字幕リストの時間文字色 string
    hoverTimeFontColor ホバー時の字幕リストの時間文字色 string
    listBackgroundColor 字幕リスト背景色 string
    selectedBackgroundColor 選択時の字幕リスト背景色 string
    hoverBackgroundColor ホバー時の字幕リスト背景色 string
    scrollbarTrackColor 字幕リストスクロールバートラック色 string
    scrollbarFaceColor 字幕リストスクロールバーつまみ色 string
    headerFontColor 字幕リストヘッダー文字色 string
    headerBackgroundColor 字幕リストヘッダー背景色 string
    searchFontColor 字幕リスト検索窓文字色 string
    searchBackgroundColor 字幕リスト検索窓背景色 string
  • html5

    プロパティ 説明 タイプ
    keySystem DRM 設定
    • com.widevine.alpha
      MPEG-DASH (Widevine) のライセンス要求 URL
    • com.microsoft.playready
      MPEG-DASH (PlayReady) のライセンス要求 URL
    object
  • videoAnalytics

    プロパティ 説明 タイプ
    enable ULIZA Video Analytics (Cloud) 連携機能の有効/無効 boolean
    userId 独自ユーザー ID string
    trackingId ビーコンの送信先識別子 string
    contentCategory コンテンツカテゴリ string
    contentTitle コンテンツタイトル
    指定しない場合は、動画ファイルURLのパスとクエリ文字列を使用します。
    string
    enableReaction リアクション機能の有効/無効 boolean
    iconId リアクションボタンアイコン enum:
    "uliza-icon-thumbs-up"
    サムズアップマーク
    "uliza-icon-thumbs-down"
    サムズダウンマーク
    "uliza-icon-question"
    ハテナマーク
    "uliza-icon-exclamation"
    ビックリマーク
    "uliza-icon-circle"
    マルマーク
    "uliza-icon-cross"
    バツマーク
    label リアクションボタンラベル string
  • beacon

    プロパティ 説明 タイプ
    enable ビーコン機能の有効/無効 boolean
    url ビーコン送信 URL string <uri>
    requestHeaders 追加 HTTP ヘッダ
    キーと値をヘッダ名とヘッダ値としたセットを objectに列挙します。
    object
  • advertising

    プロパティ 説明 タイプ
    enable 広告機能の有効/無効 boolean
    ulizaAdId 簡易動画広告 ID string
    vmapUrl VMAP 取得 URL string <uri>
    vastUrl VAST 取得 URL string <uri>
  • resumePlayback

    プロパティ 説明 タイプ
    enable レジューム再生機能の有効/無効 boolean
    startPosition 再生開始位置(秒) integer
  • modal

    プロパティ 説明 タイプ
    sizeAuto サムネイルサイズ自動調整の有効/無効 boolean
    width サムネイル幅(ピクセルまたは%) string
    height サムネイル高さ(ピクセルまたは%) string
    modalMaxWidth モーダルプレイヤーの最大幅を設定の有効/無効 boolean
    maxWidth モーダルプレイヤーの最大幅 string
    background 背景クリック時挙動 enum:
    "default" モーダルを閉じない
    "backdrop" モーダルを閉じる
    zIndex z-index integer
    thumbnail サムネイル画像ファイルURL string <uri>
    appendToBody モーダルのエレメントをBODY要素直下に追加 boolean
  • floating

    プロパティ 説明 タイプ
    position 表示位置 enum:
    "TopLeft" 左上
    "TopRight" 右上
    "BottomLeft" 左下
    "BottomRight" 右下
    width integer
    margin 余白 integer
    afterStarting 再生開始まで無効 boolean
  • filler

    プロパティ 説明 タイプ
    enable エラーフィラー機能の有効/無効 boolean
    type フィラータイプ enum:
    "image" 画像
    "video" 動画
    "page" ページ遷移
    url フィラー URL string <uri>
  • adBlockFiller

    プロパティ 説明 タイプ
    enable 広告ブロックフィラー機能の有効/無効 boolean
    type フィラータイプ enum:
    "image" 画像
    "video" 動画
    "page" ページ遷移
    url フィラー URL string <uri>
  • playbackRange

    プロパティ 説明 タイプ
    enable 切り出し再生機能の有効/無効 boolean
    startSeconds 切り出し再生開始位置(秒) integer
    endSeconds 切り出し再生終了位置(秒) integer
    enum:
    "end" 終端
  • chapter

    プロパティ 説明 タイプ
    enable チャプター機能の有効/無効 boolean
    display チャプターリスト表示の有効/無効 boolean
    chapterType チャプタータイプ enum:
    "right" 右にチャプター
    "bottom" 下にチャプター
    "left" 左にチャプター
    "top" 上にチャプター
    item チャプター情報
    startTimetitlethumbnailUrl をキーとし、再生開始位置とタイトルとサムネイル画像ファイル URL を値とした object を 1 セットとし配列に格納します。
    • startTime
      再生開始位置
    • title
      タイトル
    • thumbnailUrl
      サムネイル画像ファイル URL
    array <object>
    parentElementId チャプター領域ターゲットエレメント ID string
    fontColor チャプターリスト文字色 string
    selectedFontColor 選択時のチャプターリスト文字色 string
    hoverFontColor ホバー時のチャプターリスト文字色 string
    timeFontColor チャプターリストの時間文字色 string
    selectedTimeFontColor 選択時のチャプターリストの時間文字色 string
    hoverTimeFontColor ホバー時のチャプターリストの時間文字色 string
    backgroundColor チャプターリスト背景色 string
    selectedBackgroundColor 選択時のチャプターリスト背景色 string
    hoverBackgroundColor ホバー時のチャプターリスト背景色 string
    scrollbarTrackColor チャプターリストスクロールバートラック色 string
    scrollbarFaceColor チャプターリストスクロールバーつまみ色 string
  • presentation

    プロパティ 説明 タイプ
    display プレゼンテーション表示の有効/無効 boolean
    presentationType プレゼンテーションの表示形式 enum:
    "right_normal" 右にプレゼンテーション
    "left_normal" 左にプレゼンテーション
    playerSizeAutoRatio プレイヤーサイズ自動調整有効時の横幅比率 integer;
    documentUrl PDF ファイル URL string <uri>
    parentElementId ターゲットエレメント ID string
  • customLayer

    プロパティ 説明 タイプ
    enable カスタムレイヤー機能の有効/無効 boolean
    className カスタムレイヤーに追加するクラス属性 string
  • title

    プロパティ 説明 タイプ
    enable タイトル機能の有効/無効 boolean
    textJa 日本語のタイトル string
    text 日本語以外のタイトル string
  • multiAngle

    プロパティ 説明 タイプ
    enable マルチアングル動画機能の有効/無効 boolean
    angle アングル数 integer
    angleLabels アングルラベル array <string>
    display マルチアングルリスト表示の有効/無効 boolean
    angleListType マルチアングルリスト表示位置 enum:
    "right" 右にリスト
    "bottom" 下にリスト
    "left" 左にリスト
    "top" 上にリスト
    fontColor マルチアングルリスト文字色 string
    selectedIconColor 選択時のマルチアングルリストのラベルのアイコン色/枠色 string
    backgroundColor マルチアングルリスト背景色 string
    labelBackgroundColor マルチアングルリストのラベルの背景色 string
    hoverColor ホバー時のマルチアングルリストカバー色 string
    cannotOperateColor 操作不可時のマルチアングルリストカバー色 string
    scrollbarTrackColor マルチアングルリストスクロールバートラック色 string
    scrollbarFaceColor マルチアングルリストスクロールバーつまみ色 string
    defaultIndex 初期アングルインデックス integer
  • オプションパラメータの例

    <script type="text/javascript" charset="utf-8">
     // オプションパラメータを使用して字幕とビーコンの設定をする。
      mySettings = {
        subtitles: {
          enable: true,
          src: [
          {
            label: "日本語",
            src: "https://host/path/ja.vtt",
          },
          {
            label: "英語",
            src: "https://host/path/eng.vtt",
          },
          ],
          defaultIndex: 1,
        },
        beacon: {
          enable: true,
          url: "https://host/path/beacon.php",
          requestHeaders: {
          myheader1: "value1",
          myheader2: "value2",
          },
        },
      };
    </script>

for Playlist Tag API

プレイリストタグ API を使用したページ内の JavaScript でプレイヤーを設定できます。プレイヤータグのレスポンスより前にクエリパラメータ options で指定した変数名で JavaScript のグローバルオブジェクトとして定義してください。指定できるプロパティは以下のとおりです。

  • player

    プロパティ 説明 タイプ
    targetId プレイヤーのターゲットエレメント ID string
  • playlist

    プロパティ 説明 タイプ
    playlistType プレイリストの表示形式 enum:
    "right_normal" 右ノーマル (default)
    "right_simple" 右シンプル
    "bottom_normal" 下ノーマル
    "bottom_simple" 下シンプル
    "left_normal" 左ノーマル
    "left_simple" 左シンプル
    "top_normal" 上ノーマル
    "top_simple" 上シンプル
    fontColor プレイリスト文字色 string
    backgroundColor プレイリスト背景色 string
    selectedBackgroundColor 選択時のプレイリスト背景色 string
    hoverBackgroundColor ホバー時のプレイリスト背景色 string
    scrollbarTrackColor プレイリストスクロールバートラック色 string
    scrollbarFaceColor プレイリストスクロールバーつまみ色 string
    targetId プレイリストのターゲットエレメント ID string
    repeatType リピートタイプ enum:
    "none" リピートしない
    "all" 全件リピート
    "one" 1 件リピート
    defaultIndex 初期インデックス integer
    playlistObjectName プレイリストオブジェクト名
    ※ アカウントに「プレイヤーオブジェクト取得」権限が必要です。
    string
  • playlistItems

    • content
      プロパティ 説明 タイプ
      title コンテンツタイトル string
      description コンテンツの説明 string
      thumbUrl サムネイル画像ファイルの URL string <uri>
      video 再生する動画ファイルの URL integer
      code ULIZA VMS Generation 4.0 のエピソードコード string
    • poster
      説明 タイプ
      再生前画像ファイルの URL string
    • posterSlideShow
      プロパティ 説明 タイプ
      enable 再生前スライドショー機能の有効/無効 boolean
      posters 画像ファイルの URL のリスト array <string>
      interval 再生前スライドショーのインターバル(ミリ秒) integer
    • seekpreview
      プロパティ 説明 タイプ
      enable シークプレビュー機能の有効/無効 boolean
      url シークプレビュー画像ファイルの URL string <uri>
    • subtitles
      プロパティ 説明 タイプ
      enable 字幕機能の有効/無効 boolean
      src 字幕のリスト
      labelurl をキーとし、字幕ラベルと字幕ファイル URL を値とした object を 1 セットとし配列に格納します。
      • label
        字幕ラベル
      • url
        字幕ファイル URL
      array <object>
      defaultIndex 初期字幕インデックス integer
    • videoAnalytics
      プロパティ 説明 タイプ
      enable ULIZA Video Analytics (Cloud) 連携機能の有効/無効 boolean
      userId 独自ユーザー ID string
      trackingId ビーコンの送信先識別子 string
      contentCategory コンテンツカテゴリ string
      contentTitle コンテンツタイトル
      指定しない場合は、動画ファイルURLのパスとクエリ文字列を使用します。
      string
    • beacon
      プロパティ 説明 タイプ
      enable ビーコン機能の有効/無効 boolean
      url ビーコン送信 URL string <uri>
      requestHeaders 追加 HTTP ヘッダ
      キーと値をヘッダ名とヘッダ値としたセットを objectに列挙します。
      object
    • advertising
      プロパティ 説明 タイプ
      enable 広告機能の有効/無効 boolean
      vmapUrl VMAP 取得 URL string <uri>
      vastUrl VAST 取得 URL string <uri>
    • title
      プロパティ 説明 タイプ
      enable タイトル機能の有効/無効 boolean
      textJa 日本語のタイトル string
      text 日本語以外のタイトル string