Roku 向け IMA DAI SDK

1. 1. ima
   2. ima.AdBreakInfo
   3. ima.AdEvent
   4. ima.AdInfo
   5. ima.Companion
   6. ima.CuePoint
   7. ima.Error
   8. ima.ErrorEvent
   9. ima.Player
   10. ima.StreamFormat
   11. ima.StreamInfo
   12. ima.StreamManager
   13. ima.StreamRequest
   14. ima.StreamType
   15. ima.WrapperInfo

クラス ima

メソッド

disableLogging、getStreamManager、initSdk、requestStream

IMA SDK を制御するグローバル関数。

disableLogging()

SDK のロギングを無効にします。ロギングはデフォルトでオンになります。

getStreamManager()

ストリーム マネージャーが利用可能な場合は、ストリーム マネージャーを返します。ストリーム マネージャーがまだ利用できない場合は、Invalid が返されます。ストリーム マネージャーの作成中にエラーが発生した場合は、エラー オブジェクトが返されます。

object を返します。ストリーム マネージャーまたはエラー オブジェクト。

initSdk(settings)

SDK を初期化します。

パラメータ	型	説明
settings	object	オプションの IMA 設定オブジェクト。

requestStream(streamRequest)

非同期ストリーミング リクエストを開始します。このメソッドを呼び出すと、コントロールはすぐにプレーヤーに戻ります。

object を返します。エラー、またはエラーがなければ無効です

パラメータ	型	説明
streamRequest	object

トップへ戻る

クラス ima.AdBreakInfo

フィールド

adPosition、duration、podIndex、timeOffset、totalAds

メソッド

createAdBreakInfo

ミッドロール挿入点に関する情報が含まれます。SDK からイベント コールバックに渡されます。

プロパティ

名前	型	説明
adPosition		広告ブレーク内の広告のインデックス。スタンドアロン広告の場合、インデックスは 1 です。
duration		ミッドロール挿入点の最大時間（秒）。不明な場合は -1 です。
podIndex		ライブ配信の場合は、ブレーク ID を Pod インデックスとして返します。プレロールの場合は 0 を返します。ライブ配信にはポストロールはありません。デフォルトは -2 です。ビデオ オンデマンド（VOD）の場合、連続配信広告のインデックスを返します。プレロール ポッドの場合は 0 を返します。ミッドロールの場合は、1、2、...、n を返します。ポストロール ポッドの場合は、n+1...n+x を返します。この広告が連続配信広告の一部でない場合、またはこの連続配信広告が再生リストの一部でない場合、デフォルトは 0 です。
timeOffset		コンテンツ内の連続配信広告の位置（秒単位）。プレロールは 0 を返します。ポストロールは -1 を返します。ミッドロールは、Pod のスケジュールされた時間を返します。
totalAds		このミッドロール挿入点に含まれる広告の総数。スタンドアロン広告の場合、値は 1 です。

createAdBreakInfo()

ima.AdBreakInfo を返します。

トップへ戻る

クラス ima.AdEvent

フィールド

AD_PERIOD_ENDED、 AD_PERIOD_STARTED、 COMPLETE、 ERROR、 FIRST_QUARTILE、 ICON_FALLBACK_IMAGE_CLOSED、 ICON_FALLBACK_IMAGE_SHOWN、 MIDPOINT、 PROGRESS、 SKIPPABLE_STATE_CHANGED、 SKIPPED、 START、 THIRD_QUARTILE

アド マネージャーによって発生するイベント。

プロパティ

名前	型	説明
AD_PERIOD_ENDED		ストリームが広告またはスレートからコンテンツに切り替わるたびに発生します。これは、広告が 2 回目に再生された場合や、広告にシークした場合でも呼び出されます。
AD_PERIOD_STARTED		ストリームがコンテンツから広告またはスレートに変換されるたびにトリガーされます。これは、広告が 2 回目に再生された場合や、広告にシークした場合でも呼び出されます。
COMPLETE		広告の再生が終了すると呼び出されます。
ERROR		エラーが発生すると呼び出されます。
FIRST_QUARTILE		広告の再生ヘッドが最初の四分位を超えると呼び出されます。
ICON_FALLBACK_IMAGE_CLOSED		ユーザーがアイコンの代替画像ダイアログを閉じると発行されます。
ICON_FALLBACK_IMAGE_SHOWN		アイコンの代替画像が表示されたときに発生します。
MIDPOINT		広告の再生ヘッドが中間点を通過すると呼び出されます。
PROGRESS		広告の進行状況が更新されると呼び出されます。
SKIPPABLE_STATE_CHANGED		広告のスキップ可能状態が変更されたときに呼び出されます。
SKIPPED		広告がスキップされると呼び出されます。
START		広告の再生が開始されると呼び出されます。
THIRD_QUARTILE		広告の再生ヘッドが第 3 四分位を超えると呼び出されます。

