七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入

自定义样式

聊天窗口样式

本节说明聊天窗口主题、头像、气泡、输入框和资源样式等 UI 配置。

对话框内容样式模板ID

SDK在后台样式设置开的情况下,会自动应用企业后台设置的默认样式,或配置templateId应用自定义配置的对话框样式。

参数名类型参数说明取值说明
templateIdlong对话框内容样式模板id后台样式设置的模板ID,使用默认样式则不用传值查询路径:管理端首页 - 在线客服 - 设置 - 访客端 - 样式设置

App 侧配置示例

如果 App 需要指定某一套后台样式模板,在初始化 SDK 时设置 YSFOptions 的 templateId。不设置时使用后台默认样式。

YSFOptions options = new YSFOptions();
options.templateId = 123456L;

Unicorn.config(context, appKey, options, imageLoader);
Unicorn.initSdk();

聊天窗口自定义

为了咨询客服窗口的界面风格能与集成七鱼 SDK 的 App 能够整体统一,七鱼 SDK 提供了简洁的 UI 自定义配置选项。

开发者可在初始化 SDK 或者在运行时任意时候修改配置,当需要与 SDK 提供的默认界面不一样表现的地方,就修改对应的项,否则不赋值即可,界面会保留默认表现。修改各设置项后,都需要等到下次进入会话界面才会看到相应的更改。

参数名类型参数说明取值说明
uiCustomizationUICustomization聊天窗口自定义UICustomization对象

聊天窗口的详细样式由 UICustomization 提供。

