AliPlayerKit quick start-ApsaraVideo VOD(VOD)-阿里云帮助中心

This document shows you how to quickly integrate AliPlayerKit, from global initialization to component and scene layer integration.

Note

Before you begin, make sure you have configured your environment and added the required dependencies as described in Integration preparations.

Note

AI-Friendly Tip: This document is structured for easy AI parsing. You can use it as Skills to accelerate your development workflow.

AliPlayerKit's minimalist API lets you quickly integrate video playback features with low code.

Choose an integration option

AliPlayerKit uses a layered architecture, offering both component and scene layer integration. Choose the option that best fits your business needs:

Integration option	Module	Description	Use case
Component layer integration	`playerkit`	Uses the `playerkit` core module, which includes a configurable player UI component.	Requires a custom player UI or flexible control over playback behavior.
Scene layer integration	`playerkit-scenes`	Provides complete, pre-built solutions for common scenarios, built on the component layer.	Quickly implement standard playback scenarios, such as long-form video, short-form video, and live streaming.

Note

The scene layer depends on the component layer, so you must complete component layer integration first.

Global initialization

Call AliPlayerKit.init() in Application.onCreate() for global initialization. This method should be called only once during the application's lifecycle to initialize the player core and global settings.

Java

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // Initialize global settings for AliPlayerKit.
        AliPlayerKit.init(this);
    }
}

Kotlin

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // Initialize global settings for AliPlayerKit.
        AliPlayerKit.init(this)
    }
}

Note

AliPlayerKit provides other global configuration methods, such as setPlayerViewType() and setDisableScreenshot(). For details, see the API reference.

Option 1: Component layer integration

The component layer (the playerkit module) provides an out-of-the-box, configurable player UI component. Follow these steps to implement playback functionality on each page that requires video playback.

Step 1: Add the player view

Add AliPlayerView to your layout XML file:

<!-- Player component view -->
<com.aliyun.playerkit.AliPlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Place AliPlayerView directly into your layout, with its width and height set as needed. If an outer container is required (for example, to support full screen switching), you can wrap it in a FrameLayout or another container.

Step 2: Bind controller and start playback

Important

If your application supports switching to full screen, you must configure the android:configChanges attribute for the player Activity in your AndroidManifest.xml. This prevents the Activity from being recreated when the screen rotates, which would otherwise cause the playback state to be lost.

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

After this configuration, screen rotation will not trigger Activity recreation, thus preserving the player's state.

In your Activity or Fragment, create the controller, configure the data, and bind it to the view:

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. Get the player view.
        playerView = findViewById(R.id.player_view);

        // 2. Create the player controller.
        controller = new AliPlayerController(this);

        // 3. Configure playback data (VidAuth is recommended).
        AliPlayerModel model = new AliPlayerModel.Builder()
                .videoSource(VideoSourceFactory.createVidAuthSource(
                        "your_video_id",    // Video ID
                        "your_playback_credential"    // Playback credential
                ))
                .coverUrl("https://example.com/cover.jpg")  // Replace with your actual cover image URL.
                .videoTitle("Sample Video")
                .autoPlay(true)
                .build();

        // 4. Bind the controller to the view.
        playerView.attach(controller, model);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        // 5. Detach and release resources.
        playerView.detach();
    }
}

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. Get the player view.
        playerView = findViewById(R.id.player_view)

        // 2. Create the player controller.
        controller = AliPlayerController(this)

        // 3. Configure playback data (VidAuth is recommended).
        val model = AliPlayerModel.Builder()
                .videoSource(VideoSourceFactory.createVidAuthSource(
                        "your_video_id",    // Video ID
                        "your_playback_credential"    // Playback credential
                ))
                .coverUrl("https://example.com/cover.jpg")  // Replace with your actual cover image URL.
                .videoTitle("Sample Video")
                .autoPlay(true)
                .build()

        // 4. Bind the controller to the view.
        playerView.attach(controller, model)
    }

    override fun onDestroy() {
        super.onDestroy()
        // 5. Detach and release resources.
        playerView.detach()
    }
}

Note

If you do not yet have a video ID and playback credential, you can use the sample data provided in SceneConstants.java to quickly run the example for testing.

Step 3 (Optional): Handle the back button

If your application supports full screen playback, you need to handle the back button event in your Activity:

Java

@Override
public void onBackPressed() {
    // If in full screen mode, exit full screen.
    if (playerView.onBackPressed()) {
        return;  // Event handled, do not perform the default action.
    }
    super.onBackPressed();  // Event not handled, perform the default action.
}

Kotlin

@Deprecated("Deprecated in Java")
override fun onBackPressed() {
    // If in full screen mode, exit full screen.
    if (playerView.onBackPressed()) {
        return  // Event handled, do not perform the default action.
    }
    super.onBackPressed()  // Event not handled, perform the default action.
}

Note

For complete API descriptions of each component, see the API reference. For the core API call flow, see Core capabilities.

Option 2: Scene layer integration

The scene layer provides complete playback solutions for specific business scenarios, such as long-form video, short-form video, and live streaming. The scene layer is built on the component layer and is ready to use out-of-the-box, requiring no extra development.

Step 1: Choose a scene module

Scene modules are located in the playerkit-scenes directory. The available modules include:

Scene module	Description
`scene-common`	Common scene module (required). Other scene modules depend on it.
`scene-longvideo`	Provides a complete solution for long-form video playback.
`scene-shortvideo`	Provides a complete solution for swipe-based short-form video playback.
`scene-live`	Provides a complete solution for live streaming playback.
`scene-playlist`	Provides a complete solution for playlist playback.

Step 2: Launch the scene page

After you integrate a scene module, you can launch the scene page in one of two ways:

Method 1: Intent navigation

Java

// Navigate to the long-form video scenario.
Intent intent = new Intent(this, LongVideoActivity.class);
startActivity(intent);

Kotlin

// Navigate to the long-form video scenario.
val intent = Intent(this, LongVideoActivity::class.java)
startActivity(intent)

Method 2: Schema navigation

Scene modules support schema navigation to start a specific playback scenario. The schema for each scenario is defined in the AndroidManifest.xml of the corresponding module. You can find the specific schema URL inside the <intent-filter>'s <data> tag.

For example, if the configuration in AndroidManifest.xml is as follows:

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

Construct the schema URL as follows:

playerkit://scenes/longvideo

Java

// Navigate to the target scenario (replace with the actual schema URL).
Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("your_schema_url_here"));
startActivity(intent);

Kotlin

// Navigate to the target scenario (replace with the actual schema URL).
val intent = Intent(Intent.ACTION_VIEW).apply {
    data = Uri.parse("your_schema_url_here")
}
startActivity(intent)

Examples and extensions

You have now completed the basic integration of AliPlayerKit and implemented video playback.

For more examples, refer to the following directories:

playerkit-examples: Provides usage examples for common APIs.
playerkit-scenes: Provides solutions for typical playback scenarios.