Skip to main content

Guia de Integração do HappyOyster Android SDK

Ao integrar o HappyOyster Android SDK, seu App pode entrar em mundos gerados por IA em tempo real, proporcionando uma experiência de vídeo interativo em tempo real em três modos: Adventure (exploração de mundo), Directing (direção em tempo real) e Acting (interpretação de papéis).

O Happy Oyster é um produto de exploração de mundos com IA. Ao integrar o SDK Android do Happy Oyster, seu aplicativo pode entrar em "mundos" gerados por IA em tempo real, proporcionando uma experiência de vídeo interativa em tempo real em aventura, direção ou atuação. Este documento é destinado a desenvolvedores Android no lado da integração. Ele cobre instalação, autenticação, o fluxo completo de integração, tratamento de eventos e melhores práticas, explicando como integrar de forma confiável. Para APIs específicas (assinaturas, parâmetros, valores de retorno, códigos de erro, modelos de dados), consulte a Referência da API do SDK Android do Happy Oyster.

1. O Que Você Pode Fazer

  • Iniciar uma experiência (Travel): Entre em um mundo pronto com uma credencial de uso único; o SDK estabelece automaticamente a conexão de vídeo em tempo real.
  • Reprodução em tempo real: O SDK retorna uma View de vídeo que você monta em seu layout para reproduzir os visuais gerados em tempo real pela IA.
  • Interação em tempo real:
    • modo de direção (directing): Envie instruções de texto para conduzir a história.
    • atuação: Também envia instruções de texto; pausar/retomar estão disponíveis; não retroceda e não use sendCommand. Use o aspectRatio da resposta de entrada para definir a orientação do jogador (veja §13 Adaptação de modo).
    • modo aventura (adventure): Envie comandos de controle de direção/ponto de vista/ação para interagir com o mundo.
  • Controle de processo: Pausar / retomar (direção e atuação), retroceder (apenas direção), encerrar (todos os três modos).
  • Callbacks de status e erro: Perceba o status e as exceções da experiência em tempo real através de listeners de eventos.
O SDK não é responsável pela criação e gerenciamento de mundos, nem expõe diretamente detalhes de comunicação em tempo real de baixo nível — estes são tratados pelo seu servidor ou internamente pelo SDK. Você só precisa se concentrar em "iniciar experiência → reproduzir → interagir → encerrar".

2. Instalação

O SDK do Happy Oyster (cn.happyoyster:opensdk) é publicado no Maven Central; seu mecanismo de comunicação em tempo real subjacente (Alibaba Cloud ARTC) é publicado no Alibaba Cloud Maven. Ambos os repositórios devem ser declarados.

Requisitos de ambiente

Item

Requisito

minSdk

24 (Android 7.0) e superior

compileSdk

36

JDK

Alvo de bytecode JDK 11 (toolchain do host: JDK 11 ou superior recomendado)

Linguagem

Kotlin (API de corrotina suspend)

ABI

arm64-v8a / armeabi-v7a (o mecanismo de comunicação em tempo real contém bibliotecas nativas)

Rede

Acesso à internet pública necessário

Adicione os repositórios no settings.gradle.kts da raiz do projeto:
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()                                       // Happy Oyster SDK (cn.happyoyster:opensdk)
        maven("https://maven.aliyun.com/repository/public")  // real-time communication engine (Alibaba Cloud ARTC)
    }
}
Encontre a versão publicada mais recente no Maven Central, substitua <version> abaixo por esse número exato de versão e adicione a dependência no módulo build.gradle.kts:
dependencies {
    implementation("cn.happyoyster:opensdk:<version>")
}
Fixe a dependência em uma versão exata. Revise as notas de lançamento antes de atualizar e recompile o código do host após a atualização.
O SDK é publicado como um AAR leve e não incorpora dependências de terceiros; dependências transitivas, como o mecanismo de comunicação em tempo real, são baixadas automaticamente dos repositórios acima durante a resolução, portanto, o repositório Alibaba Cloud Maven é indispensável—sua ausência fará com que com.aliyun.aio:AliVCSDK_ARTC falhe na resolução.

Permissões