参数名类型参数说明取值说明是否受后台设置影响
msgBackgroundUriString客服消息窗口背景图片设置uri(支持格式见表后)否
msgBackgroundColorint客服消息窗口颜色。如果同时设置 uri 和颜色,优先使用 uri32 位颜色值否
msgListViewDividerHeightint消息列表消息项间距单位为 pixel否
hideLeftAvatarboolean是否隐藏左侧(客服消息)头像默认为 false,不隐藏否
hideRightAvatarboolean是否隐藏右侧(访客消息)头像默认为 false,不隐藏否
avatarShapeint头像形状风格0为圆形头像,1为方形头像否
priorityWebAvatarboolean左侧 (客服消息)头像优先级默认为false,本地设置优先,若为true,管理端优先否
leftAvatarString左侧 (客服消息)头像图片 uriuri(支持格式见表后)跟随优先级
rightAvatarString右侧 (访客消息)头像图片 uriuri(支持格式见表后)否
isShowTitleAvatarboolean是否在标题栏上面展示头像,只对 Activity 接入方式生效默认为 false,不展示是
tipsTextColorint提示类消息的字体颜色(包括分配客服消息,消息时间标签等)32 位颜色值否
tipsTextSizefloat提示类消息的字体大小(包括分配客服消息,消息时间标签等)单位为 sp否
msgItemBackgroundLeftint左边消息项背景, 最好是 selector,同时影响文本和语音消息。drawable resId是
msgItemBackgroundRightint右边消息项背景, 最好是 selector,同时影响文本和语音消息。drawable resId是
msgRobotItemBackgroundLeftint左边机器人消息项背景, 最好是 selectordrawable resId否
msgRobotItemBackgroundRightint右边机器人消息项背景, 最好是 selectordrawable resId否
audioMsgAnimationLeftint左侧语音消息播放时候的动画 animation-list,没有播放时显示最后一帧drawable resId否
audioMsgAnimationRightint右侧语音消息播放时候的动画 animation-list,没有播放时显示最后一帧drawable resId否
textMsgColorLeftint左侧文本消息颜色32 位颜色值否
hyperLinkColorLeftint左侧文本消息中超链接的颜色32 位颜色值否
textMsgColorRightint右侧文本消息颜色32 位颜色值否
hyperLinkColorRightint右侧文本消息中超链接的颜色32 位颜色值否
textMsgSizefloat文本消息字体大小单位为sp否
inputTextColorint底部消息输入框的字体颜色32 位颜色值否
inputTextSizefloat底部消息输入框的字体大小单位为sp否
topTipBarBackgroundColorint顶部提示栏(没有客服,排队状态等)背景色32 位颜色值否
topTipBarTextColorint顶部提示栏文字颜色32 位颜色值否
topTipBarTextSizefloat顶部提示栏文字大小单位为 sp否
titleBackgroundResIdint标题栏背景图drawable resId否
titleBackBtnIconResIdint返回键图标资源,若titleBarStyle为深色系,则不生效drawable resId否
titleBackgroundColorint标题栏背景颜色,如果同时设置 drawable 和颜色,优先使用 drawable32 位颜色值否
statusBarColorint设置状态栏颜色32位颜色值否
titleBarStyleint标题栏风格,影响标题和标题栏上按钮的颜色目前支持: 0浅色系,1深色系是
titleCenterboolean标题居中如果为 true ,居中,否则(默认)居左否
buttonBackgroundColorListint发送,选择,预览等按钮的颜色ColorStateList,可参考 SDK 的 ysf_button_color_state_list是
buttonTextColorint发送,选择,预览等按钮的文字颜色32 位颜色值否
hideAudioboolean是否隐藏语音输入栏默认为 false,不隐藏是
hideAudioWithRobotboolean在机器人聊天界面是否隐藏语音输入栏默认为false,不隐藏。给机器人发送语音后,会先转成文字消息,再发送给机器人否
hideEmojiboolean是否隐藏表情输入栏默认为 false,不隐藏是
screenOrientationint屏幕旋转角度0 为仅竖屏显示,1为仅横屏显示,2为根据重力感应切换否
hideKeyboardOnEnterConsultboolean在进入聊天界面时是否隐藏输入键盘默认为 false,进入时就自动弹出键盘否
robotBtnBackint机器人会话中的按钮的背景机器人按钮的背景图片 drawable是
robotBtnTextColorint机器人会话中的按钮的文字颜色机器人按钮的文字颜色 32 位颜色值否
inputUpBtnBackint输入栏上方一触即达按钮的背景输入栏上方一触即达按钮的背景 drawable否
inputUpBtnTextColorint输入栏上方一触即达按钮的文字颜色输入栏上方 一触即达按钮的文字颜色 32 位颜色值否
loadingAnimationDrawableint聊天界面下拉加载更多 loading 动画的 drawable id(drawable 类型为 animation-list 帧动画)默认为 0 ,也就是使用 SDK 默认的动画否
editTextHintString聊天界面的 editText 的 hint默认为 请输入想要咨询的问题是
isFullScreenboolean是否设置全屏,只有在横屏下才生效默认为 false,非全屏否
hideLeftNameboolean是否隐藏客服名称默认为 false,不隐藏否
disableKeyboardOnEnterConsultboolean在进入聊天界面时设置键盘不可用默认为 false否
isRobotMessageFoldboolean机器人回复超长消息是否折叠默认为 false否
isRobotSendImageboolean机器人阶段是否展示发送图片控件默认为 false,不展示否
showRobotImageEntryint输入栏机器人阶段相机按钮展示样式,只有isRobotSendImage设置为true时才生效默认为0,展示相机图标设置为1展示“+”图标否

图片 uri 支持的格式由开发者根据自己使用的图片加载框架定义。但必须要支持 file://, http:// 和 https:// 这3种。 如果开发者遇到下面两种情况,请首先检查图片加载器是否有正常初始化或是否支持当前图片路径:

  1. 设置的 leftAvatar 或者 rightAvatar 无效,展示的是 app 的 icon;
  2. 聊天框中不展示接收到的信息(没有展示聊天气泡);

代码示例

UICustomization customization = DemoCache.ysfOptions.uiCustomization;
customization.msgBackgroundUri = "file:///android_asset/msg_bg.png";
customization.leftAvatar = "android.resource://" + getContext().getPackageName() + "/" + R.drawable.my_avatar_staff;
customization.rightAvatar = "android.resource://" + getContext().getPackageName() + "/" + R.drawable.my_avatar_user;
customization.avatarShape = 0;
//是否隐藏左边的访客头像,默认显示头像
customization.hideLeftAvatar = false;
//是否隐藏右边的客服头像,默认显示头像
customization.hideRightAvatar = false;
//在机器人阶段展示发送图片控件
customization.isRobotSendImage = true;
ysfOptions.uiCustomization = customization;

