自訂配置 - ApsaraVideo VOD

AliPlayerKit內建了最佳實務配置，大多數情境無需額外設定即可獲得優質體驗。當您需要的播放器能力未通過 AliPlayerKit 的介面直接提供時，可通過以下自訂配置機制，直接調用底層 AliPlayer SDK 的 API 來實現。

配置層級概覽

AliPlayerKit 提供兩個層級的自訂配置入口，滿足不同粒度的需求：

層級	介面	調用時機	典型情境
全域配置	`AliPlayerKit.setOnGlobalInit()`	全域初始化完成後（僅一次）	`AliPlayerGlobalSettings.setOption()`（全域記錄層級）、HTTP/2 多工等全域行為
執行個體配置	`AliPlayerModel.Builder.onPlayerConfig()`	每個播放器執行個體 `setDataSource()` 之後	`aliPlayer.setConfig()`（緩衝、Referer）、`aliPlayer.setOption()` 等執行個體行為

播放器 SDK 本身分為全域配置和執行個體配置兩種類型。AliPlayerKit 已內建最佳實務配置，但對於未直接透出的原生介面，提供了上述兩個回調入口，供開發人員自行擷取播放器執行個體並調用。

全域配置

適用情境

設定全域 Option（如全域記錄層級）。
啟用 HTTP/2 多工。
其他需要在所有播放器執行個體建立前生效的全域行為。

機制說明

通過 AliPlayerKit.setOnGlobalInit() 註冊回調。
回調在 AliPlayerKit.init() 內部全域初始化完成後觸發，僅執行一次。
此時底層 SDK 已就緒，可安全調用全域 API。

使用方式

在 Application.onCreate() 中，調用 AliPlayerKit.init() 之前註冊回調：

public class MyApplication extends Application {

    @Overridepublic void onCreate() {
        super.onCreate();

        // 1. 註冊全域自訂配置回調（在 init 之前調用）
        AliPlayerKit.setOnGlobalInit(() -> {
            // 樣本：啟用 HTTP/2 多工
            AliPlayerFactory.setOption(
                AliPlayerGlobalSettings.ENABLE_H2_MULTIPLEX, 1
            );
            // 樣本：設定全域記錄層級// AliPlayerFactory.setOption(...);
        });

        // 2. 初始化（內部會在初始化完成後觸發上面註冊的回調）
        AliPlayerKit.init(this);
    }
}

注意事項

要點	說明
調用順序	`setOnGlobalInit()` 必須在 `init()` 之前調用，否則回調不會被觸發。
執行次數	全域配置僅執行一次，後續重複調用 `init()` 不會再次觸發。
傳 null 取消	傳入 `null` 可取消登入的回調。

執行個體配置

適用情境

自訂緩衝策略（maxBufferDuration、highBufferDuration等）。
設定 Referer 防盜鏈。
配置 HTTP Header。
設定執行個體級 Option。
其他 AliPlayerKit 未直接透出的播放器介面。

機制說明

通過 AliPlayerModel.Builder.onPlayerConfig() 傳入回調。
在每次 controller.configure(model) 時觸發。
回調在 setDataSource() 之後、prepare() 前執行。
回調參數為 IMediaPlayer 執行個體，可通過此執行個體訪問底層 SDK 的全部配置能力。

重要

已知限制：setDataSource(model) 內部已隱式調用 prepare()，因此 onPlayerConfig 回調實際在 prepare() 之後觸發，而非之前。這意味著依賴"prepare 前生效"的配置項（如部分緩衝參數）在當前實現下可能無法在首次 prepare 時生效。如有此類強依賴，建議關注後續版本更新。

使用方式

在構建 AliPlayerModel 時，通過onPlayerConfig()方法傳入回調：

AliPlayerModel model = new AliPlayerModel.Builder()
        .videoSource(videoSource)
        .onPlayerConfig(player -> {
            // 先擷取底層原生播放器執行個體
            AliPlayer aliPlayer = player.getInternalPlayer();

            // 樣本 1：自訂緩衝策略和 Referer
            PlayerConfig config = aliPlayer.getConfig();
            config.mMaxBufferDuration = 50000;                  // 最大緩衝時間長度 50s
            config.mHighBufferDuration = 3000;                  // 高水位緩衝 3s
            config.mStartBufferDuration = 500;                  // 起播緩衝 500ms
            config.mReferrer = "https://your-domain.com";       // 設定 Referer 防盜鏈
            aliPlayer.setConfig(config);

            // 樣本 2：設定執行個體級 Option
            aliPlayer.setOption(AliPlayer.ALLOW_PRE_RENDER, 1);
        })
        .build();

// 配置並播放
controller.configure(model);

注意事項

要點	說明
觸發頻率	每次調用 `controller.configure(model)` 都會觸發該回調，適合動態配置情境。
執行時機	回調在 `setDataSource()` 之後、`prepare()` 之前執行，是進行自訂配置的最佳時機。
回調參數	`IMediaPlayer` 執行個體，可調用底層 SDK 的所有介面。
傳 null 可選	`onPlayerConfig()` 為可選配置，不設定時不影響正常播放。

