Integrate the ApsaraVideo Player SDK for iOS - ApsaraVideo VOD

This topic describes how to quickly integrate the ApsaraVideo Player software development kit (SDK) for iOS.

Environment requirements

System: iOS 8.0 or later.
Development tool: We recommend that you use Xcode. The procedures in this topic are based on Xcode. Download URL: Xcode.
Limits: The ApsaraVideo Player SDK for iOS does not support emulators. You must run the application on a physical device after integration.

Prerequisites

You have registered a license for the ApsaraVideo Player SDK and obtained the license file AliVideoCert-********.crt. For more information, see Obtain a license.
When you integrate the SDK locally, you must first download the ApsaraVideo Player SDK for iOS package. We recommend that you download the latest version.

Usage notes

When you package your application, the dSYM file is used for crash symbol parsing.
AlivcFFmpeg and AliyunPlayer are required when you use the ApsaraVideo Player SDK for iOS. The player header files are located in AliyunPlayer.
If you want to integrate both the ApsaraVideo Player SDK and the short video SDK, note the version dependencies among the short video SDK, the ApsaraVideo Player SDK, and AlivcFFmpeg. Otherwise, features of the short video SDK or ApsaraVideo Player SDK may fail. For more information, see AlivcFFmpeg dependencies.
The installation package of the ApsaraVideo Player SDK for iOS includes a simulator architecture. You must remove the simulator architecture before you publish the application. Otherwise, the application fails to be submitted to the App Store.

Step 1: Integrate the SDK

CocoaPods integration

Install CocoaPods. CocoaPods depends on the Ruby environment.

// Run this command in the terminal
sudo gem install cocoapods

Verify CocoaPods.
After the installation is complete, run pod --version in the terminal to verify that CocoaPods is installed.
```
xxx@ ~ % pod --version
1.16.2
```

Create a Podfile.

In the terminal, navigate to your project directory. Run the pod init command to create a Podfile.

// Go to your project directory.
xxx@ ~ %  cd /path/yourProject
// Generate the file.
xxx@ yourProject % pod init

Edit the Podfile to add the ApsaraVideo Player SDK dependency.
Note
- If you want to integrate both the ApsaraVideo Player SDK and the short video SDK, replace AliPlayerSDK_iOS in the following code with AliPlayerPartSDK_iOS. AliPlayerPartSDK_iOS does not contain the FFmpeg framework. This prevents conflicts with the FFmpeg framework of the short video SDK.
- Make sure that the version number of the ApsaraVideo Player SDK is correct. Otherwise, an error is reported and the SDK fails to be imported. For more information about the SDK versions, see Release notes of the ApsaraVideo Player SDK for iOS.
```
source 'https://github.com/CocoaPods/Specs.git'
platform:ios, '8.0'

target 'yourProject' do
    # We recommend that you use the latest version of the ApsaraVideo Player SDK.
    pod 'AliPlayerSDK_iOS'
end
```

Optionally, add a dependency on a specific version of the ApsaraVideo Player SDK.

source 'https://github.com/CocoaPods/Specs.git'
platform:ios, '8.0'

player_sdk_version = '7.12.0'

target 'yourProject' do
    # We recommend that you use the latest version of the ApsaraVideo Player SDK.
    pod 'AliPlayerSDK_iOS' , player_sdk_version
end

Install the dependencies.

Run the installation command to add the ApsaraVideo Player SDK dependency to the local repository.

pod install

The following sample result indicates that the installation is successful.

xxx@ yourProject % pod install
Analyzing dependencies
Downloading dependencies
Installing AliPlayerSDK_iOS (7.11.0)
Generating Pods project
Integrating client project
Pod installation complete! There is 1 dependency from the Podfile and 1 total pod installed.

Run the following command to update the ApsaraVideo Player SDK.

pod update AliPlayerSDK_iOS

Local integration

Note

If you want to integrate both the ApsaraVideo Player SDK and the short video SDK, you only need to import one AlivcFFmpeg. Make sure that you import the correct version of AlivcFFmpeg.

Download iOS player SDK.
Add the player frameworks to the Frameworks, Libraries, and Embedded Content section, and set Embed to Embed & Sign.
- alivcffmpeg.framework: the underlying framework of the player.
- AliyunMediaDownloader.framework: the framework for offline download.
- AliyunPlayer.framework: the player framework.
Click the Build Settings tab.
In the Search Paths section, set Framework Search Paths to the directory where the framework files are stored.

(Optional) Real-Time Streaming (RTS) integration (CocoaPods)

To integrate the Real-Time Streaming (RTS) component, see Implement RTS stream pulling on iOS.

Step 2: Configure the license

Important