A própria biblioteca do SDK declara apenas INTERNET. O mecanismo de comunicação em tempo real mescla automaticamente um pequeno número de permissões do tipo rede/Bluetooth/configurações de áudio; o manifesto da biblioteca não inclui permissões de microfone ou câmera. O fluxo de vídeo é apenas para reprodução por assinatura, e o SDK não envia áudio real para o lado remoto. O host deve declarar por conta própria: Quando o seu targetSdk for 33 ou superior, você deve declarar a permissão de notificação no AndroidManifest.xml do host (o mecanismo de comunicação em tempo real inclui um serviço em primeiro plano):
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
modo aventura (sendCommand) — declarar a permissão do microfone é recomendado: Os comandos de controle em tempo real do modo aventura trafegam em um uplink carregado por um fluxo de áudio silencioso que estabelece a "identidade do publicador" local; o SDK não grava ou faz upload do seu áudio real. RECORD_AUDIO não é um pré-requisito rígido para o DataChannel — mesmo sem ele, o fluxo silencioso ainda atua como publicador e o uplink normalmente está disponível. Ainda assim, para estabilidade entre dispositivos, nós recomendamos que, se o seu aplicativo usar sendCommand, você declare a permissão no AndroidManifest.xml do host e a solicite em tempo de execução antes de chamar.
<uses-permission android:name="android.permission.RECORD_AUDIO" />
Sobre o código de erro 105004: 105004 significa que o canal em tempo real não está pronto / um envio falhou (por exemplo, uma interrupção do DataChannel ou uma anomalia no canal em tempo real). Não é uma consequência necessária de uma permissão ausente — não é acionado diretamente por RECORD_AUDIO não ter sido concedida. O modo de direção (sendInstruct) e a reprodução de vídeo não são afetados. Se o seu aplicativo não usar o modo aventura, essa permissão não é necessária. Para remover permissões mescladas, use tools:node="remove".

3. Modelo de autenticação

O SDK não obtém nem atualiza tokens, mantendo-o leve. A autenticação possui duas camadas:
  1. API Key do gateway Bailian (百炼): Injetada como um token Bearer pelo seu aplicativo via updateToken(token). O SDK mantém apenas a mais recente; ele não a persiste nem a atualiza, e após a alteração da Key, você a reinjeta. O gateway exige que todas as requisições do SDK, incluindo startTravel, usem este Bearer. Quando a Bearer Key expira ou é inválida, o SDK lança SDKError(101002); neste caso, você deve obter e reinjetar a Bearer Key (updateToken) em vez de trocar por um novo ticket. Durante o desenvolvimento / Demo, você pode usar sua API Key principal do Bailian (百炼) diretamente como o Bearer (updateToken) para fazer o fluxo funcionar. Em produção, sempre mude para um token de curta duração emitido pelo seu servidor, e nunca inclua uma API Key de longa duração em um aplicativo distribuído.
  2. Credencial de experiência de uso único ticket: Trocada pelo seu servidor através da plataforma aberta e entregue ao cliente; usada apenas para uma única startTravel. Ela se torna inválida após o término da experiência (normal ou anormalmente) e não pode ser reutilizada. Erros de credencial no nível do ticket são identificados por códigos de servidor de seis dígitos (por exemplo, 401010 = ticket inválido / expirado, 401011 = ticket já utilizado), os quais o SDK repassa literalmente.
