聊天页的四种形态

同一套对话界面，可以用四种方式装进你的 APP。选哪一种取决于客服入口在你 APP 里的位置，以及你想让客户看到多少你自己的界面。

四种形态长什么样

标准档	弹层档
嵌入档	沉浸档

	占多少屏幕	标题栏	客户怎么退出
标准档	整页	SDK 画一条，跟你的 APP 主题	左上角返回
弹层档	半屏卡片	系统样式的一条	右上角关闭、下拉、点卡片外
嵌入档	你说了算	你自己画	你自己的返回
沉浸档	整屏	工作台配的渠道外观那一套	右上角关闭（iOS 见下）

出口的位置有规律：能退回上一页的形态，出口在左上角；没有上一页可退的，出口是右上角的关闭。 弹层是盖在当前页上的，关掉就回到原处，所以是关闭而不是返回。沉浸档在 iOS 上看你从哪进：有导航栏就推进去、左上角返回，没有才盖在上面、右上角关闭。

怎么选

你的情况	用哪档
从「我的」「设置」这类页面进客服	标准档 —— 接入最省事，界面全由 SDK 提供
客户在商品页、订单页问一句就走，不想让他离开当前页	弹层档
客服是 APP 里的一个 Tab，或要和别的内容同屏	嵌入档
想让客服页整屏都是自己的品牌色	沉浸档

拿不准就从标准档开始。四档共用同一套配置和回调，换档只是换一个调用方法，之前接的身份、未读、推送都不用动。

标准档

// Android
HecongChatActivity.start(this, config)

// iOS：SDK 自己找到当前的导航栏推进去
HecongChat.shared.push(config: config)

Android 这一档的标题栏由 SDK 画，跟着你的 APP 主题走深浅色。iOS 推进你自己的导航栏，SDK 不另画一条；页面标题会填成配置里的 title，你已经设过的话不覆盖。

iOS 上你不用告诉 SDK 从哪个页面打开——它自己找前台最上层的导航栏，UIKit 和 SwiftUI 工程都直接在按钮回调里调。当前页面没有导航栏时（比如从一个模态页里点开客服），会退化成全屏弹页，顶上是系统导航栏和一个关闭按钮，功能不缺。

iOS 这一档还会自动隐藏底部 Tab 栏、把大标题模式关掉 —— 客服页占满一屏，不带你的 Tab 更合理。要大标题的话 push 之后自己改回来。

弹层档

// Android
HecongChatActivity.startSheet(this, config)

// iOS
HecongChat.shared.presentSheet(config: config)

卡片默认占屏幕高度的 82%，用 sheetHeightRatio 调（取值 0.3 到 1.0）。客户上拉能全屏、下拉能关掉、点卡片外面也关。

iOS 上这个比例要 iOS 16 及以上才生效：iOS 15 上是系统的半屏高度，iOS 13、14 没有系统弹层，这一档会整屏打开 —— 关闭按钮和功能都在，只是形态退回整屏。

带上 useChannelHeader 参数，卡片里的顶栏就换成工作台配的渠道外观那一套，和沉浸档一个观感，只是装在卡片里：

HecongChatActivity.startSheet(this, config, useChannelHeader = true)

HecongChat.shared.presentSheet(config: config, useChannelHeader: true)

嵌入档

对话嵌进你自己的布局，标题栏、返回、周围的内容都由你安排。

// Android：SDK 提供的 Fragment，选文件、权限、返回键都在内部处理好了
supportFragmentManager.beginTransaction()
    .replace(R.id.container, HecongChatFragment.newInstance(config))
    .commit()

// iOS：当成普通子页面摆进去
let vc = HecongChatViewController(config: config)
addChild(vc)
view.addSubview(vc.view)
vc.didMove(toParent: self)

Android 用这一档要自带 androidx.fragment

SDK 不把 androidx.fragment 打进包里，用 Fragment 的工程自己已经有了。没有的话编译时会找不到类，加上依赖即可。

还有一种更底层的做法是把 HecongChatView 直接放进布局，代价是选文件、权限、前后台这些回调要你自己转发，见把聊天嵌进自己的页面。只想嵌进 Tab 的话用 Fragment 就行，不用走那条路。

沉浸档

// Android
HecongChatActivity.startImmersive(this, config)

// iOS
HecongChat.shared.presentImmersive(config: config)

整屏显示，顶栏是工作台里配好的渠道外观 —— 头像、昵称、背景色都跟着渠道模板走，SDK 侧不用配。状态栏的时间和电量图标会根据顶栏深浅自动切黑白。

iOS 上它怎么进来取决于当前页面有没有导航栏。 有导航栏（多数从「我的」「设置」进来的情况）就推进导航栈，客户左上角返回或侧滑退出；没有导航栏才整屏盖上去，右上角关闭。这带来一条写代码时要注意的：推进导航栈的那种情况下，你自己调 dismiss 是不会有反应的，要退它得用 popViewController。不过退出本来就由 SDK 处理，你不需要在关闭回调里再退一次。

Android 上整屏铺到状态栏下面、状态栏底色跟着顶栏走的效果需要 Android 11 及以上；Android 10 及以下不铺屏，状态栏保持你 APP 的主题色，功能不缺，见兼容性核对。

标题栏能改什么

标准档和弹层档的标题栏可以配这几项（沉浸档的顶栏来自工作台的渠道外观，不受这些影响）：

配置项	默认	说明
title	「在线客服」	标题文字。跟随语言设置，英文环境是 Customer service
titleFollowsAgent	false	开了之后客服接待时标题换成客服昵称，转接时跟着换
headerBackgroundColor	跟随深浅色	标题栏背景色
titleColor	跟随深浅色	标题文字颜色
backIconRes（Android） backImage（iOS）	系统返回箭头	换成你自己的返回图标

iOS 标准档用的是你自己的导航栏，SDK 只填标题：配色和返回图标跟着你的导航栏走，改它们要在你自己那边改。Android 标准档的标题栏由 SDK 画，上面几项都生效。

HecongChatConfig("你的渠道ID").apply {
    title = "售后咨询"
    titleFollowsAgent = true
}

let config = HecongChatConfig(channelId: "你的渠道ID")
config.title = "售后咨询"
config.titleFollowsAgent = true

要改的是对话内容区的配色、欢迎语这些，入口在工作台，见聊天窗口。

下一步

• 把聊天嵌进自己的页面 —— 自己摆容器时要转发的几个回调
• 聊天窗口 —— 在工作台调整对话界面的样子
• 接口速查 —— 全部配置项与回调