建议 App 在初始化 SDK 前集中配置 YSFOptions,这样首次进入客服界面就能生效;如果业务需要运行时切换样式,可以修改同一个 YSFOptions 后调用 Unicorn.updateOptions(options),新配置会在下次进入会话界面时生效。

界面区域自定义

本节说明输入栏、导航栏、顶部区域和其他界面区域的自定义方式。

自定义输入栏区域

输入栏区域由 InputPanelOptions 配置,并通过 YSFOptions.inputPanelOptions 传给 SDK。开发者可以在初始化 SDK 时或运行期间修改配置;未赋值的项目保留默认表现,修改后在下次进入会话界面时生效。

参数名类型参数说明
inputPanelOptionsInputPanelOptions设置样式参数

InputPanelOptions

参数名类型参数说明取值说明
voiceIconResIdint音频输入图标iddrawable resId
emojiIconResIdint表情输入图标iddrawable resId
photoIconResIdint拍照和相册图标iddrawable resId 当开启输入更多的时候该图标不会生效
moreIconResIdint输入更多(类似于微信 + 号的功能)的图标iddrawable resId
showActionPanelboolean是否开启输入更多功能true 拍照和相册功能被替换为输入更多,false 不开启,输入更多图标也不会生效
actionPanelOptionsActionPanelOptions输入更多弹框里面选项的相关配置参考ActionPanelOptions表格说明

ActionPanelOptions

参数名类型参数说明取值说明
actionListProviderActionListProvider获取"+"出现的 actionlist 的接口drawable resId
backgroundColorint的列表的背景颜色 iddrawable resId

ActionListProvider

"+"出现的 actionlist 的接口回调

接口回调函数说明
ActionListProvider需要实现getActionList接口,用于返回 List<BaseAction> 集合,表示返回"+" 里面需要展示的 action 集合

代码示例

ActionPanelOptions 可以通过设置 backgroundColor 去自定义输入更多弹出框的背景颜色,也可以通过配置 ActionPanelOptions 中的 ActionListProvider 接口去返回弹出框出现的选项列表(如果开启了输入更多功能,但是没配置这个列表,那么列表中会自动加入拍照和相册功能)。

YSFOptions options = new YSFOptions();
options.inputPanelOptions = new InputPanelOptions();
options.inputPanelOptions.showActionPanel = true;
options.inputPanelOptions.moreIconResId = R.drawable.ysf_ic_actionpanel_strat;
options.inputPanelOptions.voiceIconResId = R.drawable.ic_launcher;
options.inputPanelOptions.emojiIconResId = R.drawable.ic_launcher;
options.inputPanelOptions.actionPanelOptions = new ActionPanelOptions();
options.inputPanelOptions.actionPanelOptions.actionListProvider = new ActionListProvider() {
    //实现 getActionList 方法,返回输入更多弹框的列表,SDK 中默认提供了 AlbumAction(相册)、CameraAction(相机)等 Action
    @Override
    public List<BaseAction> getActionList() {
        List<BaseAction> list = new ArrayList<>();
        list.add(new ImageAction(R.drawable.ic_home,R.string.ysf_action_camera_and_album));
        list.add(new SendTextAction(R.drawable.ic_kaola,R.string.ysf_action_text));
        list.add(new SendProductAction(R.drawable.ic_launcher,R.string.ysf_action_product));
        list.add(new DemoAction(R.drawable.ic_kaola,R.string.ysf_action_test));
        list.add(new CameraAction(R.drawable.ic_kaola,R.string.ysf_action_camera));
        list.add(new AlbumAction(R.drawable.ic_kaola,R.string.ysf_action_Album));
        return list;
    }
};
options.inputPanelOptions.actionPanelOptions.backgroundColor = 0xFF0000FF; //自定义输入更多弹框背景颜色

从上面的代码中可以看出列表中的每一个 item 为一个 Action ,SDK 提供了 BaseAction ,您可以继承它去实现你自己的 Action,然后加入列表。BaseAction 中提供了很多可自定义的内容,例如图标和文字,点击事件,还定义了创建文本消息和图片消息的方法。你可以通过如下代码去发送一条文本消息:

