Tous les produits
Search
Centre de documentation

ApsaraVideo VOD:Démarrage rapide

Dernière mise à jour :Sep 10, 2026

Ce guide explique comment intégrer rapidement le SDK AliPlayerKit pour iOS. Il couvre l'intégralité du processus, y compris l'initialisation globale, l'intégration de la couche de composants et l'intégration de la couche de scènes.

Remarque

Avant de commencer, configurez votre environnement et ajoutez les dépendances requises en suivant le guide Préparation à l'intégration.

Remarque

La structure claire de ce document le rend idéal pour l'analyse et l'exécution par l'IA. Vous pouvez l'utiliser comme une Skill pour rationaliser votre flux de travail de développement. Nous vous recommandons d'utiliser l'assistance IA pour intégrer AliPlayerKit.

AliPlayerKit propose une API minimaliste qui permet d'intégrer rapidement des fonctionnalités de lecture vidéo avec très peu de code.

Choisir une solution d'intégration

AliPlayerKit repose sur une architecture en couches. Outre l'intégration de la couche de composants, il propose une intégration de la couche de scènes, ce qui vous permet de choisir l'option la mieux adaptée à vos besoins métier :

Solution d'intégration

Module

Description

Cas d'utilisation

Intégration de la couche de composants

PlayerKit

Fournit des composants d'interface utilisateur de lecteur configurables à l'aide du module PlayerKit principal.

Pour les cas d'utilisation nécessitant une interface utilisateur de lecteur personnalisée ou un contrôle précis du comportement de lecture.

Intégration de la couche de scènes

PlayerKitScenes

Propose des solutions complètes pour les scénarios de lecture courants, construites sur la couche de composants.

Implémentez rapidement des scénarios de lecture standard, tels que les vidéos longues, les vidéos courtes et le streaming en direct.

Remarque

Étant donné que la couche de scènes dépend de la couche de composants, vous devez d'abord intégrer la couche de composants.

Initialisation globale

Dans la méthode application:didFinishLaunchingWithOptions: de AppDelegate, appelez [AliPlayerKit setup] pour effectuer l'initialisation globale. Cette méthode ne doit être appelée qu'une seule fois durant tout le cycle de vie de l'application.

#import <AliPlayerKit/AliPlayerKit.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Initialize global settings for AliPlayerKit
    [AliPlayerKit setup];
    return YES;
}

@end
import AliPlayerKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize global settings for AliPlayerKit
        AliPlayerKit.setup()
        return true
    }
}
Remarque

AliPlayerKit propose également d'autres interfaces de configuration globale, telles que le système de journalisation et les politiques de préchargement. Pour plus d'informations, consultez la Référence API.

Option 1 : Intégration de la couche de composants

La couche de composants (module PlayerKit) fournit des composants d'interface utilisateur de lecteur configurables et prêts à l'emploi. Suivez ces étapes pour implémenter la lecture dans chaque vue nécessitant une vidéo.

Étape 1 : Ajouter la vue du lecteur

Dans votre ViewController, créez un AliPlayerView et ajoutez-le à votre hiérarchie de vues :

AliPlayerView *playerView = [[AliPlayerView alloc] initWithFrame:self.view.bounds];
[self.view addSubview:playerView];
let playerView = AliPlayerView(frame: view.bounds)
view.addSubview(playerView)

Vous pouvez placer le AliPlayerView n'importe où dans votre hiérarchie de vues et définir son cadre selon vos besoins. Si vous activez le basculement en plein écran, le composant gère automatiquement les ajustements de la hiérarchie des vues.

Étape 2 : Lier le contrôleur et lancer la lecture

Important

Vous devez appeler configure: avant attach:, sinon la configuration de lecture ne pourra pas être récupérée lors de la liaison de la vue.

Dans votre ViewController, créez le contrôleur, configurez les données et attachez la vue :

  1. Créez AliPlayerController.

  2. Configurez AliPlayerModel (vous pouvez utiliser la méthode VidAuth recommandée ou la source URL pour des tests rapides).

  3. Appelez configure: et attach:.

  4. Dans dealloc, appelez destroy pour libérer les ressources.