Seu servidor é responsável por criar/gerenciar o World, trocar pelo Travel ticket e entregá-lo ao cliente; o Android SDK apenas consome tokens e tickets e não fornece interface de gerenciamento do World. Durante a inicialização, você deve passar o API Host da sua conta Bailian (百炼) via SDKConfig.apiHost (no formato llm-xxxx.ap-southeast-1.maas.aliyuncs.com, copiado do campo "API Host" na página API Key do console Bailian (百炼)) e passar o SDKConfig.model obrigatório e sem padrão (happyoyster-1.0-directing / happyoyster-1.0-acting / happyoyster-1.0-adventure, correspondendo à entrada da Open API). O SDK completa a URL da requisição como https://{apiHost}/api/v2/apps/{model}/openapi/v1/{endpoint}, portanto, você não precisa montá-la manualmente. Omitir model ao construir SDKConfig é um erro de tempo de compilação. Se model estiver em branco, initialize lança sincronicamente SDKError(100002) (raw = "SDKConfig.model must not be blank"), não cria nem substitui nenhum runtime e não faz nenhuma requisição de rede. O API Host, o modelo e a API Key injetada devem corresponder à conta, região e autorização de modelo necessárias, caso contrário, o gateway normalmente retorna AccessDenied (em tempo de execução, isso é lançado como SDKError(106003), com o corpo original do AccessDenied disponível em SDKError.raw; consulte a linha 106003 da tabela de códigos de erro da Referência da API para uma lista de verificação de solução de problemas). Por segurança, recomendamos fortemente que o cliente injete um token de curta duração emitido pelo seu servidor como o Bearer, em vez de incluir uma API Key de longa duração no aplicativo ou confirmá-la em um repositório de código.
Aviso de conformidade regional: Para apoiar a conformidade com os requisitos legais e de dados aplicáveis, se os seus usuários pretendidos incluírem usuários dos EUA, você deve configurar um API Host da região dos EUA durante a inicialização do SDK para os serviços fornecidos a esses usuários. Os desenvolvedores são responsáveis pela configuração correta e assumem a responsabilidade correspondente sob a lei aplicável em caso de descumprimento deste requisito.

4. Início Rápido

import cn.happyoyster.opensdk.*   // All entry-point classes live in this package: HappyOyster, SDKConfig, TravelStatusValue, ModeValue, SDKError, etc.

// Track the current experience status and this Travel's metadata; use them to decide whether interaction can be sent.
@Volatile private var currentStatus: TravelStatusValue? = null
@Volatile private var currentTravel: StartTravelData? = null

// 1) Initialize (recommended in Application.onCreate)
//    apiHost is required: your account's Bailian API Host (copied from the API Key page in the Bailian console)
//    model is required with no default: the complete model name and version; refer to the official Bailian HappyOyster model documentation for available values
HappyOyster.initialize(
    applicationContext,
    SDKConfig(
        apiHost = "llm-xxxx.ap-southeast-1.maas.aliyuncs.com",
        model = "happyoyster-1.0",
    ),
)

// 2) Inject the Bailian gateway API Key (as the Bearer token)
HappyOyster.updateToken(bailianApiKey)

// 3) Listen to SDK events: use onStatusChanged to drive the host state machine and gate interaction capabilities
HappyOyster.addListener(object : HappyOysterListener {
    override fun onStatusChanged(status: TravelStatusValue) {
        currentStatus = status
        when (status) {
            // Interaction is allowed only in running; adventure-mode sendCommand is valid only in running.
            TravelStatusValue.Running -> markInteractionAllowed()
            // Paused is the signal that pauseTravel has actually taken effect (asynchronous, see below); sendInstruct is still allowed here.
            TravelStatusValue.Paused -> markTravelPaused()
            // Terminal states: the SDK has already ended and released resources; clean up the host-side experience state.
            TravelStatusValue.Completed, TravelStatusValue.Failed -> clearActiveTravel()
            // init / pending: not yet ready, interaction unavailable.
            else -> markInteractionBlocked()
        }
    }
    override fun onError(error: SDKError) {
        // Unified error callback; see the error-codes section of the API Reference
    }
})

