Quickly integrate the ApsaraVideo Player SDK for iOS - ApsaraVideo VOD

This topic describes how to quickly integrate the ApsaraVideo Player SDK for iOS.

Environment requirements

Operating system: iOS 8.0 or later.
Development tool: Xcode is recommended. The steps in this topic use Xcode. You can download it from ‎Xcode.
Limits: The ApsaraVideo Player SDK for iOS does not support emulators. You must run your project on a physical device after integration.

Prerequisites

You have registered for and obtained a license file that contains the player authorization: AliVideoCert-********.crt. For more information, see Obtain a license.
For local integration, download the ApsaraVideo Player SDK for iOS package. We recommend that you download the latest version.

Notes

The dSYM file is used to parse crash symbol tables during packaging.
Both AlivcFFmpeg and AliyunPlayer are required when you use the ApsaraVideo Player SDK for iOS. The player header files are 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 the player may not work. For more information, see AlivcFFmpeg version dependencies.
The installation package of the ApsaraVideo Player SDK for iOS includes the emulator architecture. You must remove this architecture before you publish your app. Otherwise, your submission to the App Store will be rejected.

Step 1: Integrate the SDK

CocoaPods integration

Install CocoaPods. CocoaPods depends on the Ruby environment.
```
// Run in the terminal
sudo gem install cocoapods
```
Verify the CocoaPods installation.
After the installation is complete, run the pod --version command 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 with AliPlayerPartSDK_iOS in the following code. AliPlayerPartSDK_iOS does not include ffmpeg. This prevents conflicts with the ffmpeg in the short video SDK.
- Make sure that you enter the correct version number for the ApsaraVideo Player SDK. Otherwise, an error occurs and the import fails. For more information about SDK versions, see Release notes for ApsaraVideo Player SDK for iOS.
```
source 'https://github.com/CocoaPods/Specs.git'
platform:ios, '8.0'

target 'yourProject' do
    # ApsaraVideo Player SDK. We recommend using the latest version.
    pod 'AliPlayerSDK_iOS'
end
```

(Optional) 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.10.0'

target 'yourProject' do
    # ApsaraVideo Player SDK. We recommend using the latest version.
    pod 'AliPlayerSDK_iOS' , player_sdk_version
end

Install the dependency.

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

pod install

The following output indicates that the installation is successful.

xxx@ yourProject % pod install
Analyzing dependencies
Downloading dependencies
Installing AliPlayerSDK_iOS (7.8.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, import only one AlivcFFmpeg and make sure that its version is correct.

Download the ApsaraVideo Player SDK for iOS.
Add the player's framework to Frameworks, Libraries, and Embedded Content, and set Embed to Embed & Sign.
- alivcffmpeg.framework: the underlying layer of the player.
- AliyunMediaDownloader.framework: used for offline downloads.
- AliyunPlayer.framework: the player.
Click the Build Settings tab.
In the Search Paths section, click Framework Search Paths and change the value to the directory where the local framework is located.

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

To integrate the RTS component, see Implement RTS stream pulling on iOS.

Step 2: Configure the license

Important

When you use the global environment, which excludes the Chinese mainland, Hong Kong, and Macao, make sure that you call the following interface to update the default configuration to the Alibaba Cloud International site environment before you call any player API.

Method 1: Call the following interface to update the default configuration to the Alibaba Cloud International site environment.

// When using the global environment (excluding the Chinese mainland, Hong Kong, and Macao), make sure to call the following interface to update the default configuration to the Alibaba Cloud International Website environment before calling any player API. This ensures that all subsequent services run in the Alibaba Cloud International Website environment.
// Set the Alibaba Cloud International Website environment through the unified AlivcBase interface. This setting cannot be modified during runtime.
AlivcBase.EnvironmentManager.globalEnvironment = ENV_SEA;

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

To integrate the license on an iOS client, see Integrate a license on an iOS client.

Step 3: Enable logging (Optional)

Enabling logs helps you quickly locate and troubleshoot issues. Logs also provide data for performance optimization and user experience improvements. You can enable logging based on your business scenario. 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 layer of the player. Required.
AliyunMediaDownloader.framework	Used for offline download. Optional.
AliyunPlayer.framework	The player. Required.
artcSource.framework	Supports the artc protocol. Optional. Note To support the artc protocol, you also need to append RtsSDK.framework. For the specific integration process, see Implement RTS stream pulling on iOS.
aemFilter.framework	Audio enhancement. Optional.
libPluginSR.framework	Video Ultra HD. Optional.
normalsrFilter.framework	Video Ultra HD. Optional.
srFilter.framework	Video Ultra HD. Optional.
vfiFilter.framework	Video frame interpolation. Optional.
vvcCodecPlugin.framwork	H.266 decoding plugin. Optional.

Common integration issues

How to use CocoaPods

// Deintegrate a project from CocoaPods dependencies.
pod deintegrate 

// Update the index of the local CocoaPods source repository.
// Scenarios:
// When you add a new dependency, this command ensures that you can get the latest available version.
// When a library version is unavailable, or you know a new version exists but it does not appear in your project, you can use this command to update.
pod repo update

// Update the pods in the project.
// Scenarios:
// Use this command when you want to update all pods in your project to the latest supported versions.
// You may have specified version ranges for some dependencies in your Podfile. Using 'pod update' attempts to satisfy these ranges and update the corresponding libraries.
pod update

// Performs the same function as 'pod install', but forces an update of the local CocoaPods repository index before installation.
// Scenarios:
// This command is a good idea when you add a new library or want to use the latest version of a library specified in your Podfile. It is especially useful when you see an error message indicating that the required library version is unavailable.
pod install --repo-update

// Clean the pod cache.
// Notes:
// 1. Cleaning the cache does not modify your Podfile.lock or Podfile files. Therefore, once you run 'pod install' or 'pod update', CocoaPods will re-download the required libraries based on the state of the existing manifest and lock files.
// 2. Typically, clearing the cache is not a routine step and is only necessary when facing specific issues. Under normal circumstances, CocoaPods manages its cache well.
pod cache clean --all

Your code or referenced third-party code reports a symbol conflict with AlivcFFmpeg during integration

Solution:

If a symbol conflict with AlivcFFmpeg occurs, delete the redundant AlivcFFmpeg and keep only one. AlivcFFmpeg is a customized extension of ffmpeg and is crucial for the ApsaraVideo Player SDK. We recommend that you delete the third-party AlivcFFmpeg and keep the one from the ApsaraVideo Player SDK for iOS. Note that this might prevent third-party players from working correctly.

sandBox error

Problem:
Solution:
Set User Script SandBoxing in UserSetting to NO.

Short video SDK integration

If you want to integrate both the ApsaraVideo Player SDK for iOS and the short video SDK into your project, we recommend that you use the All-in-One SDK for iOS for the integration. Otherwise, duplicate class issues may occur and cause compilation to fail.

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

Feature documentation

Basic Features

Advanced Features