#import <AliPlayerKit/AliPlayerKit.h>

@interface VideoPlayerViewController ()
@property (nonatomic, strong) AliPlayerView *playerView;
@property (nonatomic, strong) AliPlayerController *controller;
@end

@implementation VideoPlayerViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // 1. Create the player view
    self.playerView = [[AliPlayerView alloc] initWithFrame:self.view.bounds];
    [self.view addSubview:self.playerView];

    // 2. Create the player controller
    self.controller = [[AliPlayerController alloc] init];

    // 3. Configure the playback data (VidAuth is recommended)
    VideoSource *source = [VideoSource vidAuthSourceWithVid:@"your_video_id"
                                                  playAuth:@"your_playback_credential"];
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
    model.videoTitle = @"Sample Video";

    // 4. Configure the source and attach the view (playback starts automatically after attachment)
    [self.controller configure:model];
    [self.playerView attach:self.controller];
}

- (void)dealloc {
    // Destroy the player to release resources
    [self.controller destroy];
}

@end
import AliPlayerKit

class VideoPlayerViewController: UIViewController {

    private let playerView = AliPlayerView(frame: .zero)
    private let controller = AliPlayerController()

    override func viewDidLoad() {
        super.viewDidLoad()

        // 1. Create the player view
        playerView.frame = view.bounds
        view.addSubview(playerView)

        // 2. Configure the playback data (VidAuth is recommended)
        let source = VideoSource.vidAuthSource(withVid: "your_video_id", playAuth: "your_playback_credential")
        let model = AliPlayerModel(videoSource: source)
        model.videoTitle = "Sample Video"

        // 3. Configure the source and attach the view (playback starts automatically after attachment)
        controller.configure(model)
        playerView.attach(controller)
    }

    deinit {
        // Destroy the player to release resources
        controller.destroy()
    }
}
Remarque

Si vous ne pouvez pas temporairement obtenir l'ID vidéo et l'identifiant de lecture, vous pouvez utiliser une source URL pour un test rapide. Le module de scène fournit des exemples de données intégrés SceneConstants, que vous pouvez également utiliser directement.

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
  • AliPlayerModel.autoPlay est défini sur YES par défaut, ce qui lance automatiquement la lecture une fois la configuration terminée. Vous n'avez pas besoin d'appeler manuellement play.

  • AliPlayerController.autoLifecycleManagement est défini sur YES par défaut, ce qui gère automatiquement la mise en pause et la reprise de la lecture lorsque l'application passe entre le premier plan et l'arrière-plan. Toutefois, pour la navigation au niveau de la page (comme push/pop), dans viewDidAppear et viewWillDisappear, vous devez appeler manuellement onResume et onPause respectivement.

  • configure: obtient en interne une instance de lecteur en utilisant une stratégie de cycle de vie, définit la source de données et prépare la lecture.

  • Dans la méthode dealloc, vous devez appeler destroy pour détruire le contrôleur. Sinon, une fuite de mémoire se produira.

Étape 3 (Facultative) : Gérer le bouton Retour

Si vous devez personnaliser le comportement du bouton Retour du lecteur, utilisez le rappel onBackPressed :

__weak typeof(self) weakSelf = self;
self.playerView.onBackPressed = ^{
    [weakSelf.navigationController popViewControllerAnimated:YES];
};
playerView.onBackPressed = { [weak self] in
    self?.navigationController?.popViewController(animated: true)
}

Ce rappel n'est déclenché que lorsque le lecteur n'est pas en mode plein écran. En mode plein écran, le bouton Retour permet de quitter le plein écran. Si vous ne définissez pas ce rappel, le lecteur tente une action de navigation par défaut (pop ou dismiss) via la chaîne de répondeurs.

Étape 4 (Facultative) : Configuration personnalisée

Pour injecter des configurations SDK personnalisées, telles que la stratégie de mise en tampon et le Referer, avant que le lecteur ne soit prêt, utilisez onPlayerConfigBlock :