If you use the global environment (regions outside the Chinese mainland, Hong Kong, Macao, and Taiwan), make sure to call the following API to update the default configuration to the international environment before you call any player APIs.

Method 1: Call the following API to update the default configuration to the international environment.

// If you use the global environment (regions outside the Chinese mainland, Hong Kong, Macao, and Taiwan), make sure to call the following API to update the default configuration to the international environment before you call any player APIs. This ensures that all subsequent services run in the international environment.
// Use the unified AlivcBase interface to set the international environment. The environment cannot be modified during runtime.
AlivcBase.EnvironmentManager.globalEnvironment = ENV_SEA;

Method 2 (Recommended): For ApsaraVideo Player SDK V7.6.0 or later, you can configure the international environment in the Info.plist file.
Open the Info.plist file and change the value of AlivcEnv to SEA.
```
// Configure the current environment as the international environment.
<key>AlivcEnv</key>
<string>SEA</string>
```
The following figure shows a sample configuration.

For more information about how to integrate a license in an iOS client, see Integrate a license in an iOS client.

Step 3: Enable logging (Optional)

Enabling logging helps you quickly locate and troubleshoot issues. It also provides data for performance optimization and user experience improvement. You can decide whether to enable logging based on your business scenarios. For more information about how to obtain logs, see Obtain SDK logs.

// Enable logging.
[AliPlayer setEnableLog:YES];
// Set the log level. The default level is LOG_LEVEL_INFO. To troubleshoot issues, set the level to LOG_LEVEL_TRACE.
[AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:nil];

Project structure

Framework	Description
alivcffmpeg.framework	The underlying framework of the player. This framework is required.
AliyunMediaDownloader.framework	Used for offline download. Not required.
AliyunPlayer.framework	A player is required.
artcSource.framework	The framework that supports the Alibaba Real-Time Communication (ARTC) protocol. This framework is optional. Note To support the ARTC protocol, you must also add RtsSDK.framework. For more information, see Implement RTS stream pulling on iOS.
aemFilter.framework	Audio enhancement is optional.
libPluginSR.framework	The framework for Video Ultra HD. This framework is optional.
normalsrFilter.framework	The framework for Video Ultra HD. This framework is optional.
srFilter.framework	The framework for Video Ultra HD. This framework is optional.
vfiFilter.framework	Video frame interpolation is optional.
vvcCodecPlugin.framwork	The plug-in for H.266 decoding. This framework is optional.

Common Integration Issues

How to use CocoaPods

// Deintegrate a project from CocoaPods dependencies.
pod deintegrate 

// Update the index of the local CocoaPods source.
// Scenarios:
// This command ensures that you can obtain the latest available version when you add a new dependency.
// If a specific version of a library is unavailable or a new version is released but does not appear in your project, you can run this command to update the index.
pod repo update

// Update the pods in your project.
// Scenarios:
// Run this command when you want to update all pods in your project to the latest supported versions.
// If you specify version ranges for dependencies in the Podfile, this command attempts to update the libraries to versions that meet the ranges.
pod update

// Perform the same function as pod install, but forcibly update the index of the local CocoaPods repository before installation.
// Scenarios:
// We recommend that you run this command when you add a new library or want to use the latest version of a library specified in the Podfile. This is useful when an error message indicates that the required library version is unavailable.
pod install --repo-update

// Clear the pod cache.
// Notes:
// 1. Clearing the cache does not modify your Podfile.lock or Podfile. CocoaPods redownloads the required libraries based on the manifest and lock files after you run pod install or pod update.
// 2. Clearing the cache is not a routine operation. Perform this operation only when you encounter specific issues. In normal cases, CocoaPods can manage its cache well.
pod cache clean --all

Your code or third-party code you reference conflicts with AlivcFFmpeg symbols during integration.

Solution:

Conflict with the symbol of AlivcFFmpeg: Retain only one AlivcFFmpeg and delete the extra AlivcFFmpeg dependencies. AlivcFFmpeg is a custom dependency developed by Alibaba Cloud based on FFmpeg and a key part of the ApsaraVideo Player SDK. We recommend that you delete the AlivcFFmpeg dependency for the third-party SDK and retain the AlivcFFmpeg dependency for the ApsaraVideo Player SDK. However, this may cause errors in the third-party player.

Sandbox Error

The issue is as follows:
Solution:
Set User Script SandBoxing in UserSettings to NO.

Short Video Integration

To integrate both the iOS player SDK and the short video SDK into your project, we recommend using the iOS all-in-one SDK for integration. This prevents duplicate class errors and compilation failures.

For more issues that may occur when you use the ApsaraVideo Player SDK and corresponding solutions, see FAQ about ApsaraVideo Player.

Feature documents

Basic features

Advanced features