Integrate short-form drama for iOS

1. Integrate the ApsaraVideo Player SDK license.

   For more information, see Integrate a license.

2. Copy the AUIFoundation, AUIShortVideoList, and AUIPlayer.podspec modules into your project.

3. Configure the Podfile.

   Modify the settings according to the relative path of the dependency libraries in your project. After you modify the Podfile, run pod install --repo-update in the same directory as the Podfile to update the third-party dependencies.

   Important

   We recommend that you use the latest version of the Player SDK. For details, see iOS Player SDK release history.

   # Pod Example
   install! 'cocoapods', :deterministic_uuids => false
   source 'https://github.com/CocoaPods/Specs.git'
   platform :ios, '9.0'
   target 'Your ProjectName' do
     # The type of SDK to use.
     # TODO: Replace 'x.x.x' in this line with a specific version number. For more information and version numbers, see the documentation link provided above.
     pod 'AliPlayerSDK_iOS', '~> x.x.x'
     # In-module dependencies (You can customize the version by modifying the AUIPlayer.podspec file.)
     pod "AUIPlayer/AliPlayerSDK_iOS", :path => "../"
     # You can add other SDKs based on your business needs or modify the AliPlayerSDK_iOS version in AUIPlayer.podspec.
     # pod "AUIPlayer/AliVCSDK_Standard", :path => "../"
     # AUIFoundation (required)
     pod "AUIFoundation/All", :path => "../AUIBaseKits/AUIFoundation"
     # Short-form drama list playback component
     pod "AUIPlayer/AUIPlayerKits", :path => "../"
     # You can customize the third-party library version.
     pod 'SDWebImage', '5.18.1'
   end
   post_install do |installer|
     installer.pods_project.build_configurations.each do |config|
         config.build_settings['CLANG_WARN_DOCUMENTATION_COMMENTS'] = 'NO'
         config.build_settings['CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER'] = 'NO'
     end
   end

   Note

   If a third-party library in your project has a version that conflicts with a dependency in the source code, use your project's version.

4. Configure the project.

   If your Swift project uses Objective-C libraries, you must configure a bridging header in the project's Build Settings. This allows Swift to access the Objective-C interfaces in the AUIShortVideoList module.

   • Set the bridging header.

     In your project's Build Settings, set SWIFT_OBJC_BRIDGING_HEADER to the path of your bridging header file. The following is an example path:

     <YourProjectName>/<YourProjectName>-Bridge-Header.h

   • Import the Objective-C interfaces.

     In the bridging header file, import the Objective-C interfaces that you want to expose to Swift. The following is an example:

     #import "AUIShortVideoList.h"

     For more examples and guidance, see the AUIPlayer-Bridge-Header.h file in the AUIShortVideoList module.

5. Build and run.

   After the configuration is complete, build and run the project to verify that the AUIShortVideoList component is integrated correctly.

   Note

   • After the integration is complete, we recommend that you run git commit to record the latest commit ID of the current component. This commit serves as an important reference for tracing future component updates, records the code differences before and after an update, and helps you effectively control integration quality. It also allows you to quickly identify the component version when you seek technical support, which improves support efficiency.

   • For integration issues, see Integration FAQ.

Using AUIShortVideoListViewController

The following examples show two ways to initialize and push AUIShortVideoListViewController for a quick setup:

• Use UINavigationController for navigation.

  Objective-C example

  // Create an array for video information.
  NSArray<AUIShortVideoInfo *> *videoInfoList = [[NSArray alloc] init];
  // Initialize AUIShortVideoListViewController and pass in the video data.
  AUIShortVideoListViewController *vc = [[AUIShortVideoListViewController alloc] initWithData:videoInfoList];
  // Use UINavigationController to push the new view controller.
  [self.navigationController pushViewController:vc animated:YES];

  Swift example

  // Create an array for video information.
  let info = Array<AUIShortVideoInfo>() // Add a data source.
  // Initialize AUIShortVideoListViewController and pass in the video data.
  let vc = AUIShortVideoListViewController(data: info)
  // Use UINavigationController to push the new view controller.
  self.navigationController?.pushViewController(vc, animated: true)