model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
    // Executed before `prepare`. You can access the underlying player instance for custom configuration.
    // For example, set the buffering strategy, Referer, or use `setOption`.
};
model.onPlayerConfigBlock = { player in
    // Executed before `prepare`. You can access the underlying player instance for custom configuration.
}
Remarque

La configuration globale est définie une seule fois en utilisant [AliPlayerKit setOnGlobalInitBlock:] avant setup. La configuration de l'instance est déclenchée par model.onPlayerConfigBlock à chaque appel de configure:. Pour plus d'informations, consultez Configurations personnalisées.

Option 2 : Intégration de la couche de scènes

La couche de scènes fournit des solutions de lecture complètes pour des scénarios métier spécifiques, tels que les vidéos longues, les vidéos courtes et le streaming en direct. Basées sur la couche de composants, ces solutions sont prêtes à l'emploi.

Étape 1 : Sélectionner un module de scène

Les modules de scène, situés dans le répertoire PlayerKitScenes, sont importés via des sous-spécifications CocoaPods. Les modules disponibles incluent :

Module de scène

Sous-spécification Pod

Description

SceneCommon

PlayerKitScenes/SceneCommon

Le module commun requis pour toutes les scènes. Il s'agit d'une dépendance de base pour les autres modules de scène.

SceneLongVideo

PlayerKitScenes/SceneLongVideo

Scène vidéo longue : Fournit une solution complète pour la lecture de vidéos longues.

SceneShortVideo

PlayerKitScenes/SceneShortVideo

Scène vidéo courte : Fournit une solution complète pour les flux de vidéos courtes avec défilement.

SceneLive

PlayerKitScenes/SceneLive

Scène de streaming en direct : Fournit une solution complète pour la lecture de streaming en direct.

ScenePlaylist

PlayerKitScenes/ScenePlaylist

Scène de liste de lecture : Fournit une solution complète pour la lecture de listes de lecture vidéo.

Étape 2 : Lancer la page de scène

Après avoir intégré un module de scène, vous pouvez lancer la page de scène correspondante de l'une des deux manières suivantes :

Méthode 1 : Instanciation directe (recommandée)

Chaque module de scène fournit un ViewController indépendant, qui peut être instancié directement et auquel on peut accéder via UINavigationController :

#import "SceneLongVideoViewController.h"

// Navigate to the long-form video scene
SceneLongVideoViewController *vc = [[SceneLongVideoViewController alloc] init];
[self.navigationController pushViewController:vc animated:YES];
// Navigate to the long-form video scene
let vc = SceneLongVideoViewController()
navigationController?.pushViewController(vc, animated: true)

Le ViewController correspondant à chaque scène est le suivant :

Scène

ViewController

Vidéo longue

SceneLongVideoViewController

Vidéo courte

SceneShortVideoViewController

Streaming en direct

SceneLiveViewController

Liste de lecture

ScenePlaylistViewController

Méthode 2 : Routage Schema

Le module de scène prend en charge le démarrage de la scène de lecture correspondante en utilisant le protocole Schema. Le projet de démonstration fournit la classe utilitaire de routage AppSchemaRouter, qui peut découvrir automatiquement et accéder à la scène correspondante en utilisant une URL Schema :

#import "AppSchemaRouter.h"

// Navigate to the long-form video scene via schema
[AppSchemaRouter navigateToSchema:@"playerkit://scenes/longvideo" fromViewController:self];
// Navigate to the long-form video scene via schema
AppSchemaRouter.navigate(toSchema: "playerkit://scenes/longvideo", from: self)

L'adresse schema correspondante à chaque scène est la suivante :

Scène

Schema

Vidéo longue

playerkit://scenes/longvideo

Vidéo courte

playerkit://scenes/shortvideo

Streaming en direct

playerkit://scenes/live

Liste de lecture

playerkit://scenes/playlist

Remarque