public class SendTextAction extends BaseAction {
    /**
     * 构造函数
     *
     * @param iconResId 图标 res id
     * @param titleId   图标标题的string res id
     */
    public SendTextAction(int iconResId, int titleId) {
        super(iconResId, titleId);
    }

    @Override
    public void onClick() {
        //buildTestMessage 为创建消息的方法,sendMessage 为 SDK 提供的发送消息的方法
        MessageService.sendMessage(buildTextMessage("hello world"));
    }
}

在 onClick 里面不仅仅可以发送文本消息,BaseAction 中还提供了 buildImageMessage 方法创建图片消息并发送,也可以在该方法跳转 App 的界面,然后重写 BaseAction 中的 onActivityResult 方法去处理你选择的数据。

自定义右上角按钮样式

可以自定义客服窗口右上角 title 的按钮功能,可以通过配置在 title 的右侧加入一个按钮,按钮的图片字体颜色,点击事件都可以配置,并可以自定义右上角相关按钮图标。

参数名类型参数说明
titleBarConfigTitleBarConfig设置右上角样式参数

TitleBarConfig

参数名类型是否必填参数说明取值说明
titleBarRightImgint否自定义 titlebar 右侧可点击区域的图片drawable resId
titleBarRightTextString否自定义 titlebar 右侧可点击区域的文字文字说明
titleBarRightTextColorint否设置右上角文字颜色(包括评价、商家、人工客服、退出)32 位颜色值
titleBarRightEvaluatorBtnBackint否设置右上角评价按钮背景drawable resId
titleBarRightHumanBtnBackint否设置右上角转人工客服按钮的背景drawable resId
titleBarRightQuitBtnBackint否设置右上角退出会话按钮的背景drawable resId
onTitleBarRightBtnClickListenerOnTitleBarRightBtnClickListener否自定义 titbar 右侧可点击区域的点击事件点击回调

OnTitleBarRightBtnClickListener

自定义 titbar 右侧可点击区域的点击事件

接口回调函数说明
OnTitleBarRightBtnClickListener需要实现onClick接口,表示标题栏右侧按钮点击响应方法

代码示例

/**
 * 设置聊天界面右上角相关配置
 * @return TitleBarConfig
 */
private TitleBarConfig configTitleBar() {
    TitleBarConfig titleBarConfig = new TitleBarConfig();
    //设置右上角退出会话按钮的图标
    titleBarConfig.titleBarRightQuitBtnBack = R.drawable.ic_launcher;
    //设置右上角转人工按钮的图标
    titleBarConfig.titleBarRightHumanBtnBack = R.drawable.ic_launcher;
    //设置右上角评价按钮的图标
    titleBarConfig.titleBarRightEvaluatorBtnBack = R.drawable.ic_launcher;
    //新增右上角按钮的图标
    titleBarConfig.titleBarRightImg = R.drawable.ic_launcher;
    //新增右上角按钮文字的颜色
    titleBarConfig.titleBarRightTextColor = 0XFFDB7093;
    //新增右上角按钮的文字
    titleBarConfig.titleBarRightText = "进店";
    //设置右上角新增按钮点击事件
    titleBarConfig.onTitleBarRightBtnClickListener = new OnTitleBarRightBtnClickListener() {
        @Override
        public void onClick(Activity activity) {
            //implement  
        }
    };

    return titleBarConfig;
}

自定义聊天窗口顶部区域

SDK 加入了聊天界面顶部,App 可以通过实现 AdViewProvider 接口来自定义顶部区域的样式

参数名类型参数说明
imPageViewConfigIMPageViewConfig聊天界面增加的 view 的相关配置信息

代码示例

IMPageViewConfig imPageViewConfig = new IMPageViewConfig();
imPageViewConfig.adViewProvider = new AdViewProvider() {
    @Override
    public View getAdview(Context context) {
    	  //每次进入客服界面都会调用该方法
        final View view = LayoutInflater.from(context).inflate(R.layout.view_ad_parent,null);
        view.setLayoutParams(new LinearLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,
                ViewGroup.LayoutParams.WRAP_CONTENT));
        ((TextView)view.findViewById(R.id.tv_ad_parent_close)).setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                view.setVisibility(View.GONE);
            }
        });
        return view;
    }
};
options.imPageViewConfig = imPageViewConfig;

