AliPlayerKit iOS快速開始 - ApsaraVideo VOD

本文介紹如何快速接入AliPlayerKit iOS端，包括全域初始化、組件層接入和情境層接入的完整步驟。

說明

在開始之前，請確保您已經按照整合準備文檔完成環境配置和依賴添加。

說明

AI友好提示：本文檔為結構化文檔，步驟清晰，適合AI解析與執行。可作為Skills用於輔助開發流程，推薦使用AI輔助接入AliPlayerKit。

AliPlayerKit提供了極簡的API設計，協助您以低代碼的方式快速整合視頻播放功能。

選擇接入方案

AliPlayerKit採用分層架構設計。除組件層接入外，還提供情境層接入方式，您可以根據業務需求靈活選擇：

接入方案	模組	說明	適用情境
組件層接入	`PlayerKit`	使用PlayerKit核心模組，提供可配置的播放器UI組件。	需要自訂播放器UI或靈活控制播允許存取為。
情境層接入	`PlayerKitScenes`	在組件層基礎上，使用完整業務情境解決方案。	快速實現標準播放情境，如長視頻、短視頻、直播。

說明

情境層相依元件層。若選擇情境層接入，需先完成組件層接入。

全域初始化

在AppDelegate的application:didFinishLaunchingWithOptions:中調用[AliPlayerKit setup]進行全域初始化。整個應用生命週期只需調用一次。

Object C

#import <PlayerKit/AliPlayerKit.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 初始化 AliPlayerKit 全域設定
    [AliPlayerKit setup];
    return YES;
}

@end

Swift

import AliPlayerKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // 初始化 AliPlayerKit 全域設定
        AliPlayerKit.setup()
        return true
    }
}

說明

AliPlayerKit 還提供其他全域配置介面，如日誌系統、預先載入策略等，詳情請參見API參考。

方案一：組件層接入

組件層（PlayerKit模組）提供開箱即用、可配置的播放器UI組件。在每個需要播放視頻的頁面中，按以下步驟實現播放功能。

步驟1：添加播放器視圖

在ViewController中建立AliPlayerView並添加到視圖層級：

Object C

AliPlayerView *playerView = [[AliPlayerView alloc] initWithFrame:self.view.bounds];
[self.view addSubview:playerView];

Swift

let playerView = AliPlayerView(frame: view.bounds)
view.addSubview(playerView)

AliPlayerView 可放置在您視圖層級的任意位置，frame 可根據實際需求設定。如需支援全屏切換，組件內部會自動處理視圖層級調整。

步驟2：綁定控制器並播放

重要

configure:必須在attach:之前調用，否則視圖綁定時無法擷取播放配置。

在 ViewController 中建立控制器、配置資料、綁定視圖：

建立 AliPlayerController。
配置 AliPlayerModel（推薦使用 VidAuth 方式，也可使用 URL 源快速測試）。
調用 configure: + attach:。
在 dealloc 中調用 destroy 釋放資源。

Object C

#import <PlayerKit/AliPlayerKit.h>

@interface VideoPlayerViewController ()
@property (nonatomic, strong) AliPlayerView *playerView;
@property (nonatomic, strong) AliPlayerController *controller;
@end

@implementation VideoPlayerViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // 1. 建立播放器視圖
    self.playerView = [[AliPlayerView alloc] initWithFrame:self.view.bounds];
    [self.view addSubview:self.playerView];

    // 2. 建立播放控制器
    self.controller = [[AliPlayerController alloc] init];

    // 3. 配置播放資料（推薦使用 VidAuth 方式）
    VideoSource *source = [VideoSource vidAuthSourceWithVid:@"您的視頻 ID"
                                                  playAuth:@"您的播放憑證"];
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
    model.videoTitle = @"樣本視頻";

    // 4. 配置播放源並綁定視圖（綁定後自動開始播放）
    [self.controller configure:model];
    [self.playerView attach:self.controller];
}

- (void)dealloc {
    // 銷毀播放器，釋放資源
    [self.controller destroy];
}

@end

Swift

import AliPlayerKit

class VideoPlayerViewController: UIViewController {

    private let playerView = AliPlayerView(frame: .zero)
    private let controller = AliPlayerController()

