Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Guia de início rápido

Última atualização: Sep 11, 2026

Este guia descreve como integrar rapidamente o SDK do AliPlayerKit para iOS. Ele aborda todo o processo, incluindo inicialização global, integração da camada de componentes e integração da camada de cenas.

Nota

Antes de começar, configure seu ambiente e adicione as dependências necessárias seguindo o guia Integration Preparation.

Nota

A estrutura clara deste documento facilita a análise e a execução por IA. Use-o como uma Skill para otimizar seu fluxo de trabalho de desenvolvimento. Recomendamos usar assistência de IA para integrar o AliPlayerKit.

O AliPlayerKit possui uma API minimalista que permite integrar recursos de reprodução de vídeo rapidamente e com pouca codificação.

Escolha uma solução de integração

O AliPlayerKit utiliza uma arquitetura em camadas. Além da integração na camada de componentes, ele oferece integração na camada de cenas, permitindo escolher a opção mais adequada às necessidades do seu negócio:

Solução de integração

Módulo

Descrição

Casos de uso

Integração da camada de componentes

PlayerKit

Fornece componentes de UI do player configuráveis usando o módulo principal PlayerKit.

Indicado para casos de uso que exigem uma UI de player personalizada ou controle refinado sobre o comportamento de reprodução.

Integração da camada de cenas

PlayerKitScenes

Oferece soluções completas para cenários comuns de reprodução, construídas sobre a camada de componentes.

Ideal para implementar rapidamente cenários padrão de reprodução, como vídeos longos, vídeos curtos e transmissões ao vivo.

Nota

Como a camada de cenas depende da camada de componentes, integre primeiro a camada de componentes.

Inicialização global

No método application:didFinishLaunchingWithOptions: do AppDelegate, chame [AliPlayerKit setup] para executar a inicialização global. Chame este método apenas uma vez durante todo o ciclo de vida da aplicação.

#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
    }
}
Nota

O AliPlayerKit também fornece outras interfaces de configuração global, como o sistema de logs e políticas de pré-carregamento. Para obter mais informações, consulte API Reference.

Opção 1: Integração da camada de componentes

A camada de componentes (módulo PlayerKit) oferece componentes de UI do player prontos para uso e configuráveis. Siga estas etapas para implementar a reprodução em cada view que necessite de vídeo.

Etapa 1: Adicionar a view do player

No seu ViewController, crie uma AliPlayerView e adicione-a à sua hierarquia de views:

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

Posicione a AliPlayerView em qualquer lugar da hierarquia de views e defina seu frame conforme necessário. Se você ativar a alternância para tela cheia, o componente ajustará automaticamente a hierarquia de views.

Etapa 2: Vincular o controller e reproduzir

Importante

Chame configure: antes de attach:. Caso contrário, a configuração de reprodução não será recuperada durante a vinculação da view.

No seu ViewController, crie o controller, configure os dados e vincule a view:

  1. Crie o AliPlayerController.

  2. Configure o AliPlayerModel (use o método recomendado VidAuth ou a source URL para testes rápidos).

  3. Chame configure: e attach:.

  4. Em dealloc, chame destroy para liberar recursos.

#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()
    }
}
Nota

Caso não seja possível obter temporariamente o ID do vídeo e a credencial de reprodução, utilize uma source URL para um teste rápido. O módulo de cenas fornece dados de amostra integrados no SceneConstants, que também podem ser usados diretamente.

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
  • Por padrão, AliPlayerModel.autoPlay é definido como YES, iniciando a reprodução automaticamente após a conclusão da configuração. Não é necessário chamar play manualmente.

  • A propriedade AliPlayerController.autoLifecycleManagement vem definida como YES por padrão, gerenciando automaticamente a pausa e a retomada da reprodução quando a aplicação alterna entre primeiro plano e segundo plano. No entanto, para navegação no nível da página (como push/pop), chame manualmente onResume em viewDidAppear e onPause em viewWillDisappear.

  • O método configure: obtém internamente uma instância do player usando uma estratégia de ciclo de vida, define a source de dados e prepara a reprodução.

  • No método dealloc, chame destroy para destruir o controller. Caso contrário, ocorrerá um vazamento de memória.

Etapa 3 (Opcional): Tratar o botão Voltar

Para personalizar o comportamento do botão Voltar do player, utilize o callback onBackPressed:

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

Esse callback é acionado apenas quando o player não está em modo de tela cheia. Nesse modo, o botão Voltar sai da tela cheia. Se este callback não for definido, o player tentará uma ação de navegação padrão (pop ou dismiss) por meio da cadeia de respondedores.

Etapa 4 (Opcional): Configuração personalizada

Para injetar configurações personalizadas do SDK, como estratégia de buffer e Referer, antes que o player esteja pronto, use 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.
}
Nota

Defina a configuração global uma única vez usando [AliPlayerKit setOnGlobalInitBlock:] antes de setup. A configuração da instância é acionada por model.onPlayerConfigBlock sempre que configure: é chamado. Para obter mais informações, consulte Custom Configurations.

