AliPlayerKit iOS Custom Configuration - ApsaraVideo VOD: Central de Documentação do Alibaba Cloud

Conceitos principais

O que é configuração personalizada?

O AliPlayerKit atua como um wrapper de alto nível para o AliPlayer SDK subjacente e traz configurações integradas seguindo as melhores práticas. No entanto, o SDK subjacente oferece um conjunto mais amplo de recursos, como estratégias personalizadas de buffer, proteção contra hotlink via Referer e injeção de cabeçalhos HTTP. Nem todas essas funcionalidades estão disponíveis diretamente no AliPlayerKit.

O mecanismo de configuração personalizada fornece dois pontos de entrada por callback, permitindo acessar os objetos subjacentes em momentos-chave e chamar suas APIs nativas diretamente:

Nível	API	Momento	Cenários típicos
Configuração global	`+setOnGlobalInitBlock:`	Após a conclusão da inicialização interna em `+setup` (apenas uma vez)	Comportamentos globais, como nível de log e multiplexação HTTP/2
Configuração do player	`onPlayerConfigBlock`	Antes de `prepare` sempre que `configure:` for chamado	Comportamentos específicos da instância, como estratégia de buffer, Referer e cabeçalhos HTTP

Sistema de configuração de três níveis

O sistema de configuração do AliPlayerKit possui três níveis:

┌─────────────────────────────────────────────────────────┐
│              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          │
└─────────────────────────────────────────────────────────┘

Configuração global

Casos de uso

Defina opções globais, como o nível de log global
Ative a multiplexação HTTP/2
Configure uma estratégia global de resolução DNS
Implemente outros comportamentos globais que devem entrar em vigor antes da criação de qualquer instância do player

Funcionamento

Registre um bloco de callback usando +[AliPlayerKit setOnGlobalInitBlock:].
O callback é acionado uma única vez após +setup concluir sua inicialização interna.
Após a execução, o sistema define o bloco como nil, impedindo novos acionamentos.
Nesse momento, o SDK subjacente está pronto e você pode chamar as APIs globais com segurança.

Uso

Em application:didFinishLaunchingWithOptions:, registre o callback antes de chamar +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;
}

Sequência de configuração

application:didFinishLaunchingWithOptions:
    │
    ├── [AliPlayerKit setOnGlobalInitBlock:block]   ← Register callback
    │
    └── [AliPlayerKit setup]
            │
            ├── [GlobalManager setup]    ← Initialize underlying SDK
            │
            ├── sInitialized = YES
            │
            └── block()                  ← Trigger global config callback (once only)

Observações de uso

Ponto importante	Descrição
Ordem de chamada	Chame `setOnGlobalInitBlock:` antes de `+setup`
Contagem de execuções	A configuração global executa apenas uma vez, e `+setup` usa internamente `dispatch_once` para proteção.
Limpeza com nil	Passe `nil` para cancele um callback registrado.
Idempotência	`+setup` executa apenas uma vez mesmo com múltiplas chamadas, e o callback não é acionado após a primeira execução.

Configuração do player

Casos de uso

Personalize a estratégia de buffer (por exemplo, maxBufferDuration e highBufferDuration).
Defina a proteção contra hotlink via Referer.
Configure cabeçalhos HTTP.
Defina opções no nível da instância.
Acesse outras interfaces do player não expostas diretamente pelo AliPlayerKit.

Funcionamento

Defina um bloco de callback na propriedade AliPlayerModel.onPlayerConfigBlock.
O callback é acionado sempre que [controller configure:model] for chamado.
A execução ocorre após setDataSource: e antes de prepare.
O parâmetro do callback é a instância do player subjacente, que está em conformidade com o protocolo MediaPlayer.

Uso

Ao construir AliPlayerModel, defina 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];

Sequência de configuração