トップへ戻る

クラス ima.AdInfo

フィールド

adBreakInfo、 adDescription、 adId、 adSystem、 adTitle、 advertiserName、 companions, creativeAdId, creativeId, currentTime, dealId, duration, skipOffset, universalAdIDRegistry, universalAdIDValue, wrappers

メソッド

createAdInfo

広告に関する情報が含まれます。SDK からイベント コールバックに渡されます。

プロパティ

名前	型	説明
adBreakInfo		この広告が含まれるブレーク全体に関する情報。
adDescription		広告の説明。
adId		広告の ID。不明な場合は空の文字列。
adSystem		クリエイティブを提供する広告システム。
adTitle		広告のタイトル。
advertiserName		配信元が定義した広告主名。
companions		VAST レスポンスで指定されたコンパニオン広告。
creativeAdId		広告の ISCI（業界標準の商業識別子）コード。VAST レスポンスで選択されたクリエイティブの Ad-ID です。
creativeId		広告に選択したクリエイティブの ID。
currentTime		広告内の現在の時刻（秒単位）。不明な場合は -1 です。
dealId		現在の広告のラッパーチェーンに存在する最初の取引 ID（上から順に）を返します。
duration		この単一の広告の再生時間（秒単位）。不明な場合は -1 です。
skipOffset		広告がスキップ可能になるまでの時間（不明な場合は -1）。
universalAdIDRegistry		選択したクリエイティブのユニバーサル広告 ID がカタログ化されているレジストリ ウェブサイトの URL を識別するために使用される文字列。
universalAdIDValue		広告に選択したクリエイティブのユニバーサル広告 ID。
wrappers		この広告のラッパー情報を含む ima.WrapperInfo の配列。順序は外側のラッパーから内側になります。

createAdInfo()

ima.AdInfo を返します。

トップへ戻る

クラス ima.Companion

フィールド

apiFramework、 creativeType、 height、 trackingEvents、 url、 width

メソッド

createCompanion

広告のコンパニオンに関する情報が含まれます。

プロパティ

名前	型	説明
apiFramework		この広告の実行に必要な API。利用できない場合は「無効」です。
creativeType		クリエイティブ タイプ（通常は MIME タイプ）を表します。
height		コンパニオンの高さ（ピクセル単位）。利用できない場合は 0 です。
trackingEvents		トラッキング イベントのマップ。キーはイベントで、値はそのイベントで ping する URL のリストです。
url		このコンパニオンの静的リソースの URL。
width		コンパニオンの幅（ピクセル単位）。利用できない場合は 0 です。

createCompanion()

ima.Companion を返します。

トップへ戻る

クラス ima.CuePoint

フィールド

end、hasPlayed、start

メソッド

createCuePoint

キューポイントに関する情報が含まれます。

プロパティ

名前	型	説明
end		キューポイントの終了時間（秒単位）。これはミッドロール挿入点に対応しています。
hasPlayed		キューポイントがすでに再生されていることを示すブール値。
start		キューポイントの開始時間（秒単位）。これはミッドロール挿入点に対応しています。

createCuePoint()

ima.CuePoint を返します。

トップへ戻る

クラス ima.Error

フィールド

id、info、type

メソッド

createError

エラーが発生した場合にエラーハンドラに渡されるオブジェクト。

プロパティ

名前	型	説明
id		エラーの ID。エラーコードの一覧については、ErrorEvent 定数をご覧ください。
info		エラーに関する追加情報。
type		このオブジェクトのタイプを示すため、常に error に設定します。