    override func viewDidLoad() {
        super.viewDidLoad()

        // 1. 建立播放器視圖
        playerView.frame = view.bounds
        view.addSubview(playerView)

        // 2. 配置播放資料（推薦使用 VidAuth 方式）
        let source = VideoSource.vidAuthSource(withVid: "您的視頻 ID", playAuth: "您的播放憑證")
        let model = AliPlayerModel(videoSource: source)
        model.videoTitle = "樣本視頻"

        // 3. 配置播放源並綁定視圖（綁定後自動開始播放）
        controller.configure(model)
        playerView.attach(controller)
    }

    deinit {
        // 銷毀播放器，釋放資源
        controller.destroy()
    }
}

說明

如果暫時無法擷取視頻ID和播放憑證，可使用URL 源快速測試，情境模組內建了 SceneConstants 樣本資料，也可直接參考使用。

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

AliPlayerModel.autoPlay 預設為 YES，配置完成後自動開始播放，無需手動調用 play。
AliPlayerController.autoLifecycleManagement 預設為 YES，會自動處理應用前後台切換時的播放暫停與恢複。但頁面級導航（如 push/pop）需要手動在 viewDidAppear / viewWillDisappear 中調用 onResume / onPause。
configure: 內部通過生命週期策略擷取播放器執行個體、設定資料來源並準備播放。
dealloc 中必須調用 destroy 銷毀控制器，否則會導致記憶體流失。

步驟3（可選）：處理返回鍵

如果您需要自訂播放器的返回行為，可通過 onBackPressed 回調實現：

Object C

__weak typeof(self) weakSelf = self;
self.playerView.onBackPressed = ^{
    [weakSelf.navigationController popViewControllerAnimated:YES];
};

Swift

playerView.onBackPressed = { [weak self] in
    self?.navigationController?.popViewController(animated: true)
}

當播放器處於全屏狀態時，返回操作會自動結束全屏，不觸發此回調。僅在非全屏狀態下才會通知外部。若未設定此回調，播放器將通過 responder chain 嘗試預設導航行為（pop / dismiss）。

步驟4（可選）：自訂配置

如需在播放器準備前注入自訂 SDK 配置（如緩衝策略、Referer 等），可通過 onPlayerConfigBlock 實現：

Object C

model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
    // 在 prepare 前執行，可訪問底層播放器執行個體進行自訂配置
    // 例如：設定緩衝配置、Referer、setOption 等
};

Swift

model.onPlayerConfigBlock = { player in
    // 在 prepare 前執行，可訪問底層播放器執行個體進行自訂配置
}

說明

全域配置通過 [AliPlayerKit setOnGlobalInitBlock:] 在 setup 前設定（僅執行一次）；執行個體配置通過 model.onPlayerConfigBlock 在每次 configure: 時觸發。詳情請參見自訂配置。

方案二：情境層接入

情境層提供針對特定業務情境的完整播放解決方案，如長視頻、短視頻、直播等。情境層基於組件層封裝，整合後即可開箱使用，無需額外開發。

步驟1：選擇情境模組

情境模組位於 PlayerKitScenes 目錄下，通過 CocoaPods subspecs 引入，當前包含：

情境模組	Pod Subspec	說明
`SceneCommon`	`PlayerKitScenes/SceneCommon`	情境公用模組（必需，其他情境模組的基礎依賴）
`SceneLongVideo`	`PlayerKitScenes/SceneLongVideo`	中長視頻情境：提供中長視頻播放的完整解決方案
`SceneShortVideo`	`PlayerKitScenes/SceneShortVideo`	短視頻情境：提供短視頻滑動播放的完整解決方案
`SceneLive`	`PlayerKitScenes/SceneLive`	直播情境：提供直播播放的完整解決方案。額外依賴 `DemoSettings` 模組，單獨整合時需一併拷貝
`ScenePlaylist`	`PlayerKitScenes/ScenePlaylist`	列表播放情境：提供視頻列表播放的完整解決方案

步驟2：啟動情境頁面

情境模組整合完成後，可通過以下兩種方式啟動情境頁面：

方式一：直接執行個體化（推薦）

每個情境模組提供獨立的 ViewController，可直接執行個體化並通過 UINavigationController 跳轉：

Object C

#import "SceneLongVideoViewController.h"

// 跳轉到中長視頻情境
SceneLongVideoViewController *vc = [[SceneLongVideoViewController alloc] init];
[self.navigationController pushViewController:vc animated:YES];

Swift

// 跳轉到中長視頻情境
let vc = SceneLongVideoViewController()
navigationController?.pushViewController(vc, animated: true)

各情境對應的 ViewController：

