ApsaraVideo VOD：自訂配置

概念介紹

三層配置體系

AliPlayerKit 的完整配置體系包含三個層級：

┌─────────────────────────────────────────────────────────┐
│              1. 全域配置 (OnGlobalInitBlock)              │
│         應用啟動時執行一次，影響所有播放器執行個體                │
├─────────────────────────────────────────────────────────┤
│              2. 模型配置 (AliPlayerModel)                 │
│         每次 configure: 時通過屬性設定播放參數               │
├─────────────────────────────────────────────────────────┤
│           3. 執行個體配置 (onPlayerConfigBlock)               │
│       每次 configure: 時在 prepare 前回調底層播放器          │
└─────────────────────────────────────────────────────────┘

全域配置（Global Config）

適用情境

• 設定全域 Option（如全域記錄層級）

• 啟用 HTTP/2 多工

• 配置全域 DNS 解析策略

• 其他需要在所有播放器執行個體建立前生效的全域行為

機制說明

• 通過 +[AliPlayerKit setOnGlobalInitBlock:] 註冊回調 Block

• 回調在 +setup 完成內部初始化後觸發，僅執行一次

• 執行後 Block 被置 nil，後續不再觸發

• 此時底層 SDK 已就緒，可安全調用全域 API

使用方式

在 application:didFinishLaunchingWithOptions: 中，調用 +setup 之前註冊回調：

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 1. 註冊全域自訂配置回調（必須在 setup 之前調用）
    [AliPlayerKit setOnGlobalInitBlock:^{
        // 樣本：啟用 HTTP/2 多工
        [AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];

        // 樣本：設定全域記錄層級
        // [AliPlayerFactory setLogLevel:AF_LOG_LEVEL_INFO];
    }];

    // 2. 初始化（內部完成初始化後觸發上面註冊的回調）
    [AliPlayerKit setup];

    return YES;
}

配置時序

application:didFinishLaunchingWithOptions:
    │
    ├── [AliPlayerKit setOnGlobalInitBlock:block]   ← 註冊回調
    │
    └── [AliPlayerKit setup]
            │
            ├── [GlobalManager setup]    ← 底層 SDK 初始化
            │
            ├── sInitialized = YES
            │
            └── block()                  ← 觸發全域配置回調（僅一次）

注意事項

執行個體配置（Player Config）

適用情境

• 自訂緩衝策略（maxBufferDuration、highBufferDuration 等）

• 設定 Referer 防盜鏈

• 配置 HTTP Header

• 設定執行個體級 Option

• 其他 AliPlayerKit 未直接透出的播放器介面

機制說明

• 通過 AliPlayerModel.onPlayerConfigBlock 設定回調 Block

• 每次調用 [controller configure:model] 時觸發

• 回調在 setDataSource: 之後、prepare 之前執行

• 回調參數為遵循 MediaPlayer 協議的底層播放器執行個體

使用方式

在構建 AliPlayerModel 時設定 onPlayerConfigBlock：

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];

// 設定執行個體級自訂配置回調
model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
    // 樣本 1：自訂緩衝策略
    AVPConfig *config = [player getConfig];
    config.maxBufferDuration = 50000;       // 最大緩衝時間長度 50s
    config.highBufferDuration = 3000;       // 高水位緩衝 3s
    config.startBufferDuration = 500;       // 起播緩衝 500ms
    [player setConfig:config];

    // 樣本 2：設定 Referer 防盜鏈
    AVPConfig *refConfig = [player getConfig];
    refConfig.referer = @"https://your-domain.com";
    [player setConfig:refConfig];

    // 樣本 3：設定執行個體級 Option
    // [player setOption:key value:value];
};

// 配置並播放
[controller configure:model];

配置時序

[controller configure:model]
    │
    ├── lifecycleStrategy.acquire()             ← 擷取播放器執行個體
    │
    ├── [mediaPlayer setDataSource:model]       ← 配置視頻源
    │
    ├── model.onPlayerConfigBlock(mediaPlayer)  ← 觸發執行個體配置回調
    │
    ├── [strategyManager start/reset]           ← 策略系統啟動
    │
    └── [mediaPlayer prepare]                   ← 開始準備播放

注意事項

內建配置項

AliPlayerKit 全域配置

通過 AliPlayerKit 類方法直接設定的內建配置項：

AliPlayerModel 執行個體配置

通過 AliPlayerModel 屬性設定的執行個體級配置項：

AliPlayerController 運行時配置

通過 AliPlayerController 方法在運行時動態調整的配置：

配置優先順序

優先順序規則

當同一配置項在不同層級都有設定時，按以下優先順序生效：

執行個體配置（onPlayerConfigBlock） > AliPlayerModel 屬性 > 全域配置 > SDK 預設值

配置生效範圍

完整配置樣本

綜合樣本

// ===== 全域配置（AppDelegate 中，僅一次）=====
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 全域自訂配置
    [AliPlayerKit setOnGlobalInitBlock:^{
        // 啟用 HTTP/2 多工
        [AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];
    }];

    // 初始化
    [AliPlayerKit setup];

    // 全域內建配置（需在 setup 之後調用）
    [AliPlayerKit setLogLevel:LogLevelWarn];
    [AliPlayerKit enableConsoleLog:YES];

    return YES;
}

// ===== 執行個體配置（播放頁中，每次播放）=====
- (void)startPlayback {
    VideoSource *source = [VideoSource urlSourceWithUrl:videoUrl];
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];

    // Model 屬性配置
    model.sceneType = SceneTypeVOD;
    model.videoTitle = @"精彩視頻";
    model.coverUrl = coverImageUrl;
    model.autoPlay = YES;
    model.hardwareDecode = YES;
    model.startTime = resumePosition; // 斷點續播

    // 執行個體級自訂配置（底層 SDK）
    model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
        AVPConfig *config = [player getConfig];
        config.maxBufferDuration = 50000;
        config.highBufferDuration = 3000;
        config.startBufferDuration = 500;
        config.referer = @"https://your-domain.com";
        [player setConfig:config];
    };

    [_controller configure:model];
}

API 速查

全域配置 API

執行個體配置 API

相關檔案

完整API請參見API參考。

常見問題

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

全域配置在應用啟動時（+setup 內）執行一次；執行個體配置在每次 configure: 時的 prepare 前執行。兩者互不干擾。

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

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

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

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

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

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

setOnGlobalInitBlock: 在 +setup 之後調用會怎樣？

不會生效。+setup 使用 dispatch_once 保證只執行一次，如果 Block 在 +setup 之後設定，將永遠不會被觸發。

日誌配置應該在 setup 之前還是之後？

setLogLevel: 和 enableConsoleLog: 需在 +setup 之後調用，因為它們直接操作 LogHub 單例。而 setOnGlobalInitBlock: 必須在 +setup 之前設定。