• Use a modal (Modal) transition.

  Objective-C example

  // Create an array for video information.
  NSArray<AUIShortVideoInfo *> *videoInfoList = [[NSArray alloc] init];
  // Initialize AUIShortVideoListViewController and pass in the video data.
  AUIShortVideoListViewController *vc = [[AUIShortVideoListViewController alloc] initWithData:videoInfoList];
  // Set the modal presentation style (optional).
  vc.modalPresentationStyle = UIModalPresentationFullScreen;
  // Present the new view controller modally.
  [self presentViewController:vc animated:YES completion:nil];

  Swift example

  // Create an array for video information.
  let info = Array<AUIShortVideoInfo>() // Add a data source.
  // Initialize AUIShortVideoListViewController and pass in the video data.
  let vc = AUIShortVideoListViewController(data: info)
  // Set the modal presentation style.
  vc.modalPresentationStyle = .fullScreen // Optional. Set the style as needed.
  // Present the new view controller modally.
  self.present(vc, animated: true, completion: nil)

  Note

  If you use a modal transition without a UINavigationController, you may need to adjust the internal navigation logic and implement a custom return path. This ensures the target page can be opened and dismissed correctly in a modal flow.

You can also implement the AUIShortVideoDataProviderDelegate to customize video data loading.

Integrating UINavigationController

Starting with Xcode 11, SceneDelegate was introduced. Before iOS 13, AppDelegate handled both the app and UI lifecycles. In iOS 13 and later, AppDelegate manages only the app lifecycle and new Scene Sessions, while SceneDelegate handles the UI lifecycle. The following are code examples:

• Integrate UINavigationController in an Objective-C project

  AppDelegate.m (iOS 12 and earlier)

  #import "MyViewController.h"
  #import "AlivcPlayerDemoConfig.h"
  #import "AVTheme.h"
  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      [UIApplication sharedApplication].statusBarStyle = UIStatusBarStyleLightContent;
      self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
      // Override point for customization after application launch.
      // Only dark mode is supported.
      AVTheme.supportsAutoMode = NO;
      AVTheme.currentMode = AVThemeModeDark;
      // Create a customizable root view controller.
      MyViewController *mainViewController = [MyViewController new];
      // Use the encapsulated AVNavigationController.
      AVNavigationController *nav =[[AVNavigationController alloc]initWithRootViewController:mainViewController];
      // Use the system's UINavigationController.
  //  UINavigationController *nav = [[UINavigationController alloc]initWithRootViewController:mainViewController];
      [self.window setRootViewController:nav];
      [self.window makeKeyAndVisible];
      return YES;
  }

  SceneDelegate.m (iOS 13 and later)

  #import "MyViewController.h"
  #import "AlivcPlayerDemoConfig.h"
  #import "AVTheme.h"
  - (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
      // Use this method to optionally configure and attach the UIWindow `window` to the provided UIWindowScene `scene`.
      // If using a storyboard, the `window` property will automatically be initialized and attached to the scene.
      // This delegate does not imply the connecting scene or session are new (see `application:configurationForConnectingSceneSession` instead).
      // Override point for customization after application launch.
      [UIApplication sharedApplication].statusBarStyle = UIStatusBarStyleLightContent;
      UIWindowScene *windowScene = (UIWindowScene *)scene;
      self.window = [[UIWindow alloc]initWithWindowScene:scene];
      self.window.frame = windowScene.coordinateSpace.bounds;
      // Only dark mode is supported.
      AVTheme.supportsAutoMode = NO;
      AVTheme.currentMode = AVThemeModeDark;
      // Create a root view controller.
      MyViewController *mainViewController = [MyViewController new];
      AVNavigationController *nav =[[AVNavigationController alloc]initWithRootViewController:mainViewController];
  //    UINavigationController *nav = [[UINavigationController alloc]initWithRootViewController:mainViewController];
      [self.window setRootViewController:nav];
      [self.window makeKeyAndVisible];
  }