// 4) Start the experience (the ticket is delivered by your server)
lifecycleScope.launch {
    try {
        // Only one concurrent Travel is allowed per App at a time (alirtc limitation: even with a different ticket
        // you cannot start a second Travel concurrently within the same App). Calling again while an experience is in progress throws
        // SDKError(103004), whose raw carries only a redacted summary of the ticket currently playing, never the full ticket.
        val travel: StartTravelData = HappyOyster.startTravel(ticket)
        currentTravel = travel

        // Inspect the returned Travel metadata first, then decide how to interact:
        //   travel.mode          —— directing / adventure / acting
        //   travel.creationModel —— Simple / ScriptList
        //   travel.aspectRatio   —— Acting only; use to set player orientation
        val canSendInstruct = (travel.mode == ModeValue.Directing || travel.mode == ModeValue.Acting) &&
            travel.creationModel != CreationModelValue.ScriptList
        // Note: calling sendInstruct in ScriptList mode throws SDKError(103002); script content is not managed through this SDK.

        // 5) Mount the video View (the SDK returns the view; you add it to the layout)
        //    Acting: size the container from travel.aspectRatio first, then attachVideo() (see §13 Mode Adaptation) —
        //    the remote view is bound clip-to-fill, so a mismatched container orientation crops the picture.
        val videoView = HappyOyster.attachVideo()
        binding.videoContainer.addView(videoView)

        // 6) In-run interaction — you must wait for running before sending:
        //    - sendCommand (adventure): valid only in running; calling in init/pending/paused returns 103002.
        //    - sendInstruct (directing / Acting): valid in running or paused; calling in init/pending returns 103002.
        if (canSendInstruct && currentStatus == TravelStatusValue.Running) {
            HappyOyster.sendInstruct("突然下起了大雨")
        }
    } catch (e: SDKError) {
        // Handle start failure (e.g., 103004: an experience is already playing)
    }
}

// 7) Pause / Resume (directing and Acting; rewind is directing only)
//    pauseTravel is asynchronous: the method's return only means "accepted"; the actual pause is determined by onStatusChanged(paused).
//    Be sure to wait for the paused callback before allowing resumeTravel.
lifecycleScope.launch {
    if ((currentTravel?.mode == ModeValue.Directing || currentTravel?.mode == ModeValue.Acting) &&
        currentStatus == TravelStatusValue.Running
    ) {
        HappyOyster.pauseTravel()        // accepted; the host marks pausing and waits for the status callback
        // …after receiving onStatusChanged(Paused)…
    }
}
lifecycleScope.launch {
    if (currentStatus == TravelStatusValue.Paused) {
        HappyOyster.resumeTravel()       // call only after paused
    }
}

// 8) End the experience (the SDK automatically disconnects the real-time connection and releases resources)
lifecycleScope.launch { HappyOyster.endTravel() }

5. Assinatura de eventos e tratamento de erros

Use onStatusChanged para conduzir a máquina de estados do host e controlar as capacidades de interação; use onError para receber erros de tempo de execução de forma uniforme. Para a interface de eventos e os códigos de erro completos, consulte a Referência da API do SDK Android do Happy Oyster. Obrigatório
  • Registre o listener imediatamente após HappyOyster.initialize(...) retornar com sucesso; addListener / removeListener devem ser chamados após initialize (chamá-los antes da inicialização lança SDKError(100001)).
  • Controle por onStatusChanged(Running)—chamadas de interação são permitidas apenas após running; o sendCommand do modo aventura é válido apenas em running.
  • Trate onError também; não capture apenas startTravel. Erros fatais também encerram a experiência (veja a seção de códigos de erro da Referência da API).
Recomendado
  • Chame removeListener em um ponto apropriado do ciclo de vida (como onDestroy) para evitar vazamentos de memória.
Evitar
  • Registrar listeners repetidamente sem chamar removeListener.

6. Enviando instruções: sendInstruct e sendCommand

sendInstruct (direção / atuação)

sendInstruct é usado na direção e atuação para enviar instruções de texto que conduzem a imagem; ele pode ser chamado no estado running ou paused. No estado pausado, o SDK não retoma automaticamente — o host decide se deve chamar resumeTravel primeiro e depois enviar a instrução (para detalhes do contrato, como limitação de taxa e validação de estado, consulte a Referência da API). O creationModel de um mundo de atuação é sempre Simple, portanto, a restrição ScriptList se aplica apenas à direção.

sendCommand (modo aventura)