createError()

ima.Error を返します。

トップへ戻る

クラス ima.ErrorEvent

フィールド

BAD_STREAM_REQUEST、 COULD_NOT_LOAD_STREAM、 ERROR、 INVALID_RESPONSE、 STREAM_API_KEY_NOT_VALID

SDK が返す可能性のあるすべてのエラー。

プロパティ

名前	型	説明
BAD_STREAM_REQUEST		ストリーム リクエストが正しく入力されていません。
COULD_NOT_LOAD_STREAM		ライブ配信を読み込めませんでした。
ERROR		不明なエラーです。
INVALID_RESPONSE		サーバー レスポンスが有効ではありませんでした。
STREAM_API_KEY_NOT_VALID		指定された API キーがサーバーで受け入れられませんでした。

トップへ戻る

クラス ima.Player

メソッド

adBreakEnded、adBreakStarted、allVideoComplete、createPlayer、loadUrl

adBreakEnded(adBreakInfo)

省略可。ミッドロール挿入点が終了したときに呼び出されます。

パラメータ	型	説明
adBreakInfo	ima.AdBreakInfo	ミッドロール挿入点に関する情報が含まれます。

adBreakStarted(adBreakInfo)

省略可。ミッドロール挿入点が開始されたときに呼び出されます。

パラメータ	型	説明
adBreakInfo	ima.AdBreakInfo	ミッドロール挿入点に関する情報が含まれます。

allVideoComplete()

省略可。すべての動画が完了したときに呼び出されます。

createPlayer()

空の IMA Player オブジェクトを作成します。広告を再生するには、loadUrl 関数を実装する必要があります。その他の関数は省略可能です。

ima.Player を返します。

loadUrl(streamInfo)

プレーヤーが URL の再生を開始するときに呼び出されます。ストリームを読み込むには、このメソッドを実装する必要があります。

パラメータ	型	説明
streamInfo	ima.StreamInfo	コンテンツの再生に必要な情報が含まれています。

トップへ戻る

クラス ima.StreamFormat

フィールド

DASH、HLS

ストリームの形式を定義します。

プロパティ

名前	型	説明
DASH
HLS

トップへ戻る

クラス ima.StreamInfo

フィールド

format、manifest、streamId、streamType、subtitles

メソッド

createStreamInfo

ストリームに関する情報。SDK からプレーヤーに渡されます。

プロパティ

名前	型	説明
format		動画の形式: hls または dash。ima.StreamFormat で定義されています。
manifest		ストリームの URL。
streamId		ストリームの一意の ID。
streamType		動画の種類: ライブまたはオンデマンド。ima.StreamType で定義されています。
subtitles		字幕（利用可能な場合）。そうでない場合は無効です。

createStreamInfo()

ima.StreamInfo を返します。

トップへ戻る

クラス ima.StreamManager

メソッド

addEventListener、createStreamManager、enableInteractiveAds、getContentTime、getCuePoints、getPreviousCuePoint、getStreamTime、loadThirdPartyStream、onMessage、replaceAdTagParameters、start

ストリームの再生を管理するオブジェクト。

addEventListener(event, callback)

指定したイベントのリスナーを追加します。サポートされているイベントについては、AdEvents 定数をご覧ください。

パラメータ	型	説明
event	string
callback	function

createStreamManager(streamRequest, streamInitResponse)

ima.StreamManager を返します。

パラメータ	型	説明
streamRequest	ima.StreamRequest
streamInitResponse	ima.StreamInitResponse

enableInteractiveAds()

サポート対象外。代わりに、コンパニオン広告から RAF にデータを直接渡します。これは無効になりました。

getContentTime(streamTime)

VOD ストリームの時間をミリ秒単位で取得します。これは、広告なしのコンテンツの時間を表します。詳しくは、よくある質問をご覧ください。現在のストリームの時間のコンテンツ時間を取得するには、-1 を渡します。

Integer を返します。指定されたストリーム時間に対応するコンテンツ時間。

パラメータ	型	説明
streamTime	Integer	ライブ配信の時間。

getCuePoints()

