為您的 Android 應用程式新增進階功能

廣告插播

Android Sender SDK 支援特定媒體串流中的廣告插播和隨播廣告。

如要進一步瞭解廣告插播的運作方式,請參閱網路接收器廣告插播總覽

雖然可以在傳送端和接收器上指定廣告插播,但還是建議您在網路接收器Android TV 接收器上指定廣告插播時間點,以便在不同平台間維持一致的行為。

在 Android 上,使用 AdBreakClipInfoAdBreakInfo 在載入指令中指定廣告插播時間點:

Kotlin
val breakClip1: AdBreakClipInfo =
    AdBreakClipInfo.Builder("bc0")
        .setTitle("Clip title")
        .setPosterUrl("https://www.some.url")
        .setDuration(60000)
        .setWhenSkippableInMs(5000)  // Set this field so that the ad is skippable
        .build()

val breakClip2: AdBreakClipInfo = …
val breakClip3: AdBreakClipInfo = …

val break1: AdBreakClipInfo =
    AdBreakInfo.Builder(/* playbackPositionInMs= */ 10000)
        .setId("b0")
        .setBreakClipIds({"bc0","bc1","bc2"})
        …
        .build()

val mediaInfo: MediaInfo = MediaInfo.Builder()
    …
    .setAdBreaks({break1})
    .setAdBreakClips({breakClip1, breakClip2, breakClip3})
    .build()

val mediaLoadRequestData: MediaLoadRequestData = MediaInfo.Builder()
    …
    .setMediaInfo(mediaInfo)
    .build()

remoteMediaClient.load(mediaLoadRequestData)
Java
AdBreakClipInfo breakClip1 =
    new AdBreakClipInfo.Builder("bc0")
        .setTitle("Clip title")
        .setPosterUrl("https://www.some.url")
        .setDuration(60000)
        .setWhenSkippableInMs(5000)  // Set this field so that the ad is skippable
        .build();

AdBreakClipInfo breakClip2 = …
AdBreakClipInfo breakClip3 = …

AdBreakInfo break1 =
    new AdBreakInfo.Builder(/* playbackPositionInMs= */ 10000)
        .setId("b0")
        .setBreakClipIds({"bc0","bc1","bc2"})
        …
        .build();

MediaInfo mediaInfo = new MediaInfo.Builder()
    …
    .setAdBreaks({break1})
    .setAdBreakClips({breakClip1, breakClip2, breakClip3})
    .build();

MediaLoadRequestData mediaLoadRequestData = new MediaInfo.Builder()
    …
    .setMediaInfo(mediaInfo)
    .build();

remoteMediaClient.load(mediaLoadRequestData);

新增自訂動作

傳送者應用程式可以擴充 MediaIntentReceiver 來處理自訂動作或覆寫其行為。如果您已實作自己的 MediaIntentReceiver,請將其新增至資訊清單,並在 CastMediaOptions 中設定其名稱。本例提供的自訂動作會覆寫遠端媒體播放、按下媒體按鈕和其他類型的動作。

// In AndroidManifest.xml
<receiver android:name="com.example.MyMediaIntentReceiver" />
Kotlin
// In your OptionsProvider
var mediaOptions = CastMediaOptions.Builder()
    .setMediaIntentReceiverClassName(MyMediaIntentReceiver::class.java.name)
    .build()

// Implementation of MyMediaIntentReceiver
internal class MyMediaIntentReceiver : MediaIntentReceiver() {
    override fun onReceiveActionTogglePlayback(currentSession: Session) {
    }

    override fun onReceiveActionMediaButton(currentSession: Session, intent: Intent) {
    }

    override fun onReceiveOtherAction(context: Context?, action: String, intent: Intent) {
    }
}
Java
// In your OptionsProvider
CastMediaOptions mediaOptions = new CastMediaOptions.Builder()
        .setMediaIntentReceiverClassName(MyMediaIntentReceiver.class.getName())
        .build();

// Implementation of MyMediaIntentReceiver
class MyMediaIntentReceiver extends MediaIntentReceiver {
    @Override
    protected void onReceiveActionTogglePlayback(Session currentSession) {
    }

    @Override
    protected void onReceiveActionMediaButton(Session currentSession, Intent intent) {
    }

    @Override
    protected void onReceiveOtherAction(Context context, String action, Intent intent) {
    }
}

新增自訂管道

為了讓傳送端應用程式與接收端應用程式通訊,您的應用程式需要建立自訂管道。傳送者可以利用自訂管道,將字串訊息傳送給接收器。每個自訂管道都是由不重複的命名空間定義,而且開頭須為 urn:x-cast:,例如 urn:x-cast:com.example.custom。可以有多個自訂管道,且每個管道都有不重複的命名空間。接收器應用程式也可以使用相同命名空間來收發訊息