• Integrate UINavigationController in a Swift project

  SceneDelegate.swift (iOS 13 and later)

  func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
      UIApplication.shared.statusBarStyle = UIStatusBarStyle.darkContent;
      let windowScene = scene as! UIWindowScene;
      self.window = UIWindow(windowScene: windowScene);
      self.window?.frame = windowScene.coordinateSpace.bounds;
      let myViewController = MyViewController();
      let nav = AVNavigationController(rootViewController: myViewController );
      // Use the system's UINavigationController.
      // let nav = UINavigationController(rootViewController: myViewController );
      self.window?.rootViewController = nav;
      self.window?.makeKeyAndVisible();
      guard let _ = (scene as? UIWindowScene) else { return }
  }

Data structure

The AUIShortVideoList component uses the data structure NSArray<AUIShortVideoInfo *>, where AUIShortVideoInfo is a data class for storing video information. Its data structure is as follows:

Component initialization

To ensure that the AUIShortVideoList component runs correctly, pass the NSArray<AUIShortVideoInfo *> data source when you initialize AUIShortVideoListViewController. The following code provides an example:

// In the current view controller, create an array of video information and initialize the controller.
NSArray<AUIShortVideoInfo *> *videoInfoList = [[NSArray alloc] init];
AUIShortVideoListViewController *vc = [[AUIShortVideoListViewController alloc] initWithData:videoInfoList];
// Use UINavigationController to push the new view controller.
[self.navigationController pushViewController:vc animated:YES];

// In the current view controller, create an array of video information and initialize the controller.
let info = [AUIShortVideoInfo]() // Add a data source.
let vc = AUIShortVideoListViewController(data: info)
// Use UINavigationController to push the new view controller.
self.navigationController?.pushViewController(vc, animated: true)

Instead of passing a data array directly, you can implement the AUIShortVideoDataProviderDelegate protocol to customize data loading:

• Initialize the component through a delegate. We recommend that you implement the data delegate during initialization.

  Objective-C example

  // In the current view controller, initialize the controller and pass in the data provider.
  AUIShortVideoListViewController *videoListVC = [[AUIShortVideoListViewController alloc] initWithDataProvider:self];
  // Use UINavigationController to push the new view controller.
  [self.navigationController pushViewController:videoListVC animated:YES];

  Swift example

  // In the current view controller, initialize the controller and pass in the data provider.
  let videoListVC = AUIShortVideoListViewController(dataProvider: self)
  // Use UINavigationController to push the new view controller.
  self.navigationController?.pushViewController(videoListVC, animated: true)

• Implement the AUIShortVideoDataProviderDelegate protocol to customize data loading and refreshing:

  @protocol AUIShortVideoDataProviderDelegate <NSObject>
  @required
  - (void)loadData:(id _Nullable)controller; // Load data.
  @optional
  - (void)refreshData:(id _Nullable)controller;// Refresh data (optional).
  @end    

After you fetch video data, use the following APIs to update the data list in the ViewController:

Append data

/**
* @brief Appends new video data to the current video list.
*
* @param videoInfoList A new list of video data, which can be null.
*                      If the provided list is not null, its data is appended to the end of the existing video list.
*                      If the provided list is null, the current list is not modified.
*/
- (void)appendVideoInfoList:(NSArray<AUIShortVideoInfo *> * _Nullable)videoInfoList;

Reset data

/**
* @brief Resets the current video list to a new specified list.
*
* @param videoInfoList A new list of video data, which can be null.
*                      This replaces the current video list with the provided list.
*                      If the provided list is null, the current video list is cleared.
*/
- (void)resetVideoInfoList:(NSArray<AUIShortVideoInfo *> * _Nullable)videoInfoList;

