美忆客服 · 使用指南美忆客服 · 使用指南
新手入门
管理员手册
客服手册
网站接入
常见问题
新手入门
管理员手册
客服手册
网站接入
常见问题
  • 开始使用

    • 第一次使用美忆客服
    • 商户管理员手册
    • 客服操作手册
  • 网站接入

    • 接入美忆客服
    • 传入客户身份资料
    • 浏览器端接入示例
    • 服务端语言接入示例
    • 常见接入问题
  • 问题排查

    • 常见问题排查

浏览器端接入示例

网页客服不依赖 Vue。原生 HTML、React、Vue、Nuxt、Next.js 或服务端生成的页面,都可以加载商户后台提供的同一份客服脚本。无需部署客服窗口,也不需要安装客服专用前端框架。

你的网站从哪里开始
普通 HTML、静态站点、jQuery 页面最简单的 HTML 接入
页面已有当前登录用户资料通用加载函数
Vue 3、NuxtVue 3 与 Nuxt
React、Next.jsReact 与 Next.js
PHP、Python、Java、Node.js、Go、ASP.NET服务端语言示例

接入前准备

  1. 商户后台的渠道已启用,套餐有效。
  2. 从 接入渠道 → 渠道接入 → 网站嵌入 复制脚本地址和渠道标识。
  3. 要传 identity.username 时,先在 客户身份字段 新建标识为 username 的字段。name 是内置参数,不需要新建字段。
  4. 官方客服脚本地址为 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 等框架只决定何时执行这段浏览器代码,不影响客服渠道或资料格式。

登录、退出与切换账号

  1. 当前页面先完成业务登录状态判断,再加载客服。
  2. 登录、退出或切换到另一个业务账号后,重新加载整个网页。
  3. 新页面按新账号设置资料,再加载客服脚本。

例如网站完成退出请求后使用 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>;
    };
  }
}
Prev
传入客户身份资料
Next
服务端语言接入示例