すべてのミッドロール挿入点に対応するすべてのキューポイントを返します。これは、すべてのミッドロール挿入が事前にわかっているビデオ オンデマンド コンテンツでのみ有効です。すべての時間は、ストリーミング時間を秒単位で表します。Cloud Stitching API ストリームの場合、各 ima.CuePoint の hasPlayed プロパティは常に false です。

Object を返します。すべてのキューポイントを含む配列。

getPreviousCuePoint(time)

この時間より前のキューポイントを返します。キューポイントは広告ブレークを示します。すべての時間は、ストリーミング時間を秒単位で表します。

ima.CuePoint を返します。start、end、hasPlayed を含むオブジェクトです。キューポイントが使用できない場合は無効を返します。

パラメータ	型	説明
time	Float	検索時間。-1 は現在の時刻を示し、他のすべてのストリームに対して Invalid を返します。

getStreamTime(contentTime)

VOD のコンテンツ時間からストリームの時間（ミリ秒単位）を取得します。詳しくは、よくある質問をご覧ください。

Integer を返します。指定されたコンテンツ時間に対応するストリーム時間。

パラメータ	型	説明
contentTime	Integer	コンテンツの時間。

loadThirdPartyStream(streamManifest, streamSubtitle)

広告メタデータを読み込み、指定された streamManifestUrl データと streamSubtitle データを使用して loadUrl 関数を呼び出します。この関数は、ストリーム リクエストのタイプが ima.StreamType.POD_VOD の場合にのみ機能します。

パラメータ	型	説明
streamManifest	string	広告が挿入されたストリーム マニフェストの URL。
streamSubtitle	ifArray>|Invalid	ストリームに関連付けられた字幕。関連付けられていない場合は Invalid。

onMessage(msg)

Video オブジェクトから送信されるすべてのメッセージを処理します。roMessagePort で受信したメッセージごとに呼び出す必要があります。

パラメータ	型	説明
msg	object	roVideo ポートからのメッセージ。

replaceAdTagParameters(adTagParameters)

今後のライブ ストリームの広告リクエストに使用されるすべての広告タグ パラメータを置き換えます。この呼び出しは VOD ストリームでは無効です。

パラメータ	型	説明
adTagParameters	string	新しい広告タグのパラメータ。

start()

ストリームの再生を開始します。

トップへ戻る

クラス ima.StreamRequest

フィールド

adTagParameters、adUiNode、apiKey、assetKey、authToken、contentSourceId、customAssetKey、format、networkCode、player、ppid、streamActivityMonitorId、videoId、videoObject、videoStitcherSessionOptions

メソッド

createLiveStreamRequest、createPodLiveStreamRequest、createPodVodStreamRequest、createStreamRequest、createVideoStitcherLiveStreamRequest、createVideoStitcherVodStreamRequest、createVideoStitcherVodStreamRequestWithVodConfig、createVodStreamRequest

ストリーム リクエストのプロパティの指定に使用されます。

プロパティ