[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 playback

Observações de uso

Ponto importante	Descrição
Frequência de acionamento	Acionado sempre que `configure:` é chamado, sendo adequado para cenários de configuração dinâmica.
Momento de execução	O melhor momento para configuração personalizada é após `setDataSource:` e antes de `prepare`.
Parâmetro do callback	A instância `id<MediaPlayer>` permite chamar todas as interfaces do SDK subjacente.
Configuração opcional	`onPlayerConfigBlock` é opcional e não afeta a reprodução normal.
Evite assincronismo	Não realize operações demoradas ou assíncronas dentro do callback.

Itens de configuração integrados

Configuração global do AliPlayerKit

Use os métodos da classe AliPlayerKit para definir diretamente as opções de configuração integradas:

Parâmetro	Método	Descrição
Inicialização	`+setup`	Inicializa o SDK. `dispatch_once` garante idempotência.
Status de inicialização	`+isInitialized`	Verifica se o SDK foi inicializado.
Callback de configuração global	`+setOnGlobalInitBlock:`	Registra um callback de configuração personalizada executado após a inicialização global.
Modo de depuração	`+setDebugModeEnabled:` / `+isDebugModeEnabled`	Ativa/desativa o modo de depuração (Padrão: `NO`)
Painel de logs	`+setLogPanelEnabled:` / `+isLogPanelEnabled`	Define se o painel de logs deve ser exibido na visualização do player. O valor padrão é `NO`.
Nível de log	`+setLogLevel:` / `+logLevel`	Nível de saída de log do SDK (padrão: `LogLevelInfo`)
Log no console	`+enableConsoleLog:` / `+isConsoleLogEnabled`	Define se os logs devem ser enviados ao console (Padrão: `YES`)
Fábrica de players	`+setPlayerFactory:` / `+playerFactory`	Personaliza a fábrica de criação de players. Passe `nil` para restaurar o padrão.
Pré-carregador	`+setPreloader:` / `+preloader`	Personaliza o pré-carregador ou passe `nil` para restaurar o padrão.
Limpar caches	`+clearCaches`	Limpa o cache local de mídia do player (deve ser chamado após `setup`)
Definição de idioma	`+setLanguageCode:`	Especifique manualmente um código de idioma (`zh-Hans` / `en`)
Localização	`+setLocaleProvider:`	Injeta um provedor de localização personalizado.
Idioma do sistema	`+resetLocaleToSystemLanguage`	Redefine a localidade para seguir o idioma preferido do sistema.
Idioma atual	`+currentLanguageCode`	Obtém o código de idioma ativo no momento.
Informações de versão	`+getPlayerKitVersion` / `+getSdkVersion`	Obtém o número da versão do AliPlayerKit ou do SDK subjacente.

Configuração do player AliPlayerModel

Itens de configuração no nível da instância definidos pela propriedade AliPlayerModel:

Propriedade	Tipo	Padrão	Descrição
`videoSource`	`VideoSource *`	—	Obrigatório. A fonte de dados de vídeo (`readonly`, definido via `initWithVideoSource:`)
`sceneType`	`SceneType`	`SceneTypeVOD`	O cenário de reprodução, que afeta slots de UI e comportamento de gestos.
`coverUrl`	`NSString *`	`nil`	A URL da imagem de capa do vídeo.
`videoTitle`	`NSString *`	`nil`	O título exibido na barra superior.
`autoPlay`	`BOOL`	`YES`	Define se a reprodução deve iniciar automaticamente após a configuração.
`traceId`	`NSString *`	`nil`	Um identificador exclusivo da sua aplicação para monitoramento da qualidade de reprodução.
`startTime`	`NSInteger`	`0`	A posição inicial para reprodução em milissegundos. Valores negativos são corrigidos para 0.
`hardwareDecode`	`BOOL`	`YES`	Define se a decodificação por hardware deve ser ativada.
`allowScreenSleep`	`BOOL`	`NO`	Define se a tela pode entrar em suspensão durante a reprodução.
`disableScreenshot`	`BOOL`	`NO`	Propriedade específica do iOS para desativar capturas de tela e gravação de tela.
`onPlayerConfigBlock`	`void (^)(id<MediaPlayer>)`	`nil`	O callback de configuração personalizada no nível da instância.

Configuração de tempo de execução do AliPlayerController

Configurações ajustadas dinamicamente em tempo de execução pelo AliPlayerController:

Método / propriedade	Tipo	Descrição
`-setRate:`	`float`	Define a velocidade de reprodução. `1.0` é normal, `0.5` é meia velocidade e `2.0` é velocidade dupla.
`-setLoop:`	`BOOL`	Ativa ou desativa a reprodução em loop.
`-setMuted:`	`BOOL`	Ativa ou desativa o som mudo.
`-setMirrorMode:`	`MirrorMode`	Modo espelho (`None` / `Horizontal` / `Vertical`)
`-setScaleMode:`	`ScaleMode`	Modo de escala (`FitXY` / `FitCenter` / `CenterCrop`)
`-setRotateMode:`	`RotateMode`	Ângulo de rotação (`0` / `90` / `180` / `270` graus)
`-setControlsVisible:`	`BOOL`	Mostra ou oculta a barra de controles.
`controlsVisibilityLocked`	`BOOL`	Bloqueio de visibilidade da barra de controles (se definido como `YES`, `setControlsVisible:NO` é ignorado)
`-setFullscreen:`	`BOOL`	Entra ou sai do modo tela cheia. A transição é animada por padrão.
`-setFullscreen:animated:`	`BOOL, BOOL`	Entra ou sai do modo tela cheia e permite controlar a animação.
`-selectTrack:`	`TrackQuality *`	Alterna a qualidade da faixa.
`-snapshot`	—	Captura um snapshot do quadro de vídeo atual.
`-toggle`	—	Alterna entre os estados de reprodução e pausa.
`-replay`	—	Reinicia a reprodução desde o início.
`-stop`	—	Interrompe a reprodução.
`autoLifecycleManagement`	`BOOL`	Pausa e retomada automáticas em primeiro plano/segundo plano (Padrão: `YES`)

Prioridade de configuração

Regras de prioridade

Se o mesmo item for configurado em vários níveis, as definições serão aplicadas na seguinte ordem de precedência:

Player configuration (onPlayerConfigBlock) > AliPlayerModel properties > Global configuration > SDK default values

Escopo da configuração

Nível	Escopo	Ciclo de vida
Configuração global	Todas as instâncias do player	Nível da aplicação (executa uma vez)
Propriedades do modelo	Uma única instância do player	Única chamada de `configure:`
Callback de configuração do player	Uma única instância do player	Acionado sempre que `configure:` é executado
Métodos do controller	Uma única instância do player	Entra em vigor dinamicamente em tempo de execução

Exemplo de configuração

Exemplo de código

// ===== 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];
}

