HappyOyster Android SDK 接入指南

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()                                       // Happy Oyster SDK（cn.happyoyster:opensdk）
        maven("https://maven.aliyun.com/repository/public")  // 实时通信引擎（阿里云 ARTC）
    }
}

dependencies {
    implementation("cn.happyoyster:opensdk:<version>")
}

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

<uses-permission android:name="android.permission.RECORD_AUDIO" />

import cn.happyoyster.opensdk.*   // 入口类均在此包下：HappyOyster、SDKConfig、TravelStatusValue、ModeValue、SDKError 等

// 跟踪当前体验状态与本次 Travel 元数据，互动前据此判断是否可发送。
@Volatile private var currentStatus: TravelStatusValue? = null
@Volatile private var currentTravel: StartTravelData? = null

// 1) 初始化（建议在 Application.onCreate）
//    apiHost 必填：千问AI平台 API Host（固定为 `maas.qianwenaiapi.com`）
//    model 必填且无默认值：包含版本的完整模型名称；可用值以千问AI平台官方 HappyOyster 系列模型文档为准
HappyOyster.initialize(
    applicationContext,
    SDKConfig(
        apiHost = "maas.qianwenaiapi.com",
        model = "happyoyster-1.0",
    ),
)

// 2) 注入千问AI平台网关 API Key（作为 Bearer token）
HappyOyster.updateToken(qwenApiKey)

// 3) 监听 SDK 事件：用 onStatusChanged 驱动宿主状态机与互动能力门控
HappyOyster.addListener(object : HappyOysterListener {
    override fun onStatusChanged(status: TravelStatusValue) {
        currentStatus = status
        when (status) {
            // running 才允许互动；世界探索模式的 sendCommand 仅在 running 有效。
            TravelStatusValue.Running -> markInteractionAllowed()
            // paused 是 pauseTravel 真正生效的信号（异步，见下）；此时仍可 sendInstruct。
            TravelStatusValue.Paused -> markTravelPaused()
            // 终态：SDK 已自行结束并释放资源，清理宿主侧本次体验状态。
            TravelStatusValue.Completed, TravelStatusValue.Failed -> clearActiveTravel()
            // init / pending：尚未就绪，互动不可用。
            else -> markInteractionBlocked()
        }
    }
    override fun onError(error: SDKError) {
        // 统一错误回调，见 API Reference 错误码节
    }
})

// 4) 开始体验（ticket 由你的服务端下发）
lifecycleScope.launch {
    try {
        // 同一 App 同一时刻只允许一个并发 Travel（alirtc 限制：即使换一个 ticket
        // 也无法在同一 App 内并发开始第二个 Travel）。已有体验进行中时再次调用会抛出
        // SDKError(103004)，其 raw 仅携带当前正在播放 ticket 的脱敏摘要，不包含完整 ticket。
        val travel: StartTravelData = HappyOyster.startTravel(ticket)
        currentTravel = travel

        // 先检视返回的 Travel 元数据再决定如何互动：
        //   travel.mode          —— directing / adventure / acting
        //   travel.creationModel —— Simple / ScriptList
        //   travel.aspectRatio   —— 仅 acting 有值，用于定播放器方向
        val canSendInstruct = (travel.mode == ModeValue.Directing || travel.mode == ModeValue.Acting) &&
            travel.creationModel != CreationModelValue.ScriptList
        // 注意：ScriptList 模式下调用 sendInstruct 会抛 SDKError(103002)，剧本内容不通过本 SDK 管理。

        // 5) 挂载视频 View（SDK 返回 view，你加入布局）
        //    角色演绎：先按 travel.aspectRatio 定好容器方向，再 attachVideo() 挂载（见「模式适配」）——
        //    远端视图以裁剪填充绑定，容器方向与 aspectRatio 不符会裁掉画面。
        val videoView = HappyOyster.attachVideo()
        binding.videoContainer.addView(videoView)

        // 6) 运行中互动——必须先等到 running 再发送：
        //    - sendCommand（世界探索）：仅 running 有效；init/pending/paused 调用返回 103002。
        //    - sendInstruct（实时导演 / 角色演绎）：running 或 paused 均可；init/pending 调用返回 103002。
        if (canSendInstruct && currentStatus == TravelStatusValue.Running) {
            HappyOyster.sendInstruct("突然下起了大雨")
        }
    } catch (e: SDKError) {
        // 处理开始失败（例如 103004：已有体验在播放）
    }
}