名前	型	説明
adTagParameters		省略可。ストリーム リクエストで、限定された広告タグ パラメータをオーバーライドできます。詳しくは、ストリームにターゲティング パラメータを指定するをご覧ください。ストリーム バリアントの優先度には、dai-ot パラメータと dai-ov パラメータを使用することもできます。詳細については、ストリームのバリエーション パラメータをオーバーライドするをご覧ください。
adUiNode		広告 UI が表示されるシーングラフ ノード。IMA は、広告中に [広告の表示について] ボタンや [スキップ] ボタンなどの要素をこの要素に配置します。要素は動画要素全体をオーバーレイする必要があります。
apiKey		省略可。これらのキーは、ストリーム リクエストの認証に使用できます。DAI 認証キーは、DFP UI で設定する必要があります。
assetKey		ライブ配信には必須です。これは、再生するストリームを決定するために使用されます。ライブ ストリーム リクエストのアセットキーは、DFP の管理画面で確認できる ID です。
authToken		ストリーム リクエストの認可トークン。より厳格なコンテンツ認可のために、API キーの代わりに使用されます。パブリッシャーは、このトークンに基づいて個々のコンテンツ ストリームの承認を制御できます。
contentSourceId		オンデマンド ストリームに必須です。cmsid は、DFP UI の DFP 動画コンテンツ ソースから取得します。
customAssetKey		カスタム アセットキーは、再生するストリームを決定するために使用されます。Pod サービング ストリーム リクエストにはカスタム アセットキーが必要です。
format		ストリームの形式。デフォルトは ima.StreamFormat.HLS です。
networkCode		ストリーミング リクエストを行うパブリッシャーのネットワーク コード。ネットワーク コードは、createPodLiveStreamRequest または createPodVodStreamRequest で行われた連続広告配信ストリーム リクエストに必要です。これらのコードは、createVideoStitcherLiveStreamRequest、createVideoStitcherVodStreamRequest、または createVideoStitcherVodStreamRequestWithVodConfig で行われた Cloud ステッチング ストリーム リクエストにも必要です。これらのコードは省略可能ですが、createLiveStreamRequest または createVodStreamRequest で行うフルサービス ストリーム リクエストには推奨されます。ネットワーク コードを追加すると、アド マネージャーの UI で選択した設定（プログラマティック限定広告の有効化など）が適用されます。Pod サービングと Cloud ステッチングの場合、ネットワーク コードを追加すると、ストリームが検出されて再生されます。ネットワーク コードを確認する方法については、こちらの記事をご覧ください。
player		プレーヤー インターフェースの実装。
ppid		非推奨です。adTagParameters を使用します。省略可。DFP オーディエンスのパブリッシャー指定の識別子。
streamActivityMonitorId		ストリーム アクティビティ モニターでストリームのデバッグに使用する ID。これは、パブリッシャーがストリーム アクティビティ モニター ツールでストリームログを簡単に見つけられるようにするために使用されます。
videoId		オンデマンド ストリームに必須です。動画コンテンツ ソースの ID。
videoObject		クライアント アプリでの動画再生を担当する動画オブジェクト（Video roSGNode など）。このオブジェクトは、ライブ HLS ID3 イベントのタイミングを適切に設定するために使用されるさまざまなデータについてポーリングされます。
videoStitcherSessionOptions		セッション オプションは、VideoStitcher の streamRequests に動画ステッチャー固有のパラメータを設定するために使用されます。

createLiveStreamRequest(assetKey, apiKey, networkCode)

ライブ StreamRequest の必須プロパティを初期化します。この API を使用すると、他の StreamType 固有のプロパティは無視されます。必須パラメータが空の文字列の場合、エラー ロギングが発生し、API は汎用の StreamRequest を返します。プロパティは無視されません。

ima.StreamRequest を返します。必要なライブ プロパティを含む ima.StreamRequest オブジェクト。

パラメータ	型	説明
assetKey	string
apiKey	string	返された ima.StreamRequest の ima.StreamRequest.apiKey プロパティに割り当てられるパラメータ。API キーが存在しない場合は、空の文字列を渡します。
networkCode	string	ストリーミング リクエストを行うパブリッシャーのネットワーク コード。ネットワーク コードを含めるかどうかは任意ですが、含めることをおすすめします。

createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)

Pod Live ima.StreamRequest の必須プロパティを初期化します。この API を使用すると、他の ima.StreamType 固有のプロパティは無視されます。必須パラメータが空の文字列の場合、エラー ロギングが発生し、API は汎用の StreamRequest を返します。プロパティは無視されません。

StreamRequest を返します。必須の PodLive プロパティを含む ima.StreamRequest オブジェクト。

パラメータ	型	説明
customAssetKey	string
networkCode	string
apiKey	string	返された ima.StreamRequest の ima.StreamRequest.apiKey プロパティに割り当てられるオプション パラメータ。デフォルトは空の文字列です。

createPodVodStreamRequest(networkCode)

サードパーティの動画スティッチャーで DAI Pod サービングを使用するときに、VOD ストリームを登録するために ima.StreamRequest の必須プロパティを初期化します。この関数は、リクエスト タイプを ima.StreamType.POD_VOD に設定し、データが欠落しているすべての必須プロパティを検証します。検証に失敗すると、デバッグ コンソールにエラーが記録されます。

StreamRequest を返します。ima.StreamRequest オブジェクト。必須のプロパティがすべて指定されている場合、リクエスト タイプは ima.StreamType.POD_VOD に設定されます。