You can obtain the NSArray<AUIShortVideoInfo *> data source by using network requests or data transformation, as shown in the following example:

• Network request

  Objective-C example

  // Request additional data. AUIShortVideoListConstants.defaultVideoInfoListURL is the request URL. You can replace it with your own request URL.
  - (void)loadData:(id)controller {
      __weak typeof(self) weakSelf = self;  // Weak reference to self.
      [AUIShortVideoListDataManager requestVideoInfoList:AUIShortVideoListConstants.defaultVideoInfoListURL completed:^(NSArray<AUIShortVideoInfo *> * _Nullable data, NSError * _Nullable error) {
          if (error) {
              __strong typeof(weakSelf) strongSelf = weakSelf; // Strong reference to self.
              [AVToastView show:[NSString stringWithFormat:@"Unable to retrieve short video list, error: %@", error.localizedDescription]
                          view:strongSelf.view
                      position:AVToastViewPositionMid];
              return;
          }
          // Call the appendVideoInfoList: method of the corresponding child view controller.
          if (controller && [controller respondsToSelector:@selector(appendVideoInfoList:)]) {
              [controller appendVideoInfoList:data];
          }
      }];
  }

  Swift example

  // Request additional data. AUIShortVideoListConstants.defaultVideoInfoListURL is the request URL. You can replace it with your own request URL.
  func loadData(_ controller: Any?) {
      weak var weakSelf = self  // Weak reference to self.
      AUIShortVideoListDataManager.requestVideoInfoList(AUIShortVideoListConstants.defaultVideoInfoListURL) { (data: [AUIShortVideoInfo]?, error: Error?) in
          if let error = error {
              guard let strongSelf = weakSelf else { return } // Strong reference to self.
              AVToastView.show("Unable to retrieve short video list, error: \(error.localizedDescription)", view: strongSelf.view, position: .mid)
              return
          }
          if let myController = controller as? AUIShortVideoListViewController {
              // Cast successful, use myController.
              if  myController.responds(to: #selector(myController.appendVideoInfoList(_:))) {
                  myController.appendVideoInfoList(data)
              }
          }
      }
  }

• Data conversion

  Objective-C example

  // Convert the dictionary array to a video information model array.
  NSArray<NSDictionary *> *responseArray = (NSArray<NSDictionary *> *)responseObject;
  NSMutableArray<AUIShortVideoInfo *> *videoInfoArray = [NSMutableArray arrayWithCapacity:responseArray.count];
  for (NSDictionary *dict in responseArray) {
      // Initialize the AUIShortVideoInfo model object and add it to the array.
      AUIShortVideoInfo *videoInfo = [[AUIShortVideoInfo alloc] initWithDict:dict];
      [videoInfoArray addObject:videoInfo];
  }

  Swift example

  let responseArray = responseObject as? [[AnyHashable : Any]]
  var videoInfoArray = [AnyHashable](repeating: 0, count: responseArray?.count ?? 0) as? [AUIShortVideoInfo]
  for dict in responseArray ?? [:] {
      guard let dict = dict as? [AnyHashable : Any] else {
              continue
      }
      // Initialize the AUIShortVideoInfo model object and add it to the array.
      let videoInfo = AUIShortVideoInfo(dict: dict)
      videoInfoArray?.append(videoInfo)
  }

Playback issues

Check your Player SDK license configuration. For more information, see Integrate a license.

Error: "Sandbox: rsync.samba(56557) deny(1) file-read-data"

In Build Settings, set User Script Sandboxing to NO.

Compilation and runtime errors

If your project already contains the same third-party library, adjust the version of that library in the AUIPlayer.podspec file to ensure compatibility and avoid conflicts.

Third-party dependency not found

If you cannot find the third-party dependencies after you modify the PodFile, run pod install --repo-update in the directory that contains the PodFile.

Slow dependency installation

If dependency installation is slow, you can add Alibaba Cloud's Pod repository to your Podfile to speed it up. The following is an example:

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/aliyun/aliyun-specs.git'

