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

廣告插播

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

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

雖然您可以在傳送端和接收端上指定插播，但建議您在網頁接收端和 Android TV 接收端上指定插播，以便在各平台上維持一致的行為。

在 Android 上，請使用 AdBreakClipInfo 和 AdBreakInfo 在載入指令中指定廣告插播：

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);
    }
}

注意： 此程序「不會」使用 setSupportedNamespaces() 方法。

傳送端應用程式連線至接收端應用程式後，您可以使用 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);
        }
    }
}

支援自動播放

請參閱「自動播放與排隊 API」一節。

覆寫 UX 小工具的圖片選項

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

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

自訂投放對話方塊

管理工作階段生命週期

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

因此，為確保 SessionManager 能正確管理工作階段生命週期，您必須確保：

• 在路徑選取器對話方塊中，當使用者選取裝置時呼叫 MediaRouter.selectRoute(MediaRouter.RouteInfo)。
• 在路徑控制器對話方塊中 (在連線狀態或投放狀態中)，當使用者停止投放時呼叫 MediaRouter.unselect(int)。

視您建立投放對話方塊的方式而定，可能需要執行其他動作：

• 如果您使用 MediaRouteChooserDialog 和 MediaRouteControllerDialog 建立投放對話方塊，這些對話方塊會自動更新 MediaRouter 中的路徑選項，因此您不必採取任何行動。
• 如果您使用 CastButtonFactory.setUpMediaRouteButton(Context, Menu, int) 或 CastButtonFactory.setUpMediaRouteButton(Context, MediaRouteButton) 設定投放按鈕，系統會使用 MediaRouteChooserDialog 和 MediaRouteControllerDialog 建立對話方塊，因此您也不需要採取任何行動。
• 在其他情況下，您會建立自訂投放對話方塊，因此需要按照上述指示更新 MediaRouter 中的路徑選取狀態。

零裝置狀態

如果您建立自訂的 Cast 對話方塊，自訂 MediaRouteChooserDialog 應妥善處理找不到任何裝置的情況。對話方塊應提供指標，讓使用者清楚瞭解應用程式何時仍在嘗試尋找裝置，以及何時不再嘗試尋找。

如果您使用預設的 MediaRouteChooserDialog，系統會處理零裝置狀態。

後續步驟

這篇文章介紹了可新增至 Android 傳送端應用程式的功能。您現在可以為其他平台 (iOS 或 網頁) 建構傳送端應用程式，或是建構網頁接收端應用程式。