配置時序

全域配置時序

Application.onCreate()
    │
    ├── AliPlayerKit.setOnGlobalInit(callback)   ← 註冊回調
    │
    └── AliPlayerKit.init(context)
            │
            ├── GlobalManager.initialize()    ← 底層 SDK 初始化
            │
            └── callback.onGlobalInit()           ← 觸發全域配置回調（僅一次）

執行個體配置時序

controller.configure(model)
    │
    ├── lifecycleStrategy.acquire()               ← 擷取播放器執行個體
    │
    ├── player.setDataSource(model)               ← 配置視頻源（內部已隱式調用 prepare()）
    │
    └── onPlayerConfig.onPlayerConfig(player)     ← 觸發執行個體配置回調（此時已在 prepare() 之後）

完整生命週期

┌──────────────────────────────────────────────────────────────────┐
│                       Application 啟動                           │
│                                                                  │
│  setOnGlobalInit(callback)  ──→  init(context)                  │
│                                      │                           │
│                               GlobalManager                  │
│                                      │                           │
│                               callback.onGlobalInit() ← 全域配置 │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│                      播放器執行個體建立                               │
│                                                                  │
│  AliPlayerModel.Builder()                                        │
│      .videoSource(source)                                        │
│      .onPlayerConfig(callback)  ← 註冊執行個體配置回調                │
│      .build()                                                    │
│                                                                  │
│  controller.configure(model)                                     │
│      │                                                           │
│      ├── setDataSource(model)  ← 內部已隱式調用 prepare()          │
│      └── callback.onPlayerConfig(player)  ← 執行個體配置（prepare 後） │
└──────────────────────────────────────────────────────────────────┘

API參考

核心介面

OnGlobalInitCallback

全域初始化自訂配置回調介面：

@FunctionalInterfacepublic interface OnGlobalInitCallback {
    /**
     * 全域初始化完成後的配置回調。
     */void onGlobalInit();
}

方法	說明
`onGlobalInit()`	全域初始化完成後觸發，僅執行一次

OnPlayerConfigCallback

執行個體級播放器自訂配置回調介面：

@FunctionalInterfacepublic interface OnPlayerConfigCallback {
    /**
     * 播放器自訂配置回調，在 prepare() 前調用。
     *
     * @param player 播放器執行個體，可通過此執行個體訪問底層 SDK 配置能力
     */void onPlayerConfig(@NonNull IMediaPlayer player);
}

方法	說明
`onPlayerConfig(player)`	播放器配置回調，參數為 `IMediaPlayer` 執行個體

註冊方法

類	方法	說明
`AliPlayerKit`	`setOnGlobalInit(@Nullable OnGlobalInitCallback)`	註冊全域配置回調，傳 `null` 可取消
`AliPlayerModel.Builder`	`onPlayerConfig(@Nullable OnPlayerConfigCallback)`	設定執行個體級配置回調

常見問題

全域配置和執行個體配置的執行順序是什嗎？

全域配置（setOnGlobalInit）在應用啟動時執行一次；執行個體配置（onPlayerConfig）在每個播放器執行個體 prepare() 前執行。兩者互不影響。

如果不設定自訂配置會怎樣？

AliPlayerKit 已內建最佳實務配置，不設定任何自訂配置即可正常使用，適合大多數情境。

執行個體配置回調中可以做非同步作業嗎？

不建議。Android 端的回調是同步執行的，回調完成後才會繼續執行 prepare()。如果在回調中執行耗時操作，會阻塞播放器的啟動流程。

可以在執行個體配置中修改視頻源嗎？

不建議。視頻源在回調前已通過 setDataSource() 設定完成，在回調中修改視頻源可能導致不可預期的行為。執行個體配置回調應僅用於設定播放參數（如緩衝策略、Referer 等）。

檔案	說明
`config/OnGlobalInitCallback.java`	全域配置回調介面定義
`config/OnPlayerConfigCallback.java`	執行個體配置回調介面定義
`AliPlayerKit.java`	全域配置註冊入口（`setOnGlobalInit`）
`AliPlayerModel.java`	執行個體配置註冊入口（Builder 的 `onPlayerConfig`）
`AliPlayerController.java`	配置執行邏輯（`configure` 方法中調用回調）

ApsaraVideo VOD：自訂配置

配置層級概覽

全域配置

適用情境

機制說明

使用方式

注意事項

執行個體配置

適用情境

機制說明

使用方式

注意事項

配置時序

全域配置時序

執行個體配置時序

完整生命週期

API參考

核心介面

OnGlobalInitCallback

OnPlayerConfigCallback

註冊方法

相關檔案

常見問題

全域配置和執行個體配置的執行順序是什嗎？

如果不設定自訂配置會怎樣？

執行個體配置回調中可以做非同步作業嗎？

可以在執行個體配置中修改視頻源嗎？