# 組み込み方法（iOS）
# はじめに
# 開発環境について
Xcode26.1およびiOS SDK26.1でのビルドをサポートします。また、arm64のアーキテクチャの実機向けのビルドに対応しています。Emulator向けのビルドおよび動作はサポートしていません。開発言語は、上記のXcodeバージョンに対応したObjective-CおよびSwiftをサポートします。
# プレイヤーリリースファイル
プレイヤーのリリースファイルには以下を含みます。
# frameworkフォルダ
プレイヤーのXCFrameworkフォルダと、プレイヤーが使用する外部モジュールを含みます。
プレイヤーのXCFrameworkファイルは以下の通りです。
- UlizaPlayer.xcframework
- リリース用プレイヤーXCFramework
- UlizaPlayer_debug.xcframework
- デバッグ用プレイヤーXCFramework
デバッグログを出力するため、リリースするアプリには使用しないでください。
プレイヤーが使用する外部モジュールは以下の通りです。
- GoogleCast.framework
- widevine_release/widevine_cdm_secured_ios.framework（リリース用）
- widevine_release/ShakaPlayerEmbedded.FFmpeg.framework（リリース用）
- widevine_release/ShakaPlayerEmbedded.framework（リリース用）
- widevine_dev/widevine_cdm_secured_ios.framework（開発用）
- widevine_dev/ShakaPlayerEmbedded.FFmpeg.framework（開発用）
- widevine_dev/ShakaPlayerEmbedded.framework（開発用）
# resourceフォルダ
プレイヤーが使用するリソースファイルを含みます。
- application.json
- 環境変数設定ファイル
環境変数の設定を参照して適切に変更してください。
# ビルドの設定
# プレイヤーのファイルの追加
プレイヤーを組み込むアプリのXcodeプロジェクトにプレイヤーのリリースファイル一式を追加してください。
# Frameworks, Libraries, and Embedded Contentの設定
プレイヤーを組み込むアプリのFrameworks, Libraries, and Embedded Contentに、以下のライブラリおよびFrameworkを追加してください。
| Framework | Embed | 備考 |
|---|---|---|
| プレイヤーのXCFramework | Embed & Sign | frameworkフォルダを参照 |
| AVFoundation.framework | Do Not Embed | |
| CoreMedia.framework | Do Not Embed | |
| GoogleCast.framework | Embed & Sign | プレイヤーリリースファイルに含まれるものを追加してください。 |
| widevine_cdm_secured_ios.framework | Embed & Sign | プレイヤーリリースファイルに含まれるものを追加してください。 |
| ShakaPlayerEmbedded.FFmpeg.framework | Embed & Sign | プレイヤーリリースファイルに含まれるものを追加してください。 |
| ShakaPlayerEmbedded.framework | Embed & Sign | プレイヤーリリースファイルに含まれるものを追加してください。 |
widevine_release、widevine_devの外部モジュールについての注意点
Xcodeからデバッグ実行する際は、widevine_dev配下の外部モジュールを使用してください。デバッグ実行する場合、widevine_releaseの外部モジュールを使用しているとDASH(Widevine)コンテンツを再生する際にクラッシュします。また、widevine_dev配下の外部モジュールは、必ずデバッグ用プレイヤーライブラリとセットで使用してください。
# Copy Bundle Resourcesの設定
プレイヤーを組み込むアプリのCopy Bundle Resourcesに以下のファイルを追加してください。
- application.json
# Other Linker Flagsの設定
プレイヤーを組み込むアプリのOther Linker Flagsに、以下のフラグを追加してください。
- -ObjC
# アプリの起動スキームの設定
プレイヤーを組み込むアプリのURL Typesにプレイヤーを起動するSchemeを追加してください。URL Schemesには環境変数設定ファイルで設定したインテント起動用URLスキームと同じ値、Identifierにはアプリで適切な識別子を指定してください。
# アプリのCapabilitiesの設定
外部出力が有効なプレイヤーを使用する場合は、アプリのCapabilitiesの設定画面よりBackground Modesを有効にし、下記項目にチェックを入れてください。
- Audio, AirPlay and Picture in Picture
- Background fetch
バックグラウンド再生が有効なプレイヤーを使用する場合は、アプリのCapabilitiesの設定画面よりBackground Modesを有効にし、下記項目にチェックを入れてください。
- Audio, AirPlay and Picture in Picture
# Bitcodeの設定
アプリのBuild Settingsの設定画面より、Build OptionsセクションのEnable Bitcodeの設定値をNoに変更してください。
# App Transport Securityの設定
アプリ設定画面のInfoタブのCustom iOS Target PropertiesセクションにApp Transport Security SettingsのKeyを追加してください。App Transport Security Settingsの子要素としてNSAllowsLocalNetworkingを追加し、値をYESに変更してください。
# UIDesignRequiresCompatibilityの設定
アプリ設定画面のInfoタブのCustom iOS Target PropertiesセクションにUIDesignRequiresCompatibilityを追加し、値をYESに変更してください。
# Application Scene Manifestの設定
アプリ設定画面のInfoタブのCustom iOS Target PropertiesセクションにApplication Scene Manifestを追加してください。
Application Scene Manifestの子要素としてEnable Multiple Scenesを追加し、値をNOに変更してください。
Application Scene Manifestの子要素としてScene Configurationを追加してください。Scene Configurationの子要素としてWindow Application Session Roleを追加してください。
Window Application Session Roleの子要素にConfiguration Nameを追加し、値をDefault Configurationに変更してください。
Window Application Session Roleの子要素にDelegate Class Nameを追加し、値を$(PRODUCT_MODULE_NAME).SceneDelegateに変更してください。
# Strip Styleの設定
アプリのBuild Settingsの設定画面より、DeploymentセクションのStrip Styleの設定値をNon-Global Symbolsに変更してください。
# 実装
# 継承
アプリのUIApplicationDelegateを実装するクラスで以下の通りに実装してください。
- UlizaPlayerのXCFrameworkのUlizaApplicationDelegate.hをImportしてください。
- UlizaApplicationDelegateクラスを継承してください。
# UIKit sceneベースライフサイクルのアプリの場合
アプリのUIWindowSceneDelegateを実装するクラスで、以下の通りに実装してください。
- UISceneDelegateのscene(_:willConnectTo:options:)でUIApplicationのopen(_:options:completionHandler:)を実行してください。
- UISceneDelegateのscene(_:openURLContexts:)でUIApplicationのopen(_:options:completionHandler:)を実行してください。
以下にSceneDelegateの実装例を示します。
import UIKit
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
if let urlContext = connectionOptions.urlContexts.first {
let url = urlContext.url
DispatchQueue.main.async {
_ = UIApplication.shared.delegate?.application?(UIApplication.shared, open: url, options: [:])
}
}
}
func scene(_ scene: UIScene, openURLContexts urlContexts: Set<UIOpenURLContext>) {
guard let urlContext = urlContexts.first else { return }
let url = urlContext.url
DispatchQueue.main.async {
_ = UIApplication.shared.delegate?.application?(UIApplication.shared, open: url, options: [:])
}
}
// 他のSceneDelegateの実装は省略。
}
# View Controller
# UIKit appベースライフサイクルのアプリの場合
アプリのView Controllerが以下のいずれかの条件を満たす必要があります。
- UIApplicationDelegate#window#rootViewControllerがUINavigationController（またはUINavigationControllerのサブクラス）であること。
- UIApplicationDelegate#window#rootViewControllerがUITabBarController（またはUITabBarControllerのサブクラス）で、かつそのUITabBarControllerのプロパティselectedViewControllerがUINavigationController（またはUINavigationControllerのサブクラス）であること。
# UIKit sceneベースライフサイクルのアプリの場合
アプリのView Controllerが以下のいずれかの条件を満たす必要があります。
- UIWindowSceneDelegate#window#rootViewControllerがUINavigationController（またはUINavigationControllerのサブクラス）であること。
- UIWindowSceneDelegate#window#rootViewControllerがUITabBarController（またはUITabBarControllerのサブクラス）で、かつそのUITabBarControllerのプロパティselectedViewControllerがUINavigationController（またはUINavigationControllerのサブクラス）であること。
# ビーコン
アプリ内でビーコン情報を受信する場合は、UlizaPlayerのXCFrameworkのUlizaBeaconNotification.hをImportしたうえで実装してください。以下に実装例を示します。
import Foundation
class BeaconNotificationObserver: NSObject {
func startObserving() {
NotificationCenter.default.addObserver(
self,
selector: #selector(handleBeaconNotification(_:)),
name: NSNotification.Name(rawValue: NSNotification.Name.UlizaPlayerBeacon.rawValue),
object: nil
)
}
func stopObserving() {
NotificationCenter.default.removeObserver(
self,
name: NSNotification.Name(rawValue: NSNotification.Name.UlizaPlayerBeacon.rawValue),
object: nil
)
}
@objc private func handleBeaconNotification(_ notification: Notification) {
guard let userInfo = notification.userInfo, !userInfo.isEmpty else {
return
}
let sortedKeys = userInfo.keys.sorted { $0.description < $1.description }
let paramStrings = sortedKeys.map { key in
let value = userInfo[key] ?? ""
return "\(key)=\(value)"
}
let allParams = paramStrings.joined(separator: " | ")
}
deinit {
stopObserving()
}
}
# 環境変数の設定
プレイヤーが正しく動作するには環境変数設定ファイル（application.json）に適切に環境変数を設定してください。環境変数設定ファイルはJSONフォーマットです。「フィールド」の列は環境変数設定ファイル内のJSONオブジェクトのname、「データタイプ」とはJSONオブジェクトのvalueの型を指します。
# アプリ基本設定値
プレイヤーの基本機能を提供する環境変数です。
- LaunchUriScheme: 文字列
- インテント起動用URLスキーム
- EnvironmentURL: 文字列
- プレイヤー環境変数取得URL
未設定の場合は、サーバー上から環境変数を取得しません。
# ビーコン
プレイヤーがビーコン送信を使用する際に設定が必要となる環境変数です。
- TrackURL: 文字列
- ビーコン送信URL
コンテンツ再生時に送信するビーコンの送信先URLです。 - TrackingIntervalSeconds: 数値＜秒＞
- ビーコン送信間隔
コンテンツ再生時に送信するビーコンの間隔値です。
# DRMコンテンツの再生の環境変数
以下に示すDRMにより暗号化されたコンテンツの再生時に使用する環境変数です。
- DASH(Widevine)コンテンツ
これらのコンテンツを再生しない場合、これらの環境変数は設定する必要はありません。
- WvDrmServerURL2: 文字列
- DASH(Widevine)コンテンツライセンス要求URL
- WvTicketURL2: 文字列
- DASH(Widevine)コンテンツライセンスコントローラーURL
DASH(Widevine)コンテンツを再生する場合において利用します。
# ストリーミング再生
環境変数の以下のパラメータにより、ストリーミング再生の動作を変更できます。
- UseSslMp4Streaming: 真偽値
- MP4ストリーミング再生時、HTTPSプロトコルを使用するか指定します。trueの場合、HTTPSプロトコルを使用します。
- UseSslHlsStreaming: 真偽値
- HLSストリーミング再生時、HTTPSプロトコルを使用するか指定します。trueの場合、HTTPSプロトコルを使用します。
- UseSslDashStreaming: 真偽値
- DASHストリーミング再生時、HTTPSプロトコルを使用するか指定します。trueの場合、HTTPSプロトコルを使用します。
# 広告再生の制御
環境変数の以下のパラメータにより、広告再生の動作を変更できます。
- AllowResetMidRollStatus: 真偽値
- true： 広告再生ポジションを通過する度にリニア広告を再生します。
false： 広告は1度のみ再生します。
# プレイヤーUIの色の変更
プレイヤー上のアイテムの色を変更するにはapplication.json内の以下のフィールドを変更してください。
- PlayerTitleFontColor: 文字列
- タイトルの文字色
16進数6ケタRGB（0xで始まるString）で指定してください。 - PlayerSeekBarColorMinimum: 文字列
- シークバーの色（つまみ部分より左の部分の色）
16進数6ケタRGB（0xで始まるString）で指定してください。 - PlayerSeekBarColorMaximum: 文字列
- シークバーの色（つまみ部分より右の部分の色）
16進数6ケタRGB（0xで始まるString）で指定してください。 - PlayerSeekBarColorSecondary: 文字列
- バッファリング表示用のシークバーの色
16進数6ケタRGB（0xで始まるString）で指定してください。
# プレイヤーUI/広告UIの表示
環境変数の以下のパラメータにより、プレイヤーUIおよび広告UIの表示に関する設定ができます。
- IntervalMovieControllerViewInContents: 数値＜ミリ秒＞
- コントローラー（プレイヤー）を表示してから自動で非表示にするまでの時間
0以上の値を指定してください。0を指定した場合はコントローラー（プレイヤー）を表示し続けます。0より大きい値を指定した場合は指定した時間でコントローラー（プレイヤー）が自動で非表示になります。 - IntervalMovieControllerViewInAd: 数値＜ミリ秒＞
- コントローラー（広告）を表示してから自動で非表示にするまでの時間
0以上の値を指定してください。0を指定した場合はコントローラー（広告）を表示し続けます。0より大きい値を指定した場合は指定した時間でコントローラー（広告）が自動で非表示になります。 - AllowHideMovieControllerViewInAd: 真偽値
- ユーザー操作によるコントローラー（広告）非表示の可否
true： コントローラー（広告）の非表示を許可します。
false： コントローラー（広告）の非表示を許可しません。 - SkipOperationType: 数値
- 進む／戻るの操作タイプ進む／戻る操作は、以下のいずれかを指定できます。
- 1:スワイプのみ
- 2:ボタン操作のみ
- 3:スワイプとボタン操作
- SkipForwardSeconds: 数値＜秒＞
- 進む／戻るの進む秒数
進む操作が行われた場合に、指定の秒数進みます。0以上999以下を指定してください。0を指定した場合は、進む操作が無効になります。 - SkipBackwardSeconds: 数値＜秒＞
- 進む／戻るの戻る秒数
戻る操作が行われた場合に、指定の秒数戻ります。0以上999以下を指定してください。0を指定した場合は、戻る操作が無効になります。
# 外部出力
環境変数の以下のパラメータにより、プレイヤーが再生中の動画を外部出力機器上に表示できます。また、iOS11から導入されたScreenRecordingによる録画ができます。なお、これらのパラメータを変更し外部出力を許可する場合、外部出力機器で動画の複写ができてしまう恐れがある点に注意してください。
- AllowScreenMirroring: 真偽値
- HDMIケーブルで接続された機器への出力、QuickTime Playerによるムービー収録、およびScreenRecordingによる録画を許可するか決定します。
true： 許可します。
false： 許可しません（外部出力またはScreenRecordingを検知すると再生を強制的に停止させます）。 - AllowAirPlay: 真偽値
- AirPlay対応機器への出力を許可するか決定します。
true： 出力を許可します。
false： 出力を許可しません（外部出力を検知すると再生を強制的に停止させます）。
# UserAgent
環境変数の以下のパラメータにより、プレイヤーがWeb通信する際のUserAgentを設定できます。
- CustomUserAgentEnabled: 真偽値
- プレイヤーがWeb通信する際、プレイヤー固有のUserAgentを使用するか決定します。
true： プレイヤー固有のUserAgentを使用します。
false： OSが生成するUserAgentを使用します。 - CustomUserAgentAppInfoEnabled: 真偽値
- プレイヤー固有のUserAgentにアプリバージョンを追加するかを決定します。
true： アプリバージョンを追加します。
false：アプリバージョンを追加しません。
# ULIZA Video Analytics (Cloud)連携
環境変数の以下のパラメータにより、ULIZA Video Analytics (Cloud)連携の有効／無効およびビーコンの送信先識別子を設定します。
- EnableVideoAnalytics: 真偽値
- ULIZA Video Analytics (Cloud)連携の有効／無効を設定します。
true： ULIZA Video Analytics (Cloud)連携を有効にします
false： ULIZA Video Analytics (Cloud)連携を無効にします。
（ユーザーガイドの「ULIZA Video Analytics (Cloud)連携」を参照） - VideoAnalyticsTrackingId: 文字列
- ULIZA Video Analytics (Cloud)で使用するビーコンの送信先識別子を設定します。
弊社からお知らせする文字列を設定してください。 - ShowVideoAnalyticsOptoutSetting: 真偽値
- ULIZA Video Analytics (Cloud)連携のトラッキングオプトアウトボタンの表示／非表示を設定します。
true： トラッキングオプトアウトウトボタンを表示します。
false： トラッキングオプトアウトボタンを表示しません。
（ユーザーガイドの「ULIZA Video Analytics (Cloud)連携」を参照）
# 拡大表示
環境変数の以下のパラメータにより、拡大表示を有効にできます。
- AllowEnlargementFunction: 真偽値
- ユーザー操作による拡大表示を許可するか決定します。
true： 拡大表示を許可します。
false： 拡大表示を許可しません。
# 倍速再生
環境変数の以下のパラメータにより、倍速再生の設定ができます。
- EnablePlaybackrate: 真偽値
- 倍速再生の有効／無効を設定します。
true： 倍速再生を有効にします
false： 倍速再生を無効にします。 - PlaybackrateMin: 数値
- 倍速再生で設定できる再生速度の最小値を設定します。
- 0.5以上1.0より小さい値を指定してください。
- PlaybackrateMax: 数値
- 倍速再生で設定できる再生速度の最大値を設定します。
- 1.5よりも大きく2.0以下の値を指定してください。
- PlaybackrateStep: 数値
- 倍速再生の速度変更における刻み値を設定します。
- 0.1単位で指定してください。
# シーク範囲制御
環境変数の以下のパラメータにより、シーク範囲制御の設定ができます。
- PlayerSeekBarColorNonSeekable: 文字列の配列
- シーク無効範囲の背景色
RGBA形式のカラーコード（16進数）です。指定された色を使用し、シークバーの背景に斜線を表示します。複数指定されている場合は、先頭2色以外を無視します。
# バックグラウンド再生
環境変数の以下のパラメータにより、バックグラウンド再生の許可／不許可を設定します。
- EnableBackgroundPlayback: 真偽値
- バックグラウンド再生の許可／不許可を設定します。
true： バックグラウンド再生を許可します。
false： バックグラウンド再生を許可しません。
（ユーザーガイドの「バックグラウンド再生」を参照）
# 初回動画再生通知
環境変数の以下のパラメータにより、初回動画再生通知のkeyを設定します。
- FirstActionQueryKey: 文字列
- 初回動画再生通知で使用するクエリ文字列のkeyを設定します。
使用可能な文字列は、半角英数字です。初回動画再生通知を無効化する場合は空文字を設定してください。
（ユーザーガイドの「初回動画再生通知」を参照）
# その他の環境変数
環境変数設定ファイル（application.json）に含まれる環境変数のうち、本書で説明を記載していない環境変数はプレイヤーが内部の処理のために必要とする環境変数です。値を変更せず、プレイヤー提供時の値を使用してください。値を変更する場合はサポート対象外です。
# 環境変数の上書きについて
上記で説明した環境変数のうち、以下に示す環境変数は「プレイヤー環境変数URL」にアクセスし取得した環境変数ファイルに該当する環境変数が含まれている場合、その値で上書きします。
- ビーコン送信URL
- DASH(Widevine)コンテンツライセンス要求URL
- DASH(Widevine)コンテンツライセンスコントローラーURL
- ULIZA Video Analytics設定XML URL
環境変数の上書きの例と注意点については環境変数の上書きについてを参照してください。
# プレイヤーUIの変更
# UI概要
以下にプレイヤーのカスタマイズ可能なUIを説明します。
- 戻る（閉じる）ボタン
- ボタンのアイコンを変更できます。
- タイトル
- 文字色を変更できます。
プレイヤーUIの色の変更を参照してください。 - 戻るボタン
- ボタンの秒数を変更できます。
- 再生ボタン（画面中央）
- 一時停止中に表示するボタンのアイコンを変更できます。
- 一時停止ボタン
- 再生中に表示するボタンのアイコンを変更できます。
- リプレイボタン
- 終端まで再生した際に表示するボタンのアイコンを変更できます。（インライン再生の場合のみ適用します）
- 進むボタン
- ボタンの秒数を変更できます。
- 縦持ち通常表示ボタン
- 横持ち拡大表示時に表示するボタンのアイコンを変更できます。（インライン再生の場合のみ適用します）
- 横持ち拡大表示ボタン
- 縦持ち通常表示時に表示するボタンのアイコンを変更できます。（インライン再生の場合のみ適用します）
- シークバー
- スライダー上のつまみ部分の画像、スライダーの色（つまみ部分より左の部分の色、つまみ部分より右の部分の色）を変更できます。また、バッファリングを示すスライダーについても色を変更できます。
# 各ボタンの変更
ボタンを変更するには、それぞれのAsset名で画像を組み込んでください。
# 戻る（閉じる）ボタンの変更
戻るボタンのAsset名は「ic_clear_white_36pt」です。
| 画面スケール | 画像サイズ（px） |
|---|---|
| Universal@2x | 72x72 |
| Universal@3x | 108x108 |
# 再生ボタンの変更
再生ボタンのAsset名は「ic_play_arrow_48pt」です。
| 画面スケール | 画像サイズ（px） |
|---|---|
| Universal@2x | 72x72 |
| Universal@3x | 108x108 |
# 一時停止ボタンの変更
一時停止ボタンのAsset名は「ic_pause_48pt」です
| 画面スケール | 画像サイズ（px） |
|---|---|
| Universal@2x | 96x96 |
| Universal@3x | 144x144 |
# リプレイボタンの変更
リプレイボタンのAsset名は「ic_replay_white_48pt」です。
| 画面スケール | 画像サイズ（px） |
|---|---|
| Universal@2x | 96x96 |
| Universal@3x | 144x144 |
# 縦持ち通常表示ボタンの変更
縦持ち通常表示ボタンのAsset名は「ic_fullscreen_exit」です。
| 画面スケール | 画像サイズ（px） |
|---|---|
| Universal@2x | 48x48 |
| Universal@3x | 72x72 |
# 横持ち拡大表示ボタンの変更
横持ち拡大表示ボタンのAsset名は「ic_fullscreen」です。
| 画面スケール | 画像サイズ（px） |
|---|---|
| Universal@2x | 48x48 |
| Universal@3x | 72x72 |
# シークバーのつまみ画像の変更
シークバーのつまみ画像のAsset名は「slider-thumb」です。
| 画面スケール | 画像サイズ（px） |
|---|---|
| Universal@2x | 38x38 |
| Universal@3x | 57x57 |
# オーディオカードの変更
プレイヤー（iOS）は動画再生中、オーディオカードを表示します。（オーディオカードに関しては、ユーザーガイドの「オーディオカード」を参照）
# オーディオカード概要
以下にオーディオカードのカスタマイズ可能なUIを説明します。
- オーディオカード用サムネイル
- オーディオカードに表示するサムネイル画像を変更します。
画像の指定がない場合はホーム画面用アイコンを表示します。
# オーディオカード用サムネイルの変更
オーディオカード用サムネイルのAsset名は「bg_controller_thumb」です。
| 画面スケール | 画像サイズ（px） |
|---|---|
| Universal@2x | 1024x1024 |
| Universal@3x | 1536x1536 |
← 組み込み方法（Android） 起動方法 →