sendCommand é usado no modo aventura (adventure) para enviar comandos de controle de direção/ponto de vista/ação; é válido apenas em running. O SDK possui um limitador integrado de "o último vence" de 42 ms (24 fps), então o host pode chamá-lo na taxa de quadros do jogo e o SDK faz a mesclagem automaticamente; nenhuma limitação de taxa manual é necessária. Chame uma vez para uma ação única. Para uma ação mantida, continue chamando a cada quadro enquanto mantida e envie explicitamente uma redefinição None quando liberada (para o contrato detalhado de limitação de taxa e superfície de falhas, consulte a Referência da API). Prática recomendada: Na UI de interação do modo aventura do host, forneça três pontos de entrada de comando independentes (direção de movimento + direção do ponto de vista + interação de ação), mantenha o valor atualmente retido para cada grupo e envie um snapshot completo de três campos a cada chamada. Use "None" apenas para dimensões inativas. Quando entradas de diferentes dimensões forem mantidas simultaneamente, preserve e envie todos os valores ativos em vez de redefinir as outras dimensões para "None".

7. Pausar / Retomar / Retroceder

Modos aplicáveis: pausar / retomar se aplicam a direção e atuação, e se comportam de forma idêntica em ambos (incluindo a barreira de 3 segundos abaixo); retroceder é apenas para direção. Chamar pauseTravel / resumeTravel / rewindTravel no modo aventura é rejeitado pelo SDK com 103003. Além disso, a version relatada pelo servidor deve ser o token v2 que seu modo exige (storyV2 para direção, actingV2 para atuação); caso contrário, pausar / retomar retorna 103002. A pausa é assíncrona: O retorno do método pauseTravel significa apenas que ela foi aceita; a pausa real é determinada por onStatusChanged(Paused). Entre "chamar pauseTravel" e "receber o callback Paused", o host pode marcar seu estado de experiência local como pausing; somente após receber Paused você deve permitir a chamada de resumeTravel ou do rewindTravel dependente do estado de pausa. Barreira interna de pausa→reabertura do SDK: assim que Paused for recebido, o host pode chamar resumeTravel / rewindTravel de acordo com o contrato. Se a chamada ocorrer dentro da janela de estabilização de 3 segundos após a confirmação da pausa, o método de suspensão do SDK aguarda o tempo restante antes de enviar a solicitação que reabre a sala em tempo real. O host não precisa de um atraso extra de pausa→retomada, e nenhum atraso é adicionado depois que 3 segundos tiverem decorrido naturalmente. Tempo de espera para chamadas no lado do host (recomendado): Recomenda-se que o host espere para emitir outro pauseTravel dentro de 3 s após resumeTravel retornar com sucesso, para evitar trocas muito frequentes. O próprio SDK não impõe esse tempo de espera. Retroceder: rewindTravel está disponível apenas no estado paused; após retroceder, o servidor retoma automaticamente e o SDK reconecta o RTC automaticamente, sem necessidade de intervenção do host. Sequência típica: pause → wait:paused → rewindTravel(sec). Os segundos de retrocesso rewindToSec devem ser um múltiplo de 4 (por exemplo, 4, 8, 12); não múltiplos são arredondados para baixo pelo servidor (por exemplo, 7→4), e os segundos efetivos reais são determinados pelo resumedAtSec retornado. Retroceder é apenas para direção: chamar rewindTravel no modo atuação ou aventura é rejeitado pelo SDK localmente com 103003, sem emitir nenhuma solicitação HTTP; o host deve ocultar a entrada de retrocesso em vez de apenas desativar o botão. Para detalhes do contrato, como semântica assíncrona e backoff de repetição de 3× (backoff do resumeTravel de 1 s / 2 s / 3 s), consulte a Referência da API do SDK Android do Happy Oyster.

8. Registro de logs

Tag Logcat do SDK: HappyOysterSDK. O SDK fornece dois caminhos de saída de log independentes:
  • Logcat integrado (desativado por padrão): o SDK grava no Logcat apenas quando SDKConfig.logcatEnabled = true (padrão false, totalmente silencioso). SDKConfig.logLevel filtra seu nível mínimo; o padrão INFO já carrega as âncoras de ciclo de vida necessárias para reconstruir uma sessão (inicialização, início da Travel / transições de status / fim, entrada no RTC / primeiro quadro). Reduza para WARN para apenas erros, ou aumente para DEBUG / VERBOSE para um diagnóstico mais profundo. logLevel não afeta logHandler.
  • Callback do host logHandler (recomendado): recebe cada LogRecord do SDK (o fluxo completo), totalmente independente de logLevel / logcatEnabled, e pode encaminhar para o próprio sistema de log do host (Logcat, arquivos, plataformas de crash, etc.). O callback deve ser rápido e não bloqueante e não deve fazer chamadas de volta ao SDK; as exceções que ele lança são capturadas silenciosamente; LogRecord.message é ocultado e não contém token Bearer, ticket ou token RTC em texto simples.
