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.
Avant de commencer, configurez votre environnement et ajoutez les dépendances requises en suivant le guide Préparation à l'intégration.
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 |
|
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 |
|
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. |
É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;
}
@endimport 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
}
}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
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 :
Créez
AliPlayerController.Configurez
AliPlayerModel(vous pouvez utiliser la méthode VidAuth recommandée ou la source URL pour des tests rapides).Appelez
configure:etattach:.Dans
dealloc, appelezdestroypour 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()
}
}
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.autoPlayest défini surYESpar défaut, ce qui lance automatiquement la lecture une fois la configuration terminée. Vous n'avez pas besoin d'appeler manuellementplay.AliPlayerController.autoLifecycleManagementest défini surYESpar 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), dansviewDidAppearetviewWillDisappear, vous devez appeler manuellementonResumeetonPauserespectivement.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 appelerdestroypour 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.
}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 |
|
|
|
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. |
|
|
|
Scène vidéo longue : Fournit une solution complète pour la lecture de vidéos longues. |
|
|
|
Scène vidéo courte : Fournit une solution complète pour les flux de vidéos courtes avec défilement. |
|
|
|
Scène de streaming en direct : Fournit une solution complète pour la lecture de streaming en direct. |
|
|
|
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 |
|
|
Vidéo courte |
|
|
Streaming en direct |
|
|
Liste de lecture |
|
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 |
|
|
Vidéo courte |
|
|
Streaming en direct |
|
|
Liste de lecture |
|
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];
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
}
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 |
|
|
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. |
|
|
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.