// 7) 暂停 / 恢复（实时导演与角色演绎；回溯仅实时导演）
//    pauseTravel 是异步的：方法返回只代表「受理」，真正暂停以 onStatusChanged(paused) 为准。
//    务必等到 paused 回调后再允许调用 resumeTravel。
lifecycleScope.launch {
    if ((currentTravel?.mode == ModeValue.Directing || currentTravel?.mode == ModeValue.Acting) &&
        currentStatus == TravelStatusValue.Running
    ) {
        HappyOyster.pauseTravel()        // 受理；宿主记录 pausing，等待状态回调
        // …收到 onStatusChanged(Paused) 后…
    }
}
lifecycleScope.launch {
    if (currentStatus == TravelStatusValue.Paused) {
        HappyOyster.resumeTravel()       // 仅在 paused 后调用
    }
}

// 8) 结束体验（SDK 自动断开实时连接并释放资源）
lifecycleScope.launch { HappyOyster.endTravel() }

HappyOyster.initialize(
    context,
    SDKConfig(
        apiHost = "maas.qianwenaiapi.com",  // 必填：千问AI平台 API Host
        model = "happyoyster-1.0",                          // 必填且无默认值：完整模型名称及版本
        logcatEnabled = true,        // 开启内置 Logcat（默认 false）
        logLevel = LogLevel.DEBUG,   // 仅影响内置 Logcat
        logHandler = { record ->     // 可选：转发到宿主自有 Logcat tag
            android.util.Log.d("MyApp/SDK", record.message, record.throwable)
        },
    ),
)

adb logcat -s HappyOysterSDK          # 仅内置 Logcat 开启时有输出
adb logcat -s HappyOysterSDK MyApp    # 同时查看宿主 App 日志（MyApp 换成你的 tag）

// startTravel() 返回之后、attachVideo() 之前：先按 aspectRatio 定好容器方向
val ratio: Float = when (travel.aspectRatio) {   // 宽 / 高
    "9:16" -> 9f / 16f                           // 竖屏（角色演绎的服务端默认值）
    "16:9" -> 16f / 9f                           // 横屏
    else -> HOST_DEFAULT_RATIO                   // null 或未识别取值：回退宿主自己的默认方向
}
// 用 ratio 定容器方向，例如：
//   - Compose：Modifier.fillMaxWidth().aspectRatio(ratio)
//   - View 体系：容器放在 ConstraintLayout 里，宽度撑满、高度由宽高比决定（XML 中 height=0dp）
binding.videoContainer.updateLayoutParams<ConstraintLayout.LayoutParams> {
    dimensionRatio = ratio.toString()
}

// 容器方向确定后，再挂载 SDK 返回的视频 View
val videoView = HappyOyster.attachVideo()
binding.videoContainer.addView(videoView)

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

// Activity 中挂载视频
val videoView = HappyOyster.attachVideo()
binding.videoContainer.addView(videoView)
// 结束时
binding.videoContainer.removeAllViews()

# 清空历史，复现问题，然后抓取 SDK 日志到文件
adb logcat -c
adb logcat -s HappyOysterSDK > happyoyster-sdk.log
# 需要同时看你自己 App 的日志时（把 MyApp 换成你的 tag）：
adb logcat -s HappyOysterSDK MyApp > happyoyster-sdk.log