自訂管道是透過 Cast.MessageReceivedCallback 介面實作:

Kotlin
class HelloWorldChannel : MessageReceivedCallback {
    val namespace: String
        get() = "urn:x-cast:com.example.custom"

    override fun onMessageReceived(castDevice: CastDevice, namespace: String, message: String) {
        Log.d(TAG, "onMessageReceived: $message")
    }
}
Java
class HelloWorldChannel implements Cast.MessageReceivedCallback {
    public String getNamespace() {
        return "urn:x-cast:com.example.custom";
    }
    @Override
    public void onMessageReceived(CastDevice castDevice, String namespace, String message) {
        Log.d(TAG, "onMessageReceived: " + message);
    }
}

傳送者應用程式連線至接收器應用程式後,即可使用 setMessageReceivedCallbacks 方法建立自訂管道:

Kotlin
try {
    mCastSession.setMessageReceivedCallbacks(
        mHelloWorldChannel.namespace,
        mHelloWorldChannel)
} catch (e: IOException) {
    Log.e(TAG, "Exception while creating channel", e)
}
Java
try {
    mCastSession.setMessageReceivedCallbacks(
            mHelloWorldChannel.getNamespace(),
            mHelloWorldChannel);
} catch (IOException e) {
    Log.e(TAG, "Exception while creating channel", e);
}

建立自訂管道後,傳送者就能使用 sendMessage 方法,透過該管道將字串訊息傳送給接收器:

Kotlin
private fun sendMessage(message: String) {
    if (mHelloWorldChannel != null) {
        try {
            mCastSession.sendMessage(mHelloWorldChannel.namespace, message)
                .setResultCallback { status ->
                    if (!status.isSuccess) {
                        Log.e(TAG, "Sending message failed")
                    }
                }
        } catch (e: Exception) {
            Log.e(TAG, "Exception while sending message", e)
        }
    }
}
Java
private void sendMessage(String message) {
    if (mHelloWorldChannel != null) {
        try {
            mCastSession.sendMessage(mHelloWorldChannel.getNamespace(), message)
                .setResultCallback( status -> {
                    if (!status.isSuccess()) {
                        Log.e(TAG, "Sending message failed");
                    }
                });
        } catch (Exception e) {
            Log.e(TAG, "Exception while sending message", e);
        }
    }
}

支援自動播放功能

請參閱「Autoplay & Queueing API」一節。

覆寫使用者體驗小工具的圖片選項

架構的各種元件 (包括 Cast 對話方塊、小型控制器和 UIMediaController,如有設定) 會顯示目前投放媒體的圖片。圖片圖片的網址通常包含在媒體的 MediaMetadata 中,但傳送者應用程式可能會提供網址的替代來源。

ImagePicker 類別會根據圖片的使用方式 (例如通知縮圖或全螢幕背景),定義從 MediaMetadata 的圖片清單中選取適當圖片的方法。預設的 ImagePicker 實作一律會選擇第一張圖片,如果 MediaMetadata 中沒有圖片,則傳回空值。應用程式可將 ImagePicker 設為子類別,並覆寫 onPickImage(MediaMetadata, ImageHints) 方法以提供替代實作項目,然後使用 CastMediaOptions.BuildersetImagePicker 方法選取該子類別。ImageHints 會為 ImagePicker 提供提示,說明要在 UI 中顯示的圖片類型和大小。

自訂 Cast 對話方塊

管理工作階段生命週期

SessionManager 是管理工作階段生命週期的集中式平台。SessionManager 會監聽 Android MediaRouter 路線選取狀態變更,以開始、繼續和結束工作階段。選取路徑後,SessionManager 會建立 Session 物件,並嘗試開始或繼續。如果未選取路徑,SessionManager 會結束目前的工作階段。

因此,為確保 SessionManager 妥善管理工作階段生命週期,請務必確保:

視建立「投放」對話方塊的方式而定,可能需要完成其他動作:

零裝置狀態

如果您建立自訂 Cast 對話方塊,自訂 MediaRouteChooserDialog 應可正確處理找不到裝置的情況。當應用程式仍在嘗試尋找裝置,以及探索嘗試已失效時,對話方塊應會顯示指標,讓使用者清楚知道。

如果您使用的是預設的 MediaRouteChooserDialog,則系統已處理零裝置狀態。

後續步驟

這就說明瞭可新增至 Android 發送端應用程式的功能。您現在可以為其他平台 (iOS網頁版) 建構傳送者應用程式,或是建構網路接收器應用程式