HappyOyster.initialize(
    context,
    SDKConfig(
        apiHost = "llm-xxxx.ap-southeast-1.maas.aliyuncs.com",  // required: your account's Bailian API Host
        model = "happyoyster-1.0",                          // required with no default: complete model name and version
        logcatEnabled = true,        // enable built-in Logcat (default false)
        logLevel = LogLevel.DEBUG,   // affects only the built-in Logcat
        logHandler = { record ->     // optional: forward to the host's own Logcat tag
            android.util.Log.d("MyApp/SDK", record.message, record.throwable)
        },
    ),
)
adb logcat -s HappyOysterSDK          # output only when built-in Logcat is enabled
adb logcat -s HappyOysterSDK MyApp    # also view the host App logs (replace MyApp with your tag)
Correlação de sessão e solicitação: o travelId (ou seja, encryptedTravelId) nos logs do SDK é emitido em sua totalidade e é a chave de sessão enviada ao servidor — inclua-o ao investigar uma sessão ou abrir um chamado para alinhar os logs do cliente e do servidor. Cada linha de resposta HTTP também carrega o requestId do servidor (o campo reqId=, mostrado como - quando ausente) para identificar uma única solicitação; este ID aparece apenas nos logs e nunca é exposto em nenhum valor de retorno público.

9. Ciclo de vida e memória

  • Chame initialize em Application.onCreate, uma vez globalmente.
  • Reinicialização em estado ocioso (por exemplo, para alternar a região da API ou model) fecha o tempo de execução ocioso anterior e redefine os listeners registrados e o estado do feature-gate; registre novamente os listeners após o seu retorno. A reinicialização é rejeitada com 103004 enquanto uma Travel estiver iniciando, ativa ou terminando: sempre aguarde endTravel() primeiro. O SDK nunca descarta uma Travel ativa como efeito colateral de initialize.
  • A experiência está vinculada ao ciclo de vida do host: chame endTravel no onDestroy da Activity/Fragment (ou no onCleared do ViewModel) para garantir que a conexão em tempo real e os recursos sejam liberados.
  • Remova a View retornada por attachVideo() do layout ao encerrar (container.removeAllViews()) e chame removeListener.
  • O SDK mantém apenas o contexto da aplicação; da mesma forma, não passe uma Activity para o SDK.

10. Corrotinas e threads

  • Os métodos de negócio são suspend; chame-os em lifecycleScope / viewModelScope a partir de qualquer contexto de corrotina. O SDK coordena o estado e o trabalho RTC em seu dispatcher principal, enquanto o HTTP permanece fora da thread principal.
  • Se a corrotina chamadora for cancelada, o SDK cancela a solicitação HTTP em andamento dessa chamada, se houver, e propaga CancellationException inalterado em vez de convertê-lo para SDKError; não o capture ou ignore como uma falha operacional. O cancelamento não reverte uma solicitação que o servidor já aceitou.
  • Chame attachVideo() e sendCommand() na thread principal; uma chamada fora da thread principal lança sincronicamente IllegalStateException.

11. Gerenciamento de tokens

  • A Bearer API Key tem um período de validade limitado; recomenda-se garantir que o token esteja atualizado antes de entrar em uma experiência. Ao receber onError(101002) (token expirado), obtenha novamente a Bearer Key e chame updateToken—não há necessidade de trocar por um novo ticket.

