AliPlayerKit快速開始 - ApsaraVideo VOD

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

說明

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

說明

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

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

選擇接入方案

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

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

說明

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

全域初始化

在Application.onCreate()中調用AliPlayerKit.init()進行全域初始化。整個應用生命週期只需調用一次，用於初始化播放器核心和全域配置。

Java

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // 初始化AliPlayerKit全域設定
        AliPlayerKit.init(this);
    }
}

Kotlin

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // 初始化AliPlayerKit全域設定
        AliPlayerKit.init(this)
    }
}

說明

AliPlayerKit還提供其他全域配置介面，如setPlayerViewType()、setDisableScreenshot()等，詳情請參見API參考。

方案一：組件層接入

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

步驟1：添加播放器視圖

在布局XML中添加AliPlayerView：

<!-- 播放器組件視圖 -->
<com.aliyun.playerkit.AliPlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

AliPlayerView可直接放入您的布局中，寬高可根據實際需求設定。如需外層容器（如全屏切換情境），可自行添加FrameLayout或其他容器包裹。

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

重要

如果您的應用支援全屏播放切換，需要在AndroidManifest.xml中為播放 Activity 配置android:configChanges屬性，防止旋轉螢幕時Activity被重建導致播放狀態丟失：

<application>
    <activity
        android:name=".VideoPlayerActivity"
        android:configChanges="orientation|screenSize"
        ...>
    </activity>
</application>

配置後，旋轉螢幕時不會觸發 Activity 重建，播放器狀態得以保持。

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

Java

public class VideoPlayerActivity extends AppCompatActivity {

    private AliPlayerView playerView;
    private AliPlayerController controller;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_video_player);

        // 1. 建立播放控制器
        controller = new AliPlayerController(this);

        // 2. 配置播放資料（推薦使用 VidAuth 方式）
        controller.configure(new AliPlayerModel.Builder()
                .videoSource(VideoSourceFactory.createVidAuthSource(
                        "您的視頻 ID",    // 視頻 ID
                        "您的播放憑證"    // 播放憑證
                ))
                .sceneType(SceneType.VOD)
                .coverUrl("https://example.com/cover.jpg")  // 替換為實際封面圖地址
                .videoTitle("樣本視頻")
                .autoPlay(true)
                .build());

        // 3. 綁定視圖
        playerView = findViewById(R.id.player_view);
        playerView.attach(controller);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        // 4. 銷毀播放器，釋放資源
        controller.destroy();
    }
}

Kotlin

class VideoPlayerActivity : AppCompatActivity() {

    private lateinit var playerView: AliPlayerView
    private lateinit var controller: AliPlayerController

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_video_player)

        // 1. 建立播放控制器
        controller = AliPlayerController(this)

        // 2. 配置播放資料（推薦使用 VidAuth 方式）
        controller.configure(AliPlayerModel.Builder()
                .videoSource(VideoSourceFactory.createVidAuthSource(
                        "您的視頻 ID",    // 視頻 ID
                        "您的播放憑證"    // 播放憑證
                ))
                .sceneType(SceneType.VOD)
                .coverUrl("https://example.com/cover.jpg")  // 替換為實際封面圖地址
                .videoTitle("樣本視頻")
                .autoPlay(true)
                .build())

        // 3. 綁定視圖
        playerView = findViewById(R.id.player_view)
        playerView.attach(controller)
    }

    override fun onDestroy() {
        super.onDestroy()
        // 4. 銷毀播放器，釋放資源
        controller.destroy()
    }
}

說明

如果暫時無法擷取視頻ID和播放憑證，可使用SceneConstants.java中提供的樣本資料進行測試，以便快速跑通樣本。

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

如果您的應用支援全屏播放，需要在Activity中處理返回鍵事件：

Java

@Override
public void onBackPressed() {
    // 如果處於全屏狀態，退出全屏
    if (playerView.onBackPressed()) {
        return;  // 已處理，不執行預設行為
    }
    super.onBackPressed();  // 未處理，執行預設行為
}

Kotlin

@Deprecated("Deprecated in Java")
override fun onBackPressed() {
    // 如果處於全屏狀態，退出全屏
    if (playerView.onBackPressed()) {
        return  // 已處理，不執行預設行為
    }
    super.onBackPressed()  // 未處理，執行預設行為
}

說明

各組件的完整API說明，請參閱API參考文檔。核心介面調用流程請參閱核心能力文檔。

方案二：情境層接入

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

步驟1：選擇情境模組

情境模組位於playerkit-scenes目錄下，當前包含：

情境模組	說明
`scene-common`	情境公用模組（必需，其他情境模組的基礎依賴）。
`scene-longvideo`	中長視頻情境：提供中長視頻播放的完整解決方案。
`scene-shortvideo`	短視頻情境：提供短視頻滑動播放的完整解決方案。
`scene-live`	直播情境：提供直播播放的完整解決方案。
`scene-playlist`	列表播放情境：提供視頻列表播放的完整解決方案。

步驟2：啟動情境頁面

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

方式一：Intent跳轉

Java

// 跳轉到中長視頻情境
Intent intent = new Intent(this, LongVideoActivity.class);
startActivity(intent);

Kotlin

// 跳轉到中長視頻情境
val intent = Intent(this, LongVideoActivity::class.java)
startActivity(intent)

方式二：Schema跳轉

情境模組支援通過Schema協議啟動對應的播放情境。各情境的Schema定義在對應模組的AndroidManifest.xml中，可查看<intent-filter>的<data>標籤擷取具體協議地址。

例如，AndroidManifest.xml中的配置如下：

<data
    android:host="scenes"
    android:path="/longvideo"
    android:scheme="playerkit" />

可以拼接得到對應的Schema地址：

playerkit://scenes/longvideo

Java

// 跳轉到目標情境（替換為實際Schema）
Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("對應的Schema地址"));
startActivity(intent);

Kotlin

// 跳轉到目標情境（替換為實際Schema）
val intent = Intent(Intent.ACTION_VIEW).apply {
    data = Uri.parse("對應的Schema地址")
}
startActivity(intent)

樣本與擴充

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

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

playerkit-examples：提供常見API的使用樣本。
playerkit-scenes：提供典型播放情境的解決方案。