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.
Antes de começar, configure seu ambiente e adicione as dependências necessárias seguindo o guia Integration Preparation.
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 |
|
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 |
|
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. |
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;
}
@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
}
}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
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:
Crie o
AliPlayerController.Configure o
AliPlayerModel(use o método recomendado VidAuth ou a source URL para testes rápidos).Chame
configure:eattach:.Em
dealloc, chamedestroypara 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()
}
}
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 comoYES, iniciando a reprodução automaticamente após a conclusão da configuração. Não é necessário chamarplaymanualmente.A propriedade
AliPlayerController.autoLifecycleManagementvem definida comoYESpor 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 manualmenteonResumeemviewDidAppeareonPauseemviewWillDisappear.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, chamedestroypara 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.
}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 |
|
|
|
Módulo comum obrigatório para todas as cenas. Funciona como dependência base para outros módulos de cena. |
|
|
|
Cena de vídeo longo: Fornece uma solução completa para reprodução de vídeos longos. |
|
|
|
Cena de vídeo curto: Oferece uma solução completa para feeds de vídeos curtos com reprodução por deslizamento. |
|
|
|
Cena de transmissão ao vivo: Disponibiliza uma solução completa para reprodução de streaming ao vivo. |
|
|
|
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 |
|
|
Vídeo curto |
|
|
Transmissão ao vivo |
|
|
Playlist |
|
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 |
|
|
Vídeo curto |
|
|
Transmissão ao vivo |
|
|
Playlist |
|
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];
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
}
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 |
|
|
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. |
|
|
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.