12. Recuperação de erros

  • Para erros fatais: limpe o estado atual da experiência (incluindo a remoção da View de vídeo), notifique o usuário e permita o reinício.
  • Para instabilidade de rede (106001) e anomalias temporárias do serviço upstream (106003): um número limitado de tentativas pode ser realizado.
  • Um 100002 síncrono da inicialização significa que model está em branco; forneça o nome e a versão completos do modelo e inicialize novamente. Se um model não vazio tiver o nome ou versão errados, tiver sido descontinuado, ainda não tiver sido publicado ou não estiver autorizado, o gateway normalmente retorna AccessDenied, mapeado para 106003; use SDKError.raw e verifique se o model, API Host, API Key, conta e região correspondem.
(Para a classificação de fatal / não fatal, veja a seção de códigos de erro da Referência da API do SDK Android do Happy Oyster.)

13. Adaptação de modo

  • Use o mode retornado por startTravel para decidir quais capacidades de interação expor: direção e atuação usam a instrução de texto sendInstruct (a atuação também usa aspectRatio para a orientação do jogador e oculta o retrocesso); o modo aventura usa o comando de controle sendCommand.
  • No modo aventura, você pode usar a sobrecarga startTravel(ticket, maxExperienceTimeSec) para limitar a duração máxima desta experiência (segundos; a sessão termina automaticamente quando atingida). Os valores permitidos são configurados pelo servidor (atualmente 60 / 90 / 120, padrão 60); direção e atuação ignoram o valor (o servidor o ignora e ecoa null). Passar um valor não suportado faz com que o servidor retorne 400000 e esta inicialização falhe. Consulte a Referência da API para detalhes dos parâmetros.

atuação: Definindo a orientação do jogador a partir de aspectRatio

StartTravelData.aspectRatio é não-null apenas para atuação: "9:16" (retrato, o padrão do lado do servidor quando o mundo é criado) ou "16:9" (paisagem); é null para aventura e direção. A tela é fixada quando o mundo é criado (especificado pelo seu servidor através da Open API), portanto, para o cliente, é um resultado somente leitura. O SDK preserva valores não reconhecidos literalmente, então o host deve tratar qualquer valor que não reconheça como null e retornar à sua própria orientação padrão. Temporização: decida a orientação do contêiner de reprodução após startTravel() retornar e antes de chamar attachVideo() e montar o SurfaceView retornado em seu layout. O SDK só começa a vincular e renderizar o fluxo remoto depois que a visualização do host é anexada, portanto, decidir a orientação nesse ponto ainda precede o primeiro quadro renderizado. O valor é entregue com o valor de retorno de startTravel() e não há garantia de que chegará antes do SDK entrar no canal de comunicação em tempo real — ele só precisa ser aplicado antes de attachVideo(). Consequência: a visualização remota é vinculada com um modo de renderização clip-to-fill — um contêiner cuja orientação discorda de aspectRatio corta a imagem (por exemplo, um fluxo em retrato 9:16 colocado em um contêiner 16:9 perde a maior parte de sua parte superior e inferior) em vez de aplicar letterboxing.
// After startTravel() returns and before attachVideo(): size the container from aspectRatio first
val ratio: Float = when (travel.aspectRatio) {   // width / height
    "9:16" -> 9f / 16f                           // portrait (the Acting server-side default)
    "16:9" -> 16f / 9f                           // landscape
    else -> HOST_DEFAULT_RATIO                   // null or unrecognized: fall back to your own default orientation
}
// Apply `ratio` to the container, for example:
//   - Compose: Modifier.fillMaxWidth().aspectRatio(ratio)
//   - Views: put the container in a ConstraintLayout, full width, height driven by the ratio (height=0dp in XML)
binding.videoContainer.updateLayoutParams<ConstraintLayout.LayoutParams> {
    dimensionRatio = ratio.toString()
}

// Only once the container orientation is settled, mount the video View returned by the SDK
val videoView = HappyOyster.attachVideo()
binding.videoContainer.addView(videoView)
Quando a atuação não está habilitada para a conta (ou a especificação está desativada), tanto a criação quanto a entrada no mundo são rejeitadas pelo servidor: startTravel falha com 403007 (rejeitado antes que o Travel seja criado), que o SDK repassa literalmente. Não tente novamente este código como capacidade cheia; em vez disso, solicite a habilitação.

14. Exemplo completo (trecho de ViewModel + Activity)

