浏览器端接入示例
网页客服不依赖 Vue。原生 HTML、React、Vue、Nuxt、Next.js 或服务端生成的页面,都可以加载商户后台提供的同一份客服脚本。无需部署客服窗口,也不需要安装客服专用前端框架。
| 你的网站 | 从哪里开始 |
|---|---|
| 普通 HTML、静态站点、jQuery 页面 | 最简单的 HTML 接入 |
| 页面已有当前登录用户资料 | 通用加载函数 |
| Vue 3、Nuxt | Vue 3 与 Nuxt |
| React、Next.js | React 与 Next.js |
| PHP、Python、Java、Node.js、Go、ASP.NET | 服务端语言示例 |
接入前准备
- 商户后台的渠道已启用,套餐有效。
- 从 接入渠道 → 渠道接入 → 网站嵌入 复制脚本地址和渠道标识。
- 要传
identity.username时,先在 客户身份字段 新建标识为username的字段。name是内置参数,不需要新建字段。 - 官方客服脚本地址为
https://meiyi.chat/chat/widget.js,聊天入口为https://meiyi.chat/chat/。请优先复制后台生成的代码,其中已包含你的渠道标识。
各方案任选一种,同一页面不要同时保留原嵌入代码和动态加载代码。
最简单的 HTML 接入
把以下两段代码依次放在现有网页的 </body> 前。静态演示可使用固定资料;正式网站应替换为当前登录用户的资料。
<script>
window.MeiyiSettings = {
name: "Alice",
identity: { username: "alice" }
};
</script>
<script
src="https://meiyi.chat/chat/widget.js"
data-channel="YOUR_CHANNEL_ID"
defer
></script>
没有登录的匿名用户,可以省略第一段,后台会显示“访客001”等编号。name 用作显示名称;其他字段见 客户身份说明。
使用 jQuery 的现有页面也可直接采用此代码,无须用 jQuery 再加载一次脚本。
通用加载函数
网站需要先请求当前用户资料,或使用单页应用时,可复用以下函数。将它保存到你现有网站的一个 JavaScript 模块,例如 src/lib/customer-support.js;普通 HTML 网站可以保存到 /assets/customer-support.js。
只需修改顶部的脚本地址和渠道标识。此函数用于你的网站,不是需要单独部署的客服前端。
const WIDGET_URL = "https://meiyi.chat/chat/widget.js";
const CHANNEL_ID = "YOUR_CHANNEL_ID";
let loading;
let identityKey;
export function mountCustomerSupport(settings = {}) {
if (typeof window === "undefined") return Promise.resolve();
const identity = Object.fromEntries(
Object.entries(settings.identity || {})
.filter(([, value]) => value !== null && value !== undefined)
.map(([key, value]) => [key, String(value)])
);
const name = String(settings.name || "").trim();
const key = JSON.stringify([
name,
Object.entries(identity).sort(([a], [b]) => a.localeCompare(b))
]);
if (loading) {
if (key !== identityKey) {
return Promise.reject(new Error("客户资料已变化,请刷新页面后重新接入客服。"));
}
return loading;
}
if (document.querySelector("[data-meiyi-widget], script[data-meiyi-loader]")) {
return Promise.reject(new Error("页面已有客服入口,请勿重复加载。"));
}
// 必须先设置资料,再加载脚本。
window.MeiyiSettings = { name, identity };
identityKey = key;
loading = new Promise((resolve, reject) => {
const script = document.createElement("script");
script.src = WIDGET_URL;
script.dataset.channel = CHANNEL_ID;
script.dataset.meiyiLoader = "true";
script.onload = () => resolve();
script.onerror = () => {
script.remove();
loading = undefined;
identityKey = undefined;
reject(new Error("客服脚本加载失败,请检查网络与接入地址。"));
};
document.body.appendChild(script);
});
return loading;
}
Promise 表示脚本已加载,浮窗随后读取渠道外观并显示。该函数没有在线身份切换或销毁接口;业务账号变化时,按后文说明刷新页面。
示例只传字符串、数字等简单字段,不要把整个用户对象、密码或登录令牌传给客服。传入字段必须已在商户后台配置,最多 20 个,每个值最多 500 字符;name 最长 100 字符。
原生 JavaScript 与异步用户资料
下面的 /account/current-user 指你自己网站已有的当前用户接口,不是平台提供的地址。将接口及字段名换成网站实际使用的值。请在网站确认登录状态后再接入,避免先建立匿名身份、随后又加载一次。
<script type="module">
import { mountCustomerSupport } from "/assets/customer-support.js";
async function startSupport() {
const response = await fetch("/account/current-user", {
credentials: "same-origin"
});
if (response.status === 401) {
await mountCustomerSupport({});
return;
}
if (!response.ok) throw new Error("暂时无法读取当前用户资料");
const user = await response.json();
await mountCustomerSupport({
name: user.displayName || user.username,
identity: { username: user.username }
});
}
startSupport().catch(() => {
console.warn("客服入口暂未加载,请稍后刷新页面。");
});
</script>
若你的网站没有这个接口,直接使用页面里已有的登录用户数据,或采用 服务端语言示例,不必为了客服另建一套登录系统。
Vue 3 与 Nuxt
在现有应用的根布局中接入一次,等登录状态加载完成后传入资料。下面的 authReady 和 user 由你的网站提供。
<script setup>
import { watch } from "vue";
import { mountCustomerSupport } from "./lib/customer-support.js";
const props = defineProps({
authReady: Boolean,
user: { type: Object, default: null }
});
watch(
() => props.authReady,
(ready) => {
if (!ready) return;
mountCustomerSupport(
props.user
? {
name: props.user.displayName || props.user.username,
identity: { username: props.user.username }
}
: {}
).catch(() => console.warn("客服入口暂未加载,请稍后刷新页面。"));
},
{ immediate: true }
);
</script>
<template><slot /></template>
Nuxt 中将此组件放在根布局,并用 <ClientOnly> 包裹;资料准备好再将 authReady 设为 true。服务端渲染阶段不操作 window 或 document。后台菜单或网站路由切换不应重复添加客服入口。
在现有页面中可用 <CustomerSupport :auth-ready="auth.ready" :user="auth.user" /> 挂载以上组件。auth 表示网站已有的登录状态,不是客服 SDK;匿名用户也要等登录检查结束后,才将 ready 设为 true。
React 与 Next.js
组件挂在应用根布局。Next.js App Router 使用客户端组件;普通 React 项目也可使用同一写法。
"use client";
import { useEffect } from "react";
import { mountCustomerSupport } from "./lib/customer-support.js";
export default function CustomerSupport({ authReady, user }) {
const name = user?.displayName || user?.username || "";
const username = user?.username || "";
const signedIn = Boolean(user);
useEffect(() => {
if (!authReady) return;
mountCustomerSupport(
signedIn ? { name, identity: { username } } : {}
).catch(() => console.warn("客服入口暂未加载,请稍后刷新页面。"));
}, [authReady, signedIn, name, username]);
return null;
}
在现有根布局中挂载 <CustomerSupport authReady={auth.ready} user={auth.user} />。这里的 auth 由网站已有登录状态提供。
示例加载函数会复用同一个加载任务,React 开发环境的 Strict Mode 重复运行 effect 时,不会因为同一份资料重复插入脚本。不要在组件 effect 的清理函数中只删除浮窗 DOM:这不会同时清理宿主脚本监听和访客身份。
Angular、Svelte 或其他前端
复用通用加载函数,在浏览器端组件挂载、且用户资料准备好之后调用一次即可。不要放在每次渲染、每次数据变更都会运行的函数里。
await mountCustomerSupport({
name: currentUser.displayName || currentUser.username,
identity: { username: currentUser.username }
});
这里的 currentUser 代表网站已确认的当前用户。Vue、React 等框架只决定何时执行这段浏览器代码,不影响客服渠道或资料格式。
登录、退出与切换账号
- 当前页面先完成业务登录状态判断,再加载客服。
- 登录、退出或切换到另一个业务账号后,重新加载整个网页。
- 新页面按新账号设置资料,再加载客服脚本。
例如网站完成退出请求后使用 window.location.reload();若网站登录流程本就完整跳转页面,使用原有跳转即可。仅修改 window.MeiyiSettings、切换前端路由或删除入口按钮,不能完成客服身份切换。
当前没有对外的在线切换身份 SDK。不同资料对应独立访客身份,不会按同名用户名自动合并不同浏览器的历史会话。
TypeScript 项目
上面的加载器使用普通 JavaScript。使用 TypeScript 的项目可以在加载器旁添加 customer-support.d.ts,为导入函数提供类型:
export interface SupportSettings {
name?: string;
identity?: Record<string, string | number | boolean | null | undefined>;
}
export function mountCustomerSupport(settings?: SupportSettings): Promise<void>;
这只是你网站内加载函数的类型声明,不需要安装额外的客服包。若项目直接在 TypeScript 中设置 window.MeiyiSettings,也可以在现有全局声明文件中添加:
export {};
declare global {
interface Window {
MeiyiSettings?: {
name?: string;
identity?: Record<string, string>;
};
}
}