从上面的代码可以看到,如果想使用该功能,首先我们需要定义一个 IMPageViewConfig ,然后实现一个 AdViewProvider 并赋值给 IMPageViewConfig。最后把 IMPageViewConfig 赋值给 YSFOption 就可以了。当 SDK 在进入客服界面的时候会调用 getAdView 这个方法,App 方可以根据不同的场景返回不同的 view ,达到展示不同广告的效果。

其他界面自定义

SDK 的所有资源文件名均以 nim 或者 ysf 作为前缀,colors 和 strings 中的常量也以 nim 或 ysf 为前缀,以避免污染开发者的资源名字空间。

聊天界面的根 layout 文件为 ysf_message_fragment.xml,通过修改该文件,以及其引用的各子 layout 文件,可以修改聊天界面的框架布局。通过修改其中引用的素材资源,可以修改界面的上各图标,字体,背景等。

SDK 自带的会话界面为 ServiceMessageActivity, 其 theme 为 ysf_window_theme, 如果需要修改标题栏样式,可以修改该 style。 该 style 位于 ysf_styles.xml 中。

如果修改 SDK 中的资源文件,以后升级 SDK 时要注意重新替换,以免又回到默认界面上。

SDK 还提供了以 fragment 嵌入的方式集成会话界面,开发者可以更灵活的使用 SDK。

代码示例

String title = "聊天窗口的标题";
// 访客来源信息
ConsultSource source = new ConsultSource(sourceUrl, sourceTitle, "custom information string");
/**
 * 构造一个 ViewGroup,用于放置sdk的评价和人工客服按钮。
 * 该控件推荐放在标题栏右边。可以用以下两种方式:
 * 1. 将 container 放到 layout 文件中
 * LinearLayout sdkIconContainer = (LinearLayout)findViewById(R.id.xxx);
 * 2. 动态构建,动态添加
 * LinearLayout sdkIconContainer = new LinearLayout(this);
 * sdkIconContainer.setOrientation(LinearLayout.HORIZONTAL);
 * 构造好后,还需要将 ViewGroup 添加到你的 Activity 中
 */
ServiceMessageFragment fragment = Unicorn.newServiceFragment(title, source, sdkIconContainer);
FragmentManager fm = getSupportFragmentManager();
FragmentTransaction transaction = fm.beginTransaction();
// 将 fragment 放到对应的 containerId 中。containerId 为 ViewGroup 的 resId
transaction.replace(containerId, fragment);
try {
    transaction.commitAllowingStateLoss();
} catch (Exception e) {
}

输入栏快捷入口

七鱼 SDK 新增人工客服模式下的快捷入口,快捷入口位于输入框上方,仅在人工客服和留言状态下显示,如开启了后台设置人工的快捷入口设置就失效了。

参数名类型参数说明取值说明
quickEntryListArrayList<QuickEntry>快捷入口列表QuickEntry类型

QuickEntry

参数名类型参数说明
idlong入口ID
nameString入口名字
iconUrlString入口 icon url ,支持的 url 类型由 ImageLoader 决定

代码示例

source.quickEntryList = new ArrayList<>();
source.quickEntryList.add(new QuickEntry(0, "查订单", iconUrl));
source.quickEntryList.add(new QuickEntry(1, "查物流", iconUrl));

运行时与样式选项

本节说明影响界面表现或运行行为的补充配置项。

询分类对话框样式

选择咨询分类时自动弹出对话框的样式

参数名类型参数说明取值说明
categoryDialogStyleint设置样式参数默认为0,表示为消息流样式1 表示从中间弹出2 表示从底部弹出

这些运行时配置项都设置在 YSFOptions 上。App 一般在初始化前按自身策略设置;如果用户在设置页修改了开关,可以更新配置后调用 Unicorn.updateOptions(options)。