class TravelViewModel : ViewModel() {

    private val listener = object : HappyOysterListener {
        override fun onStatusChanged(status: TravelStatusValue) {
            _status.value = status
        }
        override fun onError(error: SDKError) {
            _error.value = error
        }
    }

    init { HappyOyster.addListener(listener) }

    fun start(ticket: String) = viewModelScope.launch {
        try {
            val travel = HappyOyster.startTravel(ticket)
            _travel.value = travel
        } catch (e: SDKError) {
            _error.value = e
        }
    }

    fun send(text: String) = viewModelScope.launch {
        runCatching { HappyOyster.sendInstruct(text) }
    }

    fun stop() = viewModelScope.launch { runCatching { HappyOyster.endTravel() } }

    override fun onCleared() {
        HappyOyster.removeListener(listener)
        viewModelScope.launch { runCatching { HappyOyster.endTravel() } }
    }
}

// Mount the video in the Activity
val videoView = HappyOyster.attachVideo()
binding.videoContainer.addView(videoView)
// On end
binding.videoContainer.removeAllViews()

15. Guia de solução de problemas de DevOps

Quando algo dá errado durante a integração (não é possível entrar em um Travel, tela preta sem vídeo, queda de fluxo no meio da sessão, anomalias de pausa/retomada, ...), abrir os logs do SDK é a maneira mais rápida de localizar o problema. Este capítulo apresenta um fluxo padrão de solução de problemas — útil tanto para sua própria verificação quanto para nos fornecer informações suficientes em uma única interação.

15.1 Habilitando logs

Escolha uma saída de log conforme necessário durante a solução de problemas (consulte §8 Logging): para uma verificação rápida, defina logcatEnabled = true e leia-o com adb logcat, aumentando logLevel para DEBUG ou VERBOSE ao diagnosticar (o padrão INFO já carrega a linha do tempo completa do ciclo de vida; reduza para WARN para apenas erros); para alimentar seu próprio sistema, use logHandler para receber cada LogRecord (não afetado por logLevel) e grave-o em seu arquivo ou plataforma de crash.

15.2 ID de correlação da sessão: travelId

O travelId (ou seja, StartTravelData.encryptedTravelId) nos logs do SDK é emitido por completo. É o identificador único que percorre uma sessão e a chave da sessão enviada ao servidor. É a chave para alinhar os logs do cliente com os registros de sessão do lado do servidor — sempre inclua o travelId da sessão com falha ao relatar um problema.

15.3 Coletando logs

Ao reproduzir o problema, persista os logs do SDK em um arquivo:
# Clear history, reproduce the issue, then capture SDK logs to a file
adb logcat -c
adb logcat -s HappyOysterSDK > happyoyster-sdk.log
# To also see your own app logs (replace MyApp with your tag):
adb logcat -s HappyOysterSDK MyApp > happyoyster-sdk.log

15.4 O que incluir ao relatar um problema

Para evitar múltiplas interações, anexe o seguinte:

Item

Notas

Versão do SDK

HappyOyster.VERSION

Sessão travelId

o encryptedTravelId da sessão com falha (veja 15.2)

Hora da ocorrência

a hora aproximada (nível de minuto é suficiente)

Código de erro

o SDKError.code capturado (significados na tabela de códigos de erro da Referência da API)

Etapas de reprodução

caminho da ação + resultado esperado + resultado real

Ambiente

modelo do dispositivo, versão do Android, rede (Wi-Fi/celular)

Arquivo de log

o log HappyOysterSDK de 15.3 (DEBUG/VERBOSE recomendado)

15.5 Sobre a ocultação de dados e o compartilhamento de logs

Os logs do SDK são projetados para serem seguros para compartilhamento: credenciais (token Bearer, ticket de Travel, token RTC), identificadores internos do RTC e URLs de mídia são ocultados antes de serem gravados, portanto, nunca aparecem em texto simples; travelId é um identificador de sessão (não uma credencial) e é mantido por completo apenas para correlação. Mesmo assim, recomendamos a transferência de arquivos de log por um canal confiável em vez de colá-los publicamente em plataformas não controladas.