Switch player versions

If you do not want to use the player dependency in AUIPlayer.podspec, see Integrate the Player SDK for iOS.

Short-form drama theater

Overview

Integration

Usage

- (void)openShortDramaList {
    AUIShortTheaterViewController *vc = [[AUIShortTheaterViewController alloc] init];
    [self.navigationController pushViewController:vc animated:YES];
}

func openShortDramaList() {
    let vc = AUIShortTheaterViewController()
    navigationController?.pushViewController(vc, animated: true)
}

Fetch data

Short-form drama feeds

Overview

Integration

Usage

- (void)openShortDramaFeeds {
    AUIShortPlaylistFeedsViewController *vc = [[AUIShortPlaylistFeedsViewController alloc] init];
    [self.navigationController pushViewController:vc animated:YES];
}

func openShortDramaFeeds() {
    let vc = AUIShortPlaylistFeedsViewController()
    navigationController?.pushViewController(vc, animated: true)
}

Fetch data

Preloading

By using a sliding window strategy, the component dynamically starts and stops video preloading tasks. The underlying SDK intelligently adjusts task priority based on network conditions to ensure that the current and upcoming videos receive more network resources. This strategy significantly improves startup speed and reduces buffering, providing a smooth playback experience even during rapid scrolling. For more information, see Preloading.

Pre-rendering

The component uses pre-rendering to render the first frame of upcoming videos in the background. This reduces the occurrence of black screens and creates a more seamless playback experience. Starting from V6.16.0, ApsaraVideo Player SDK and Player SDK support a forced pre-rendering feature. For more information, see Pre-rendering.

Multi-instance player pool

This component implements a globally shared player instance pool with a configurable number of instances. It optimizes API calls and thread resource management to minimize thread overhead and reduce CPU and memory usage. This balances performance and user experience. Performance optimizations also reduce expensive operations during scrolling, which cuts down on stutter and makes playback smoother.

PiP automatic episode switching

The global PiPVC and DisplayLayer technologies ensure continuous rendering during episode switches in the small window and prevent interruptions during instance switching to provide a seamless, imperceptible, and uninterrupted experience. This solution is an engineered implementation of the best practice for Small Window Playback (Picture-in-Picture capability).

HTTPDNS

HTTPDNS provides faster and more stable DNS resolution. By replacing traditional DNS, it reduces lookup times and improves video loading speed and stability, which enhances the user's viewing experience. Starting from V6.12.0, ApsaraVideo Player SDK enables HTTPDNS by default. For more information, see HTTPDNS.

Video encryption

Videos in short-form drama scenarios are usually MP4 files that are 1 to 3 minutes long. Starting in V6.8.0, ApsaraVideo Player SDK and Player SDK support MP4 playback with proprietary cryptography, which protects short-form drama content. For more information, see Alibaba Cloud proprietary cryptography.

To play an MP4 video encrypted with proprietary cryptography, the following conditions must be met:

• When you play an MP4 video that is encrypted by using proprietary cryptography, your application must append etavirp_nuyila=1 to the video URL. For example, if the original video URL is https://example.aliyundoc.com/test.mp4, the video URL that you must pass to the player is https://example.aliyundoc.com/test.mp4?etavirp_nuyila=1.

• The UID associated with the app license must match the UID used to encrypt the proprietary MP4.

To verify that a proprietary-encrypted video is correct:

• The metadata should include the AliyunPrivateKeyUri tag.

• The video cannot be played directly with ffplay.

Adaptive H.265 playback

If hardware decoding of an H.265 stream fails, the player automatically falls back to a configured H.264 backup stream. If no backup is configured, the player falls back to software decoding for H.265. For more information, see Adaptive H.265 playback.

Adaptive bitrate streaming

The Player SDK supports multi-bitrate adaptive HLS and DASH video streams. You can call the selectTrack method of the player to switch the playback bitrate, which enables adaptive bitrate switching for video quality. For more information, see adaptive bitrate switching.