ppSchemaRouter est un outil de routage fourni dans le projet de démonstration (module App). Il permet la découverte automatique des modules basée sur le protocole AppModuleProtocol. Les modules de scène utilisent des classes *Module (telles que SceneLongVideoModule) pour enregistrer leurs schemas, titres et priorités. Si vous souhaitez utiliser le routage schema dans votre application, vous pouvez vous référer à cette implémentation ou intégrer votre propre framework de routage.

Implémentation des scènes

Le code source du module de scène fournit des exemples de meilleures pratiques pour l'intégration de la couche de composants. Les sections suivantes décrivent les modèles d'implémentation principaux pour chaque scène.

Vidéo longue

SceneLongVideoViewController illustre le processus d'intégration standard pour la couche de composants :

// Initialize the AliPlayerKit playback components
- (void)setupPlayerKit {
    // 1. Create the player component view
    self.playerView = [[AliPlayerView alloc] initWithFrame:self.view.bounds];
    [self.view addSubview:self.playerView];

    // Optional: Set the back button callback
    __weak typeof(self) weakSelf = self;
    self.playerView.onBackPressed = ^{
        [weakSelf.navigationController popViewControllerAnimated:YES];
    };

    // 2. Create the player component controller
    self.playerController = [[AliPlayerController alloc] init];

    // 3. Configure the player component data
    VideoSource *source = [VideoSource vidAuthSourceWithVid:@"your_video_id" playAuth:@"your_playback_credential"];
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
    model.videoTitle = @"Long Video";

    // 4. Configure the source and attach the controller to the view (playback starts automatically after attachment)
    [self.playerController configure:model];
    [self.playerView attach:self.playerController];
}

Streaming en direct

SceneLiveViewController illustre l'utilisation de la source URL et du type de scénario de streaming en direct :

VideoSource *source = [VideoSource urlSourceWithUrl:liveUrl];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.videoTitle = @"Live Stream";
model.sceneType = SceneTypeLive;  // Set the scene type to live

[self.playerController configure:model];
[self.playerView attach:self.playerController];
Remarque

SceneType affecte la configuration de la visibilité des emplacements et le comportement de l'interface utilisateur. Par exemple, dans un scénario de streaming en direct, les éléments VOD tels que la barre de progression sont automatiquement masqués. Pour plus d'informations, consultez Type de scène.

Liste de lecture

ScenePlaylistViewController illustre une utilisation avancée de SingletonLifecycleStrategy et de PlayerNotificationDelegate pour implémenter la lecture continue :

// Use the singleton lifecycle strategy to reuse the player instance
self.lifecycleStrategy = [SingletonLifecycleStrategy sharedInstance];
self.currentController = [[AliPlayerController alloc] initWithLifecycleStrategy:self.lifecycleStrategy];

// Register a notification for playback completion to trigger continuous playback
[self.currentController addNotificationDelegate:self];

// PlayerNotificationDelegate callback
- (void)playerDidCompletion {
    [self playNextVideo];  // The current video finished playing; play the next one automatically
}
Remarque

Pour les scénarios de lecture en liste, vous pouvez utiliser initWithLifecycleStrategy: pour spécifier une stratégie de cycle de vie et réutiliser les instances de lecteur afin d'améliorer les performances. Pour plus d'informations, consultez Stratégie de cycle de vie du lecteur.

Exemples et extensions

En suivant ces étapes, vous avez intégré AliPlayerKit et activé la lecture vidéo.

Pour plus d'exemples, reportez-vous aux répertoires suivants :

Module

Description

PlayerKitUsages

Fournit des exemples d'utilisation pour les API courantes, y compris le système de journalisation, le système d'emplacements, le système de notification, le système de politique, la stratégie de cycle de vie, le préchargement, les sources vidéo et la localisation.

PlayerKitScenes

Fournit des solutions pour des scénarios de lecture typiques, tels que les vidéos longues, les vidéos courtes, le streaming en direct et les listes de lecture.

Le format de route Schema pour chaque exemple d'utilisation est playerkit://usages/<module_name>. Vous pouvez accéder directement à ces exemples depuis la page d'accueil du projet de démonstration.