ApsaraVideo VOD:Integration preparation

Development environment

License

You must have a player license certificate and License Key for the ApsaraVideo Player SDK. For details, see Manage License.

Step 1: Copy the module to your project

Copy the PlayerKit/ directory to your project's directory (at the same level as your Podfile or in a suitable subdirectory):

YourProject/
├── YourApp/
├── PlayerKit/                  # ← Copy this directory
│   ├── PlayerKit.podspec
│   ├── Source/
│   └── Resources/
└── Podfile

Step 2: Configure the Podfile

In your Podfile, reference PlayerKit using its local path:

platform :ios, '11.0'

target 'YourApp' do
  use_frameworks!

  # Core component (required, referenced by local path)
  pod 'PlayerKit', :path => './PlayerKit'

  # Underlying player SDK (required)
  pod 'AliPlayerSDK_iOS', '~> 7.15.0'

  # RTS for ultra-low latency live streaming (optional, for live streaming scenarios only)
  # pod 'AliPlayerSDK_iOS_ARTC', '~> 7.15.0'
  # pod 'RtsSDK', '~> 7.12.0'
end

Step 3: Install dependencies

pod install
open YourApp.xcworkspace

Step 4: Configure the license

The player SDK requires a valid license to work. See Manage License to obtain and configure your license.

Step 5: Global initialization

This method should be called only once during the application lifecycle:

#import <AliPlayerKit/AliPlayerKit.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // (Optional) Global SDK configuration, such as setOption
    // [AliPlayerKit setOnGlobalInitBlock:^{
    //  Global configuration is executed only once after setup
    // }];

    // Initialize AliPlayerKit
    [AliPlayerKit setup];
    return YES;
}

import AliPlayerKit

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    // (Optional) Global SDK configuration
    // AliPlayerKit.setOnGlobalInitBlock {
    //  Global configuration is executed only once after setup
    // }

    // Initialize AliPlayerKit
    AliPlayerKit.setup()
    return true
}

Step 6: Verify the integration

Use the following checklist to verify the integration:

• pod install completes successfully without dependency conflicts.

• The license is configured correctly.

• [AliPlayerKit setup] is called in AppDelegate.

• The project builds successfully (Cmd + B) without linker errors.

Step 1: Copy the module to your project

Copy the PlayerKitScenes/ directory to your project, at the same level as PlayerKit/:

YourProject/
├── YourApp/
├── PlayerKit/                  # Component level (already copied)
├── PlayerKitScenes/            # ← Copy this directory
│   ├── PlayerKitScenes.podspec
│   ├── SceneCommon/
│   ├── SceneLongVideo/
│   ├── SceneShortVideo/
│   ├── SceneLive/
│   └── ScenePlaylist/
└── Podfile

Step 2: Configure the Podfile

In your Podfile, reference PlayerKitScenes using its local path:

target 'YourApp' do
  use_frameworks!

  # Core component (required)
  pod 'PlayerKit', :path => './PlayerKit'
  pod 'AliPlayerSDK_iOS', '~> 7.15.0'

  # Playback scene solutions (import as needed)
  pod 'PlayerKitScenes', :path => './PlayerKitScenes'

  # Or, select individual scenes as needed:
  # pod 'PlayerKitScenes/SceneLongVideo', :path => './PlayerKitScenes'
  # pod 'PlayerKitScenes/SceneShortVideo', :path => './PlayerKitScenes'
  # pod 'PlayerKitScenes/SceneLive', :path => './PlayerKitScenes'
  # pod 'PlayerKitScenes/ScenePlaylist', :path => './PlayerKitScenes'
end

Scene module descriptions:

Step 3: Install and verify

pod install

If your project builds successfully, the scene-level integration is complete.

Version information

• At runtime, call [AliPlayerKit getSdkVersion] to get the underlying SDK version number.

• Call [AliPlayerKit getPlayerKitVersion] to get the AliPlayerKit component version number.

• See Download Player SDK and iOS SDK Release History.

Upgrade steps

1. Confirm version compatibility.

   Before upgrading, review the SDK release history and changelog to check if the target version contains breaking changes.

2. Modify the version number in your Podfile.

   pod 'AliPlayerSDK_iOS', '~> x.x.x'  # Replace with the target version
   
   # RTS (if you use live streaming scenarios)
   # pod 'AliPlayerSDK_iOS_ARTC', '~> x.x.x'
   # pod 'RtsSDK', '~> x.x.x'

3. Run the update command.

   pod update AliPlayerSDK_iOS

4. Verify the upgrade.

   • The project builds successfully without linker errors.

   • Verify core playback functions: play, pause, seek, playback speed, etc.

   • Verify specific playback scenarios, such as ultra-low latency live streaming with RTS.

License issues

Problem: The player reports a license error or shows a black screen.

Common causes include an incorrectly added certificate file, a mismatched License Key, a Bundle ID that is inconsistent with the one bound to the license, or an expired license. For details, see Manage License.

Dependency conflicts

Problem: pod install fails with a dependency conflict.

Troubleshooting steps: This conflict can occur if your project and PlayerKit depend on different versions of SDWebImage. Try running pod update to resolve the conflict. If the issue persists, run pod repo update to refresh your local repository index before trying again.

Initialization issues

Problem: Playback does not work correctly after you call [AliPlayerKit setup].

Troubleshooting steps:

1. Ensure the call is made in application:didFinishLaunchingWithOptions: within AppDelegate.

2. Confirm that the license is configured correctly. For details, see Manage License.

3. Call [AliPlayerKit isInitialized] to confirm that the initialization was successful.

4. The setup method is idempotent (using dispatch_once). Repeated calls are safe and do not throw exceptions.

5. If you need to inject global SDK configurations, confirm that setOnGlobalInitBlock: is set before setup is called.

Debugging with logs

If you encounter playback issues, you can enable debug logs to help with troubleshooting:

// Enable debug mode
[AliPlayerKit setDebugModeEnabled:YES];
// Set the log level to Verbose for the most detailed output
[AliPlayerKit setLogLevel:LogLevelVerbose];

For details on how to use the logging system, see Logging System.