情境	ViewController
中長視頻	`SceneLongVideoViewController`
短視頻	`SceneShortVideoViewController`
直播	`SceneLiveViewController`
列表播放	`ScenePlaylistViewController`

方式二：Schema路由

情境模組支援通過 Schema 協議啟動對應的播放情境。Demo 工程中提供了 AppSchemaRouter 路由工具類，可通過 Schema URL 自動探索並跳轉到對應情境：

Object C

#import "AppSchemaRouter.h"

// 通過 Schema 跳轉到中長視頻情境
[AppSchemaRouter navigateToSchema:@"playerkit://scenes/longvideo" fromViewController:self];

Swift

// 通過 Schema 跳轉到中長視頻情境
AppSchemaRouter.navigate(toSchema: "playerkit://scenes/longvideo", from: self)

各情境對應的 Schema 地址：

情境	Schema
中長視頻	`playerkit://scenes/longvideo`
短視頻	`playerkit://scenes/shortvideo`
直播	`playerkit://scenes/live`
列表播放	`playerkit://scenes/playlist`

說明

ppSchemaRouter 是 Demo 工程（App 模組）中提供的路由工具，基於 AppModuleProtocol 協議實現模組自動探索。情境模組通過 *Module 類（如 SceneLongVideoModule）註冊自身的 Schema、標題和優先順序。如需在您的應用中使用 Schema 路由，可參考此實現或對接您自己的路由架構。

情境實現參考

情境模組的源碼可作為組件層接入的最佳實務參考。以下是各情境的核心實現模式：

中長視頻情境

SceneLongVideoViewController 展示了標準的組件層接入流程：

// 初始化 AliPlayerKit 播放組件
- (void)setupPlayerKit {
    // 1. 建立播放器組件視圖
    self.playerView = [[AliPlayerView alloc] initWithFrame:self.view.bounds];
    [self.view addSubview:self.playerView];

    // 可選：設定返回鍵回調
    __weak typeof(self) weakSelf = self;
    self.playerView.onBackPressed = ^{
        [weakSelf.navigationController popViewControllerAnimated:YES];
    };

    // 2. 建立播放器組件控制器
    self.playerController = [[AliPlayerController alloc] init];

    // 3. 配置播放器組件資料
    VideoSource *source = [VideoSource vidAuthSourceWithVid:@"視頻 ID" playAuth:@"播放憑證"];
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
    model.videoTitle = @"Long Video";

    // 4. 配置播放源並將控制器掛載到視圖（掛載後自動開始播放）
    [self.playerController configure:model];
    [self.playerView attach:self.playerController];
}

直播情境

SceneLiveViewController 展示了 URL 源 + 直播情境類型的用法：

VideoSource *source = [VideoSource urlSourceWithUrl:liveUrl];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.videoTitle = @"Live Stream";
model.sceneType = SceneTypeLive;  // 設定為直播情境類型

[self.playerController configure:model];
[self.playerView attach:self.playerController];

說明

SceneType 影響插槽可見度配置和 UI 行為。直播情境下會自動隱藏進度條等點播元素。詳情請參見情境類型。

列表播放情境

ScenePlaylistViewController 展示了 SingletonLifecycleStrategy + PlayerNotificationDelegate 實現自動連播的進階用法：

// 使用單例生命週期策略複用播放器執行個體
self.lifecycleStrategy = [SingletonLifecycleStrategy sharedInstance];
self.currentController = [[AliPlayerController alloc] initWithLifecycleStrategy:self.lifecycleStrategy];

// 註冊播放完成通知，用於觸發自動播放下一個
[self.currentController addNotificationDelegate:self];

// PlayerNotificationDelegate 回調
- (void)playerDidCompletion {
    [self playNextVideo];  // 當前視頻播放完成，自動播放下一個
}

說明

列表播放情境通過 initWithLifecycleStrategy: 指定生命週期策略，複用播放器執行個體以提升效能。詳情請參見播放器生命週期策略。

樣本與擴充

通過以上步驟，您已經完成了 AliPlayerKit 的基礎接入，並成功實現了視頻播放。

如需查看更多樣本，可參考以下目錄：

模組	說明
`PlayerKitUsages`	提供常見 API 的使用樣本（日誌系統、插槽系統、通知系統、策略系統、生命週期策略、預先載入、視頻源、本地化）
`PlayerKitScenes`	提供典型播放情境的解決方案（長視頻、短視頻、直播、列表播放）

各使用樣本的 Schema 路由格式為 playerkit://usages/<模組名>，可通過 Demo 工程首頁直接進入。