Skip to main content

Guia de Integração do SDK HappyOyster para iOS

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.

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.
OysterStream.register()
HappyOysterEngine.shared: initialize → updateToken → createTravel
OysterTravel:             videoView / events → start → sendInstruct / sendCommand → end

1. Requisitos

Item

Requisito

SO Mínimo

iOS 15.0+

Linguagem

Swift (async/await)

Threading

As APIs públicas são @MainActor; chame-as na thread principal

Importação

import HappyOysterSDK (ponto de entrada agregado, já inclui @_exported Core + World)

A comunicação em tempo real (AliRTC) é encapsulada dentro do SDK; os integradores nunca tocam diretamente na API RTC.

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.
# HappyOysterSDK / AliVCSDK_ARTC are both published on the public CocoaPods source.
source 'https://cdn.cocoapods.org/'

platform :ios, '15.0'
use_frameworks!

target 'YourApp' do
  # Aggregate entry point (Core + World); `import HappyOysterSDK` and you're set.
  pod 'HappyOysterSDK'
  # Optional default UI components (video view, control HUD).
  pod 'HappyOysterSDK/UI'
  # Video stream + AliRTC engine adapter (already depends on Stream; no need to declare it separately).
  pod 'HappyOysterSDK/StreamAliRTC'

  # RTC vendor binary: weak-linked by the SDK, not redistributed with it — bring your own (public CocoaPods source).
  pod 'AliVCSDK_ARTC', '7.11.0'
end
Em seguida, execute 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)

updateToken(_:); o SDK mantém apenas o mais recente

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 createTravel(ticket:)

Os dois não são intercambiáveis: 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.
import HappyOysterSDK
import HappyOysterStream

OysterStream.register()

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.
let engine = HappyOysterEngine.shared
engine.initialize(config: OysterConfig(
    apiHost: "[workspace-id].[region].maas.aliyuncs.com",  // Model Studio gateway host
    model: "happyoyster-1.0-adventure"                     // Versioned model name enabled for your account, required
))
// Optional: override the log level / signalling callback timeout
// OysterConfig(apiHost: "…", model: "…", logLevel: .debug, callbackTimeoutMs: 30_000)

// Both apiHost and model are required with no default: Happy Oyster is split into
// per-mode sub-models. See the Happy Oyster model documentation for available names
// and versions; they must match the account and region of your token.

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.
let token = await fetchTokenFromYourBackend()
engine.updateToken(token)

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.
let travel = try engine.createTravel(ticket: ticket)

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.
containerView.addSubview(travel.videoView)     // SwiftUI: OysterVideoView(travel:)

let eventTask = Task {
    for await event in travel.events {
        switch event {
        case .statusChanged(let status): render(status)   // running / paused / ended / failed…
        case .error(let error):          handle(error)    // error.code / error.kind — see the API Reference
        }
    }
}

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.
let data = try await travel.start()
// data.encryptedTravelId —— identifier of this experience, used for diagnostics / server reconciliation
// data.encryptedWorldId  —— identifier of the world you entered
// data.mode              —— adventure / directing / acting, determines the interaction UI
// data.aspectRatio       —— "9:16" / "16:9"; set for acting only, use it to pick the player orientation
start(maxExperienceTimeSec:) aplica-se apenas a adventure; directing e acting ignoram o parâmetro.
O modo do mundo para esta travel deve corresponder ao 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():
HappyOysterEngine.shared.initialize(config: OysterConfig(
    apiHost: "…", model: "happyoyster-1.0-acting"))   // the model for this world's mode
Enquanto ocioso (nenhuma travel em andamento), a configuração mais recente vence e o token injetado é mantido. O SDK não pode verificar a correspondência modelo/mundo para você antecipadamente: 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.
Enquanto uma travel está em andamento, uma chamada repetida de initialize() é ignorada com um aviso — faça end() primeiro.

Etapa 7: Interação em Tempo Real (Escolha Uma Baseada no Modo)

if data.mode == .adventure {
    // Adventure: direction/view/action control (fire-and-forget; never throws, failures come via events)
    travel.sendCommand(OysterAdventureCommand(translation: .front, interaction: .jump))
} else {
    // Directing and acting: text instructions
    _ = try await travel.sendInstruct(content: "Pan to the castle; the hero starts running")
}
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 none ou chamar flushCommands() 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)

_ = try await travel.pause()           // supported by directing and acting
_ = try await travel.resume()
_ = try await travel.rewind(toSec: 10) // directing only
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.
_ = try? await travel.end()
eventTask.cancel()
Chame await engine.cleanup() ao desmontar o SDK ou trocar de gateways.

4. Exemplo Completo (SwiftUI)

import SwiftUI
import HappyOysterSDK
import HappyOysterStream

@main
struct MyApp: App {
    init() {
        OysterStream.register()                                     // Step 1
        HappyOysterEngine.shared.initialize(config: OysterConfig(   // Step 2
            apiHost: "[workspace-id].[region].maas.aliyuncs.com",
            model: "happyoyster-1.0-adventure"
        ))
    }
    var body: some Scene { WindowGroup { TravelScreen() } }
}

struct TravelScreen: View {
    @State private var travel: OysterTravel?
    @State private var eventTask: Task<Void, Never>?

    var body: some View {
        ZStack {
            if let travel {
                OysterVideoView(travel: travel)      // Step 5: SDK provides the view, host places it
                    .ignoresSafeArea()
            } else {
                Color.black.ignoresSafeArea()
            }
        }
        .task { await start() }
        .onDisappear { Task { await end() } }
    }

    @MainActor private func start() async {
        let engine = HappyOysterEngine.shared
        engine.updateToken(await fetchToken())                      // Step 3
        do {
            let ticket = await fetchTicket()                        // issued by your server
            let travel = try engine.createTravel(ticket: ticket)    // Step 4
            self.travel = travel

            eventTask = Task {                                      // Step 5
                for await event in travel.events {
                    switch event {
                    case .statusChanged(let status): print("status: \(status)")
                    case .error(let error):          print("error: \(error.code)")
                    }
                }
            }

            let data = try await travel.start()                     // Step 6
            if data.mode == .adventure {                            // Step 7
                travel.sendCommand(OysterAdventureCommand(translation: .front))
            } else {
                _ = try await travel.sendInstruct(content: "Suddenly it starts to pour")
            }
        } catch let error as OysterSDKError {
            // Handle start failure (see the error code table in the API Reference)
        } catch {}
    }

    @MainActor private func end() async {
        _ = try? await travel?.end()                                // Step 9
        eventTask?.cancel()
        travel = nil
    }
}

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 chame end() 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 via createTravel depois 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 .error de events e estabelece o estado terminal failed; 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 de aspectRatio (retrato 9:16 por padrão).

6. Próximos Passos