Opção 2: Integração da camada de cenas

A camada de cenas oferece soluções completas de reprodução para cenários de negócios específicos, como vídeos longos, vídeos curtos e transmissões ao vivo. Construídas sobre a camada de componentes, essas soluções estão prontas para uso imediato.

Etapa 1: Selecionar um módulo de cena

Os módulos de cena, localizados no diretório PlayerKitScenes, são importados via subspecs do CocoaPods. Os módulos disponíveis incluem:

Módulo de cena

Pod subspec

Descrição

SceneCommon

PlayerKitScenes/SceneCommon

Módulo comum obrigatório para todas as cenas. Funciona como dependência base para outros módulos de cena.

SceneLongVideo

PlayerKitScenes/SceneLongVideo

Cena de vídeo longo: Fornece uma solução completa para reprodução de vídeos longos.

SceneShortVideo

PlayerKitScenes/SceneShortVideo

Cena de vídeo curto: Oferece uma solução completa para feeds de vídeos curtos com reprodução por deslizamento.

SceneLive

PlayerKitScenes/SceneLive

Cena de transmissão ao vivo: Disponibiliza uma solução completa para reprodução de streaming ao vivo.

ScenePlaylist

PlayerKitScenes/ScenePlaylist

Cena de playlist: Entrega uma solução completa para reprodução de playlists de vídeo.

Etapa 2: Iniciar a página da cena

Após integrar um módulo de cena, inicie a página correspondente de uma das duas maneiras seguintes:

Método 1: Instanciação direta (recomendado)

Cada módulo de cena fornece um ViewController independente, que pode ser instanciado diretamente e navegado 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)

O ViewController correspondente para cada cena é o seguinte:

Cena

ViewController

Vídeo longo

SceneLongVideoViewController

Vídeo curto

SceneShortVideoViewController

Transmissão ao vivo

SceneLiveViewController

Playlist

ScenePlaylistViewController

Método 2: Roteamento por Schema

O módulo de cena suporta o início da cena de reprodução correspondente usando o protocolo Schema. O projeto de demonstração fornece a classe utilitária de roteamento AppSchemaRouter, capaz de descobrir e navegar automaticamente para a cena correspondente usando uma 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)

O endereço de schema correspondente para cada cena é o seguinte:

Cena

Schema

Vídeo longo

playerkit://scenes/longvideo

Vídeo curto

playerkit://scenes/shortvideo

Transmissão ao vivo

playerkit://scenes/live

Playlist

playerkit://scenes/playlist

Nota

O ppSchemaRouter é uma ferramenta de roteamento fornecida no projeto de demonstração (módulo App). Ela permite a descoberta automática de módulos com base no protocolo AppModuleProtocol. Os módulos de cena usam classes *Module (como SceneLongVideoModule) para registrar seus schemas, títulos e prioridades. Caso deseje usar roteamento por schema em sua aplicação, consulte esta implementação ou integre seu próprio framework de roteamento.

Implementação de cenas

O código-fonte do módulo de cenas fornece exemplos de melhores práticas para integração da camada de componentes. As seções a seguir descrevem os padrões principais de implementação para cada cena.

Vídeo longo

O SceneLongVideoViewController demonstra o processo padrão de integração para a camada de componentes:

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

Transmissão ao vivo

O SceneLiveViewController demonstra o uso da source URL e do tipo de cenário de transmissão ao vivo:

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];
Nota

O SceneType afeta a configuração de visibilidade dos slots e o comportamento da UI. Por exemplo, em um cenário de transmissão ao vivo, elementos de VOD, como a barra de progresso, são ocultados automaticamente. Para obter mais informações, consulte Scene Type.

Playlist

O ScenePlaylistViewController demonstra um uso avançado de SingletonLifecycleStrategy e PlayerNotificationDelegate para implementar reprodução contínua:

// 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
}
Nota

Para cenários de reprodução em lista, use initWithLifecycleStrategy: para especificar uma estratégia de ciclo de vida e reutilizar instâncias do player, melhorando o desempenho. Para obter mais informações, consulte Player lifecycle strategy.

Exemplos e extensões

Ao seguir estas etapas, você integrou o AliPlayerKit e habilitou a reprodução de vídeo.

Para mais exemplos, consulte os seguintes diretórios:

Módulo

Descrição

PlayerKitUsages

Contém exemplos de uso para APIs comuns, incluindo sistema de logs, sistema de slots, sistema de notificações, sistema de políticas, estratégia de ciclo de vida, pré-carregamento, sources de vídeo e localização.

PlayerKitScenes

Disponibiliza soluções para cenários típicos de reprodução, como vídeos longos, vídeos curtos, transmissões ao vivo e playlists.

O formato da rota Schema para cada exemplo de uso é playerkit://usages/<module_name>. Acesse esses exemplos diretamente na home do projeto de demonstração.