La configuration personnalisée est un mécanisme d'extension d'AliPlayerKit. AliPlayerKit intègre des configurations fondées sur les meilleures pratiques, offrant une expérience de haute qualité dans la plupart des scénarios sans configuration supplémentaire. Lorsque vous avez besoin de fonctionnalités du lecteur non exposées directement par l'interface AliPlayerKit, utilisez le mécanisme de configuration personnalisée pour appeler directement les API du SDK AliPlayer sous-jacent.
Concepts clés
Qu'est-ce que la configuration personnalisée ?
AliPlayerKit est un wrapper de haut niveau pour le SDK AliPlayer sous-jacent et intègre des configurations fondées sur les meilleures pratiques. Toutefois, le SDK sous-jacent offre un éventail plus large de fonctionnalités, telles que des stratégies de mise en mémoire tampon personnalisées, la protection contre le hotlinking par Referer et l'injection d'en-têtes HTTP. Toutes ces fonctionnalités ne sont pas exposées directement par AliPlayerKit.
Le mécanisme de configuration personnalisée fournit deux points d'entrée de rappel. Ils vous permettent d'accéder aux objets sous-jacents à des moments clés et d'appeler directement leurs API natives :
|
Niveau |
API |
Moment |
Scénarios typiques |
|
Configuration globale |
|
Après la finalisation de l'initialisation interne dans |
Comportements globaux, tels que le niveau de journalisation et le multiplexage HTTP/2 |
|
Configuration du lecteur |
|
Avant |
Comportements spécifiques à l'instance, tels que la stratégie de mise en mémoire tampon, le Referer et les en-têtes HTTP |
Système de configuration à trois niveaux
Le système de configuration d'AliPlayerKit comporte trois niveaux :
┌─────────────────────────────────────────────────────────┐
│ 1. Global Configuration (OnGlobalInitBlock) │
│ Executes once at app launch, affecting all player instances │
├─────────────────────────────────────────────────────────┤
│ 2. Model Configuration (AliPlayerModel) │
│ Sets playback parameters via properties each time configure: is called │
├─────────────────────────────────────────────────────────┤
│ 3. Player Configuration (onPlayerConfigBlock) │
│ Provides a callback to the underlying player before prepare each time configure: is called │
└─────────────────────────────────────────────────────────┘Configuration globale
Cas d'utilisation
Définir des options globales, telles que le niveau de journalisation global
Activer le multiplexage HTTP/2
Configurer une stratégie de résolution DNS globale
Implémenter d'autres comportements globaux qui doivent prendre effet avant la création de toute instance de lecteur
Fonctionnement
Enregistrez un bloc de rappel en utilisant
+[AliPlayerKit setOnGlobalInitBlock:].Le rappel se déclenche une fois après la finalisation de l'initialisation interne par
+setup.Après l'exécution, le système définit le bloc sur
nilet il ne se déclenchera plus.À ce stade, le SDK sous-jacent est prêt et vous pouvez appeler les API globales en toute sécurité.
Utilisation
Dans application:didFinishLaunchingWithOptions:, enregistrez le rappel avant d'appeler +setup :
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// 1. Register the global custom configuration callback.
// This must be called before setup.
[AliPlayerKit setOnGlobalInitBlock:^{
// Example: Enable HTTP/2 multiplexing.
[AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];
// Example: Set the global log level.
// [AliPlayerFactory setLogLevel:AF_LOG_LEVEL_INFO];
}];
// 2. Initialize the SDK. This triggers the callback registered above
// after internal initialization is complete.
[AliPlayerKit setup];
return YES;
}Séquence de configuration
application:didFinishLaunchingWithOptions:
│
├── [AliPlayerKit setOnGlobalInitBlock:block] ← Register callback
│
└── [AliPlayerKit setup]
│
├── [GlobalManager setup] ← Initialize underlying SDK
│
├── sInitialized = YES
│
└── block() ← Trigger global config callback (once only)Remarques sur l'utilisation
|
Point clé |
Description |
|
Ordre d'appel |
|
|
Nombre d'exécutions |
La configuration globale n'est exécutée qu'une seule fois. |
|
Effacer avec nil |
Passez |
|
Idempotence |
|
Configuration du lecteur
Cas d'utilisation
Personnaliser la stratégie de mise en mémoire tampon (par exemple,
maxBufferDurationethighBufferDuration).Définir la protection contre le hotlinking par Referer.
Configurer les en-têtes HTTP.
Définir des options au niveau de l'instance.
Accéder à d'autres interfaces du lecteur non exposées directement par AliPlayerKit.
Fonctionnement
Définissez un bloc de rappel sur la propriété
AliPlayerModel.onPlayerConfigBlock.Le rappel se déclenche à chaque appel de
[controller configure:model].Le rappel s'exécute après
setDataSource:et avantprepare.Le paramètre du rappel est l'instance du lecteur sous-jacent, conforme au protocole MediaPlayer.
Utilisation
Lors de la construction de AliPlayerModel, définissez onPlayerConfigBlock :
VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
// Set the instance-level custom configuration callback
model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
// Example 1: Customize the buffering strategy
AVPConfig *config = [player getConfig];
config.maxBufferDuration = 50000; // Max buffer duration: 50s
config.highBufferDuration = 3000; // High watermark: 3s
config.startBufferDuration = 500; // Start buffer duration: 500ms
[player setConfig:config];
// Example 2: Set Referer hotlink protection
AVPConfig *refConfig = [player getConfig];
refConfig.referer = @"https://your-domain.com";
[player setConfig:refConfig];
// Example 3: Set an instance-level option
// [player setOption:key value:value];
};
// Configure and play the video
[controller configure:model];Séquence de configuration
[controller configure:model]
│
├── lifecycleStrategy.acquire() ← Get player instance
│
├── [mediaPlayer setDataSource:model] ← Configure video source
│
├── model.onPlayerConfigBlock(mediaPlayer) ← Trigger player config callback
│
├── [strategyManager start/reset] ← Start strategy system
│
└── [mediaPlayer prepare] ← Start preparing for playbackRemarques sur l'utilisation
|
Point clé |
Description |
|
Fréquence de déclenchement |
Se déclenche à chaque appel de |
|
Moment d'exécution |
Le meilleur moment pour la configuration personnalisée se situe après |
|
Paramètre du rappel |
L'instance |
|
Configuration facultative |
|
|
Éviter l'asynchronisme |
Évitez les opérations longues ou asynchrones dans le rappel. |
Éléments de configuration intégrés
Configuration globale AliPlayerKit
Utilisez les méthodes de la classe AliPlayerKit pour définir directement les options de configuration intégrées :
|
Paramètre |
Méthode |
Description |
|
Initialisation |
|
Initialise le SDK. |
|
Statut d'initialisation |
|
Vérifie si le SDK a été initialisé. |
|
Rappel de configuration globale |
|
Enregistre un rappel de configuration personnalisé qui s'exécute après l'initialisation globale. |
|
Mode débogage |
|
Active ou désactive le mode débogage (Par défaut : |
|
Panneau de journaux |
|
Indique s'il faut afficher le panneau de journaux dans la vue du lecteur. La valeur par défaut est |
|
Niveau de journalisation |
|
Niveau de sortie des journaux du SDK (par défaut : |
|
Journal de la console |
|
Indique s'il faut envoyer les journaux vers la console (Par défaut : |
|
Usine de lecteurs |
|
Personnalisez l'usine de création de lecteurs. Passez |
|
Préchargeur |
|
Personnalisez le préchargeur, ou passez |
|
Effacer les caches |
|
Efface le cache multimédia local du lecteur (doit être appelé après |
|
Paramètre de langue |
|
Spécifiez manuellement un code de langue ( |
|
Localisation |
|
Injecte un fournisseur de localisation personnalisé. |
|
Langue du système |
|
Réinitialise la locale pour suivre la langue préférée du système. |
|
Langue actuelle |
|
Obtient le code de langue actuellement actif. |
|
Informations de version |
|
Obtient le numéro de version d'AliPlayerKit ou du SDK sous-jacent. |
Configuration du lecteur AliPlayerModel
Éléments de configuration au niveau de l'instance définis par la propriété AliPlayerModel :
|
Propriété |
Type |
Valeur par défaut |
Description |
|
|
|
— |
Obligatoire. Source de données vidéo ( |
|
|
|
|
Scénario de lecture, qui affecte les emplacements d'interface utilisateur et le comportement des gestes. |
|
|
|
|
URL de l'image de couverture de la vidéo. |
|
|
|
|
Titre affiché dans la barre supérieure. |
|
|
|
|
Indique s'il faut démarrer la lecture automatiquement après la configuration. |
|
|
|
|
Identifiant unique de votre application pour la surveillance de la qualité de lecture. |
|
|
|
|
Position de départ de la lecture en millisecondes. Les valeurs négatives sont corrigées à 0. |
|
|
|
|
Indique s'il faut activer le décodage matériel. |
|
|
|
|
Indique s'il faut autoriser la mise en veille de l'écran pendant la lecture. |
|
|
|
|
Propriété spécifique à iOS pour désactiver les captures d'écran et l'enregistrement d'écran. |
|
|
|
|
Rappel de configuration personnalisée au niveau de l'instance. |
Configuration d'exécution AliPlayerController
Configurations ajustées dynamiquement au moment de l'exécution par AliPlayerController :
|
Méthode / propriété |
Type |
Description |
|
|
|
Définit la vitesse de lecture. |
|
|
|
Active ou désactive la lecture en boucle. |
|
|
|
Active ou désactive le mode muet. |
|
|
|
Mode miroir ( |
|
|
|
Mode de mise à l'échelle ( |
|
|
|
Angle de rotation ( |
|
|
|
Affiche ou masque la barre de contrôle. |
|
|
|
Verrouillage de la visibilité de la barre de contrôle (si défini sur |
|
|
|
Entre ou quitte le mode plein écran. La transition est animée par défaut. |
|
|
|
Entre ou quitte le mode plein écran et vous permet de contrôler l'animation. |
|
|
|
Change la qualité de la piste. |
|
|
— |
Capture l'image vidéo actuelle. |
|
|
— |
Bascule entre les états de lecture et de pause. |
|
|
— |
Redémarre la lecture depuis le début. |
|
|
— |
Arrête la lecture. |
|
|
|
Gestion automatique de la pause et de la reprise en arrière-plan/premier plan (Par défaut : |
Priorité de configuration
Règles de priorité
Si le même élément est configuré à plusieurs niveaux, les paramètres sont appliqués selon l'ordre de priorité suivant :
Player configuration (onPlayerConfigBlock) > AliPlayerModel properties > Global configuration > SDK default valuesPortée de la configuration
|
Niveau |
Portée |
Cycle de vie |
|
Configuration globale |
Toutes les instances du lecteur |
Niveau application (s'exécute une fois) |
|
Propriétés du modèle |
Une seule instance du lecteur |
Appel unique de |
|
Rappel de configuration du lecteur |
Une seule instance du lecteur |
Se déclenche à chaque exécution de |
|
Méthodes du contrôleur |
Une seule instance du lecteur |
Prend effet dynamiquement au moment de l'exécution |
Exemple de configuration
Exemple de code
// ===== Global configuration (in AppDelegate, once only) =====
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Global custom configuration
[AliPlayerKit setOnGlobalInitBlock:^{
// Enable HTTP/2 multiplexing
[AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];
}];
// Initialize
[AliPlayerKit setup];
// Global built-in configuration (must be called after setup)
[AliPlayerKit setLogLevel:LogLevelWarn];
[AliPlayerKit enableConsoleLog:YES];
return YES;
}
// ===== Player configuration (in the player view controller, for each playback) =====
- (void)startPlayback {
VideoSource *source = [VideoSource urlSourceWithUrl:videoUrl];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
// Model property configuration
model.sceneType = SceneTypeVOD;
model.videoTitle = @"Awesome Video";
model.coverUrl = coverImageUrl;
model.autoPlay = YES;
model.hardwareDecode = YES;
model.startTime = resumePosition; // Resume from last position
// Instance-level custom configuration (for the underlying SDK)
model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
AVPConfig *config = [player getConfig];
config.maxBufferDuration = 50000;
config.highBufferDuration = 3000;
config.startBufferDuration = 500;
config.referer = @"https://your-domain.com";
[player setConfig:config];
};
[_controller configure:model];
}Les configurations de journalisation telles que setLogLevel: et enableConsoleLog: doivent être appelées après setup car elles opèrent sur l'instance singleton LogHub.
Référence rapide des API
API de configuration globale
|
Méthode |
Description |
|
|
Enregistre un rappel de configuration globale. Passez |
|
|
Déclenche l'initialisation et exécute le rappel. |
API de configuration du lecteur
|
Classe |
Propriété |
Description |
|
|
|
Rappel de configuration au niveau de l'instance ( |
Fichiers connexes
|
Fichier |
Description |
|
|
API de configuration globale (typedef |
|
|
Point d'entrée de configuration du lecteur ( |
|
|
Définit les méthodes pour la configuration au moment de l'exécution. |
|
|
Définit le protocole pour le lecteur sous-jacent, qui est le type du paramètre du rappel. |
Pour une liste complète des API, consultez la Référence API.
FAQ
Ordre d'exécution de la configuration
La configuration globale s'exécute une fois au démarrage de l'application (dans +setup), et la configuration du lecteur s'exécute lors de chaque appel de configure: avant prepare. Les deux ne s'interfèrent pas mutuellement.
Comportement par défaut
AliPlayerKit intègre des configurations fondées sur les meilleures pratiques, ce qui le rend adapté à la plupart des cas d'utilisation sans nécessiter de configuration personnalisée.
Opérations asynchrones dans les rappels
Cela n'est pas recommandé. Les rappels s'exécutent de manière synchrone, ce qui signifie que le lecteur n'exécutera pas prepare tant que le rappel n'est pas terminé. Si vous effectuez une opération longue dans le rappel, cela bloquera le processus de démarrage du lecteur.
Modification de la source vidéo dans les rappels
Cela n'est pas recommandé. La source vidéo est déjà définie via setDataSource: avant le rappel. La modifier dans le rappel peut entraîner un comportement inattendu. Utilisez le rappel de configuration du lecteur uniquement pour définir des paramètres de lecture, tels que la stratégie de mise en mémoire tampon et le Referer.
Appel de setOnGlobalInitBlock: après setup
Cela n'aura aucun effet. La méthode +setup utilise dispatch_once pour garantir qu'elle ne s'exécute qu'une seule fois. Si vous définissez un bloc après l'appel de la méthode +setup, le bloc ne se déclenchera jamais.
Moment de la configuration des journaux
setLogLevel: et enableConsoleLog: doivent être appelés après +setup, car ils opèrent directement sur le singleton LogHub. Cependant, setOnGlobalInitBlock: doit être défini avant +setup.