Integrate Flutter Player SDK for Video Playback - ApsaraVideo VOD

Play a video in your Flutter app using the ApsaraVideo Player SDK. This guide covers player creation, video view setup, playback source configuration, and resource cleanup.

Prerequisites

Integrate the Flutter player SDK into your project. For instructions, see Integrate the Flutter player SDK.

Procedure

Step 1: Create a player

FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer();
fAliplayer.setTraceID("traceId");

The setTraceID parameter controls instrumentation log reporting. This powers features such as playback quality monitoring, single-point tracking, and video playback statistics.

`setTraceID` value	Instrumentation log reporting	Available features
Not set (default)	Enabled	Playback quality monitoring, video playback statistics
A unique identifier such as a user ID, IMEI, or IDFA	Enabled	Playback quality monitoring, single-point tracking, video playback statistics
`DisableAnalytics`	Disabled	None

To use single-point tracking, pass a unique identifier for the user or device, such as your business user ID, an International Mobile Equipment Identity (IMEI), or an identifier for advertisers (IDFA).

Step 2: Set up the video view

Create an AliPlayerView widget and attach the player after the view is created.

// 1. Create the player view widget
AliPlayerView aliPlayerView = AliPlayerView(
  onCreated: onViewPlayerCreated,
  x: 0,
  y: 0,
  width: width,
  height: height,
  aliPlayerViewType: AliPlayerViewTypeForAndroid.surfaceview);

// 2. Attach the player to the view
void onViewPlayerCreated(viewId) async {
  fAliplayer.setPlayerView(viewId);
}

Step 3: Set the playback source

The SDK supports three playback source types. Choose one based on your use case.

VidAuth (recommended)

Use VidAuth for secure playback with a short-lived playback credential. Call the GetVideoPlayAuth operation of ApsaraVideo VOD to get the playAuth value.

fAliplayer.setVidAuth(
  vid: "<your-video-id>",       // Required. The video ID (VideoId).
  playAuth: "<your-play-auth>", // Required. The playback credential from GetVideoPlayAuth.
  region: "<your-region>",      // Required. The region of ApsaraVideo VOD. Default: cn-shanghai.
);

VidSts

Use VidSts for playback with temporary Security Token Service (STS) credentials. Call the AssumeRole operation of STS to get the required values.

fAliplayer.setVidSts(
  vid: "<your-video-id>",              // Required. The video ID (VideoId).
  accessKeyId: "<your-access-key-id>",         // Required. The AccessKey ID from the temporary AccessKey pair.
  accessKeySecret: "<your-access-key-secret>", // Required. The AccessKey secret from the temporary AccessKey pair.
  securityToken: "<your-security-token>",      // Required. The STS token.
  region: "<your-region>",             // Required. The region of ApsaraVideo VOD. Default: cn-shanghai.
);

UrlSource

Use UrlSource for direct URL-based playback.

fAliplayer.setUrl("<your-video-url>");

For more playback source details, see Basic features.

Step 4: Start playback

fAliplayer.prepare();
fAliplayer.play();

Step 5: Release the player

Stop playback, release resources, and clear the player reference when playback ends.

fAliplayer.stop();
fAliplayer.release();
fAliplayer = null; // Prevents memory leaks

Always call release() and set the player to null when it is no longer needed. Otherwise, memory leaks occur.

Complete example

The following example combines all steps into a single flow.

// Step 1: Create a player
FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer();
fAliplayer.setTraceID("traceId");

// Step 2: Set up the video view
AliPlayerView aliPlayerView = AliPlayerView(
  onCreated: (viewId) async {
    fAliplayer.setPlayerView(viewId);
  },
  x: 0,
  y: 0,
  width: width,
  height: height,
  aliPlayerViewType: AliPlayerViewTypeForAndroid.surfaceview);

// Step 3: Set the playback source (VidAuth)
fAliplayer.setVidAuth(
  vid: "<your-video-id>",
  playAuth: "<your-play-auth>",
  region: "<your-region>",
);

// Step 4: Start playback
fAliplayer.prepare();
fAliplayer.play();

// Step 5: Release the player when done
fAliplayer.stop();
fAliplayer.release();
fAliplayer = null;

References

For more details on basic player features such as playback control and event listeners, see Basic features.