YSFOptions options = new YSFOptions();
options.categoryDialogStyle = 2;
options.isUseSAF = true;
options.openFileSizeStatistics = true;
options.isDisableNetworkTrace = true;
options.isConfigMediaVisualUserSelected = true;

Unicorn.config(context, appKey, options, imageLoader);

是否使用 SAF 模式

是否使用Android存储访问框架

参数名类型参数说明取值说明
isUseSAFboolean是否使用 SAF 模式国内版默认为false,海外版默认为true

是否开启文件大小统计

是否开启文件大小统计,开启后与七鱼SDK相关的文件大小会记录在本地日志

参数名类型参数说明取值说明
openFileSizeStatisticsboolean是否开启文件大小统计默认为false,表示不开启

是否禁用网络检测

是否禁用网络检测,当网络不好的情况下会自动进行网络检测,如果您不希望进行检测,可以手动关闭

参数名类型参数说明取值说明
isDisableNetworkTraceboolean是否禁用网络检测默认为false,表示不开启

已选照片访问权限

适配Android14,是否在AndroidManifest.xml中配置了android.permission.READ_MEDIA_VISUAL_USER_SELECTED权限

参数名类型参数说明取值说明
isConfigMediaVisualUserSelectedboolean是否配置已选照片选择权限默认为false,如配置该权限,请设置为true

隐私开关配置

SDK 提供以下隐私相关配置项,接入方可根据 App 合规策略控制剪切板、距离传感器和屏幕显示参数的使用。

参数名类型参数说明取值说明
messageCopyBtnSwitchboolean是否允许通过消息长按复制入口写入剪切板默认为 true,表示允许复制;设置为 false 后,文本消息或 CopyableAttachment 消息不展示长按复制入口
proximitySensorEnableboolean语音消息播放时是否允许 SDK 使用距离传感器默认为 true,表示允许使用;设置为 false 后,SDK 不会初始化、查询或注册距离传感器
screenDisplayMetricsDisplayMetrics接入方提供的完整屏幕显示参数,用于 SDK 的屏幕宽高、密度和字体缩放计算默认为 null,SDK 使用自身上下文读取屏幕参数;非空时优先使用接入方传入的 DisplayMetrics,且 widthPixels、heightPixels 应为有效正值

代码示例

YSFOptions options = new YSFOptions();

// 禁止消息长按复制写入剪切板
options.messageCopyBtnSwitch = false;

// 禁止语音播放时使用距离传感器
options.proximitySensorEnable = false;

// 如需由宿主 App 提供屏幕显示参数,建议传入系统完整的 DisplayMetrics,
// 避免遗漏 density、scaledDensity 等尺寸换算参数
options.screenDisplayMetrics = context.getResources().getDisplayMetrics();

自定义功能

本节收纳自定义功能相关的基础说明和平台补充内容。

在SDK中,可自定义配置项,配置项在YSFOptions对象中,初始化YSFOptions对象。

YSFOptions options = new YSFOptions();

自定义 gif 表情加载器

当加载格式为 gif 表情的时候会调用此方法

参数名类型参数说明取值说明
gifImageLoaderUnicornGifImageLoader自定义 gif 表情加载器默认不实现,使用图片加载器加载gif

UnicornGifImageLoader

UnicornGifImageLoader 用于加载 gif 图片,主要应用于 gif 表情。

接口回调函数说明
UnicornGifImageLoader需要实现loadGifImage方法

代码示例

public class GlideGifImagerLoader implements UnicornGifImageLoader, Serializable {

    Context context;

    public GlideGifImagerLoader(Context context) {
        this.context = context.getApplicationContext();
    }


    @Override
    public void loadGifImage(String url, ImageView imageView, String imgName) {
        if (url == null || imgName == null) {
            return;
        }
        Glide.with(context).load(url).placeholder(R.drawable.ic_launcher).error(R.drawable.nim_default_img_failed).into(imageView);
    }
}

修改设置

SDK提供了修改自定义样式的代码,该方法是对象直接赋值,不是对之前的设置进行更新。

代码示例

Unicorn.updateOptions(YSFOptions options);

这篇文档有帮助吗?

目录