Nota

Chame configurações de log como setLogLevel: e enableConsoleLog: após setup, pois operam na instância singleton LogHub.

Referência rápida de API

API de configuração global

Método	Descrição
`+[AliPlayerKit setOnGlobalInitBlock:]`	Registra um callback de configuração global. Passe `nil` para cancele o registro.
`+[AliPlayerKit setup]`	Aciona a inicialização e executa o callback.

API de configuração do player

Classe	Propriedade	Descrição
`AliPlayerModel`	`onPlayerConfigBlock`	Callback de configuração no nível da instância (`void (^)(id<MediaPlayer>)`)

Arquivos relacionados

Arquivo	Descrição
`PlayerKit/Source/AliPlayerKit.h`	API de configuração global (typedef `OnGlobalInitBlock`)
`PlayerKit/Source/AliPlayerModel.h`	Ponto de entrada da configuração do player (`onPlayerConfigBlock`)
`PlayerKit/Source/AliPlayerController.h`	Define métodos para configuração em tempo de execução.
`PlayerKit/Source/Player/MediaPlayer.h`	Define o protocolo para o player subjacente, que é o tipo do parâmetro de callback.

Para obter a lista completa de APIs, consulte API Reference.

Perguntas frequentes

Ordem de execução da configuração

A configuração global executa uma vez na inicialização da aplicação (em +setup), enquanto a configuração do player executa durante cada chamada de configure: antes de prepare. Uma não interfere na outra.

Comportamento padrão

O AliPlayerKit inclui configurações integradas baseadas em melhores práticas, adequadas para a maioria dos casos de uso sem exigir configuração personalizada.

Operações assíncronas em callbacks

Não recomendado. Os callbacks são executados sincronamente, o que significa que o player não continuará a executar prepare até que o callback seja concluído. Se você realizar uma operação demorada no callback, isso bloqueará o processo de inicialização do player.

Alteração da fonte de vídeo em callbacks

Não recomendado. A fonte de vídeo já foi definida usando setDataSource: antes do callback. Modificá-la dentro do callback pode causar comportamento inesperado. Use o callback de configuração do player apenas para definir parâmetros de reprodução, como estratégia de buffer e Referer.

Chamada de setOnGlobalInitBlock: após setup

Não terá efeito. O método +setup usa dispatch_once para garantir que seja executado apenas uma vez. Se um Block for definido após a chamada do método +setup, esse Block nunca será acionado.

Momento da configuração de log

Chame setLogLevel: e enableConsoleLog: após +setup, pois operam diretamente no singleton LogHub. No entanto, defina setOnGlobalInitBlock: antes de +setup.