Este é o caminho de integração mais curto para desenvolvedores iOS: da inicialização, passando pela exibição da imagem na tela, envio de instruções de controle, até o encerramento da experiência. Para assinaturas completas de métodos, campos e códigos de erro, consulte a Referência da API do SDK para iOS.
0. O Que Você Vai Construir
Um loop mínimo de ponta a ponta de "entrar em um mundo → experiência de vídeo em tempo real → interagir → encerrar". Os pontos de entrada de tempo de execução são o global HappyOysterEngine.shared e o identificador de sessão de uso único OysterTravel que ele cria.
1. Requisitos
Item | Requisito |
|---|---|
SO Mínimo | iOS 15.0+ |
Linguagem | Swift ( |
Threading | As APIs públicas são |
Importação |
|
1.1 Adicionar o SDK via CocoaPods
O SDK é distribuído como um binário pré-compilado (xcframework) via subspecs do CocoaPods, publicado no Trunk público do CocoaPods — referencie-o diretamente pela versão, sem necessidade de arquivo podspec local.
pod install e abra o .xcworkspace gerado (não o .xcodeproj).
AliVCSDK_ARTC é obrigatório sempre que você incluir HappyOysterSDK/StreamAliRTC: se estiver ausente, o SDK reverte silenciosamente para Loopback — ele ainda se conecta e atinge running, mas mostra uma tela preta sem erro.2. Dois Tipos de Credenciais (Entenda-os Primeiro para Evitar Armadilhas)
O SDK não obtém nem renova nenhuma credencial por conta própria; você injeta todas elas:
Credencial | Fonte | Finalidade | Como Injetar |
|---|---|---|---|
Token de autenticação HTTP | Seu aplicativo o obtém de seu próprio backend | Autenticação geral para chamadas do SDK ao gateway (de longa duração, necessita renovação) |
|
Ticket de uso único | Emitido pelo seu servidor após troca via API de credenciais da Travel | Usado para uma única experiência, invalidado imediatamente após o uso | Passado como o argumento |
updateToken é para autenticação geral, enquanto ticket é uma credencial de entrada de uso único. As chaves AK / assinatura existem apenas no seu servidor e nunca são expostas ao cliente.3. Etapas de Integração
Ciclo de vida: registrar o stream engine → inicializar → injetar token → criar a sessão → anexar vídeo + assinar eventos → iniciar → interagir → encerrar.
Etapa 1: Registrar o Stream Engine
O único ponto de entrada para renderização de vídeo. Chame-o uma vez na inicialização do aplicativo; chamadas repetidas são seguras.
Etapa 2: Inicializar o SDK
Você deve inicializar uma vez antes de chamar qualquer outra API. Para trocar de gateway ou modelo, basta chamá-lo novamente — enquanto ocioso, a configuração mais recente vence e o token injetado é mantido; a chamada é ignorada apenas enquanto uma travel está em andamento, então faça end() primeiro.
Etapa 3: Injetar o Token de Autenticação HTTP (push)
Obtenha uma Model Studio API Key temporária do seu próprio backend e injete-a. Re-injete após a expiração.
Etapa 4: Criar o Identificador de Sessão
Crie um OysterTravel a partir de um ticket de uso único. Nada está conectado ainda, mas a visualização de vídeo já está disponível.
Etapa 5: Anexar a Visualização de Vídeo e Assinar Eventos
O SDK fornece a visualização, o host a posiciona. Assine antes start() para não perder alterações iniciais de status.
Etapa 6: Iniciar a Experiência
Conecte e comece a reproduzir. O SDK então mantém automaticamente a conexão em tempo real e o polling de status, expondo o status através de events.
start(maxExperienceTimeSec:) aplica-se apenas a adventure; directing e acting ignoram o parâmetro.model que você passou para initialize na Etapa 2. Com modelos por modo (happyoyster-1.0-adventure / -directing / -acting), cada modelo é sua própria rota de aplicação de gateway, então um único initialize serve apenas a mundos de um modo; o ticket foi emitido pelo seu servidor sob a rota do modo desse mundo, e start() o envia para a rota do model atualmente configurado — uma incompatibilidade falha nesta etapa.
Antes de entrar em um mundo de um modo diferente, chame initialize() novamente com o modelo correspondente — sem cleanup() e sem re-updateToken():
mode chega apenas na resposta desta etapa (data.mode); antes da chamada, o SDK possui nada além de um ticket opaco e um nome de modelo. Aplicativos que oferecem um único modo não são afetados e inicializam uma vez.
initialize() é ignorada com um aviso — faça end() primeiro.Etapa 7: Interação em Tempo Real (Escolha Uma Baseada no Modo)
sendCommand faz throttling internamente em um ciclo de 42ms (24FPS) onde o último valor vence, para que o host possa chamá-lo em alta frequência:
- Ações únicas, como pular, atacar, agachar e correr, são enviadas uma vez.
- Movimento e rotação da visão são enviados continuamente enquanto mantidos, e você simplesmente para de chamar ao soltar.
- Você não precisa enviar
noneou chamarflushCommands()ao soltar; o SDK nunca gera um comando de parada por conta própria, e o servidor encerra a ação assim que o canal em tempo real fica silencioso.
Etapa 8: Pausar / Retomar / Retroceder (Dependente do Modo)
adventure não suporta none destes; acting suporta pausar/retomar, mas não suporta retroceder — oculte o ponto de entrada de retrocesso nesses modos. Chamadas incompatíveis são rejeitadas localmente pelo SDK (103003 / 103002).Etapa 9: Encerrar a Experiência
Desconecta, interrompe o polling e libera todos os recursos da sessão; o ticket é consumido. Idempotente — todo caminho de saída deve convergir para ele.
await engine.cleanup() ao desmontar o SDK ou trocar de gateways.4. Exemplo Completo (SwiftUI)
5. Melhores Práticas
- Ciclo de vida: Chame
OysterStream.register()+initialize()o mais cedo possível na inicialização do aplicativo, uma vez cada globalmente; sempre chameend()ao sair da página de experiência para garantir que a conexão em tempo real e os recursos sejam liberados.OysterTravelé de uso único — crie um novo viacreateTraveldepois que ele atingir um estado terminal. - Renovação de token: Certifique-se de que o token HTTP esteja atualizado antes de iniciar uma experiência; ao receber um callback de erro relacionado à autenticação, obtenha um novo token e chame
updateToken(não fatal, não encerra a experiência). - Gravidade do erro: Para erros fatais, o SDK encerra automaticamente a experiência atual, expõe-os via
.errordeeventse estabelece o estado terminalfailed; você deve retornar à tela exibida antes de "iniciar experiência". Erros não fatais são apenas expostos e podem ser tentados novamente. Consulte a tabela completa de códigos de erro na Referência da API. - Adaptação de modo: Os modos directing e acting mostram uma entrada de texto (
sendInstruct); o modo adventure mostra widgets de controle (sendCommand). Apenas directing mostra um ponto de entrada para retrocesso. Para mundos acting, escolha a orientação do player a partir deaspectRatio(retrato9:16por padrão).
6. Próximos Passos
- API completa (
pause()/resume()/rewind(toSec:), modelos de dados, códigos de erro) → Referência da API do SDK para iOS