パラメータ	型	説明
networkCode	string	Google アド マネージャー ネットワーク コード

createStreamRequest()

ima.StreamRequest を返します。空の ima.StreamRequest オブジェクト。

createVideoStitcherLiveStreamRequest(customAssetKey, networkCode, liveConfigId, region, projectNumber, oAuthToken)

Video Stitcher ライブ StreamRequest の必須プロパティを初期化します。この API を使用すると、他の StreamType 固有のプロパティは無視されます。必須パラメータが空の文字列の場合、エラー ロギングが行われ、API は汎用の StreamRequest を返します。プロパティは無視されません。

ima.StreamRequest を返します。必要な VideoStitcherLive プロパティを持つ ima.StreamRequest オブジェクト。

パラメータ	型	説明
customAssetKey	string
networkCode	string
liveConfigId	string
region	string
projectNumber	string
oAuthToken	string

createVideoStitcherVodStreamRequest(adTagUrl, networkCode, contentSourceUrl, region, projectNumber, oAuthToken)

Video Stitcher VOD StreamRequest の必須プロパティを初期化します。この API を使用すると、他の StreamType 固有のプロパティは無視されます。必須パラメータが空の文字列の場合、エラー ロギングが発生し、API は汎用の StreamRequest を返します。プロパティは無視されません。

ima.StreamRequest を返します。必要な VideoStitcherVod プロパティを含む ima.StreamRequest オブジェクト。

パラメータ	型	説明
adTagUrl	string
networkCode	string
contentSourceUrl	string
region	string
projectNumber	string
oAuthToken	string

createVideoStitcherVodStreamRequestWithVodConfig(vodConfigId, networkCode, region, projectNumber, oAuthToken)

クラウド動画スティッチャーから作成された vodConfigId を使用して、Video Stitcher VOD StreamRequest の必須プロパティを初期化します。この API を使用すると、他の StreamType 固有のプロパティは無視されます。必須パラメータが空の文字列の場合、エラー ロギングが発生し、API は汎用の StreamRequest を返します。プロパティは無視されません。

ima.StreamRequest を返します。必要な VideoStitcherVod プロパティを含む ima.StreamRequest オブジェクト。

パラメータ	型	説明
vodConfigId	string
networkCode	string
region	string
projectNumber	string
oAuthToken	string

createVodStreamRequest(contentSourceId, videoId, apiKey, networkCode)

VOD ima.StreamRequest の必須プロパティを初期化します。この API を使用すると、他の ima.StreamType 固有のプロパティは無視されます。必須パラメータが空の文字列の場合、エラー ロギングが発生し、API は汎用の StreamRequest を返します。プロパティは無視されません。

ima.StreamRequest を返します。必要な VOD プロパティを含む ima.StreamRequest オブジェクト。

パラメータ	型	説明
contentSourceId	string
videoId	string
apiKey	string	返された ima.StreamRequest の ima.StreamRequest.apiKey プロパティに割り当てられるパラメータ。API キーが存在しない場合は、空の文字列を渡します。
networkCode	string	ストリーミング リクエストを行うパブリッシャーのネットワーク コード。ネットワーク コードを含めるかどうかは任意ですが、含めることをおすすめします。

トップへ戻る

クラス ima.StreamType

フィールド

ライブ、VOD

プレーヤーに再生をリクエストするストリームのタイプを定義します。プレロールと VOD は、ストリーミングの最初から再生する必要があります。

プロパティ

名前	型	説明
LIVE		動画が公開されています。
VOD		動画はオンデマンドです。

トップへ戻る

クラス ima.WrapperInfo

フィールド

adId、 adSystem、 creativeAdId、 creativeId、 dealId

メソッド

createWrapperInfo

ラッパーに関する情報が含まれています。

プロパティ

名前	型	説明
adId		広告の ID。不明な場合は空の文字列。
adSystem		広告システムの宣言された名前。不明な場合は空の文字列。
creativeAdId		クリエイティブの広告 ID。不明な場合は空の文字列。
creativeId		クリエイティブの ID。不明な場合は空の文字列。
dealId		取引 ID。不明な場合は空の文字列。

createWrapperInfo()

ima.WrapperInfo を返します。

トップへ戻る