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

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

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

    • 常见问题排查

服务端语言接入示例

PHP、Python、Java、Node.js、Go、ASP.NET 等网站接入的是同一个托管客服窗口。服务端只需把自己网站已登录用户的名称和需要展示的资料放进页面,再由浏览器加载客服脚本。无需安装对应语言的客服 SDK,也无需部署平台服务。

前后端分离项目:服务端沿用现有登录与用户资料接口,浏览器按 原生 JavaScript、Vue 或 React 示例 接入。下文适用于服务端渲染 HTML 的网站,不要把这些模板语法复制到 Vue/React 文件里。

网站技术示例
PHP、LaravelPHP 与 Laravel
Python DjangoDjango
Python FlaskFlask
Python FastAPI + Jinja2FastAPI 与 Jinja2
Java Spring Boot + ThymeleafJava Spring Boot
Node.js Express + EJSNode Express
Go html/templateGo
C# ASP.NET Core RazorASP.NET Core Razor

公共页面代码

以下示例统一输出一个 ID 为 meiyi-user 的 JSON 数据块。将 通用加载函数 保存到现有网站的 /assets/customer-support.js,在页面底部加入下面的代码。

<script type="module">
  import { mountCustomerSupport } from "/assets/customer-support.js";
  const data = document.getElementById("meiyi-user");
  const customer = data ? JSON.parse(data.textContent || "{}") : {};
  mountCustomerSupport(customer).catch(() => {
    console.warn("客服入口暂未加载,请稍后刷新页面。");
  });
</script>

在通用加载函数中,替换成后台复制的脚本地址与渠道标识。以下仅使用 username 自定义字段,接入前先在商户后台配置;name 是内置显示名称,无需配置。

JSON 数据仍属于浏览器可见内容,只输出接待需要的资料。不要输出密码、私钥、登录 Cookie 或访问令牌,也不要通过客服链接的查询参数传完整客户资料。

PHP 与 Laravel

普通 PHP 页面

$currentUser 使用你现有登录系统读取的当前用户,未登录时为 null。下面的数据结构仅是示例,请替换键名。

<?php
// $currentUser 由网站原有登录逻辑提供。
$supportUser = $currentUser ? [
    'name' => ($currentUser['display_name'] ?? '') ?: $currentUser['username'],
    'identity' => ['username' => (string) $currentUser['username']],
] : new stdClass();

$supportJson = json_encode(
    $supportUser,
    JSON_UNESCAPED_UNICODE | JSON_HEX_TAG | JSON_HEX_AMP
        | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_THROW_ON_ERROR
);
?>
<script id="meiyi-user" type="application/json"><?= $supportJson ?></script>

之后加入本页的公共页面代码。保留上述 JSON 转义选项,不要把客户昵称直接拼进 JavaScript 引号中。

Laravel Blade

控制器用现有登录用户生成 $supportUser,只输出需要的字段;页面使用 Blade 默认带 HTML 安全转义标志的 @json。

$user = $request->user();
$supportUser = $user ? [
    'name' => $user->name,
    'identity' => ['username' => (string) $user->getAuthIdentifier()],
] : new stdClass();
return view('account', compact('supportUser'));
<script id="meiyi-user" type="application/json">@json($supportUser)</script>

这里 username 使用登录系统用户标识作为示例;如果网站有独立的用户名字段,可以替换。不要把密码哈希或完整用户模型直接交给 @json。

Django

视图从 Django 已确认的 request.user 读取资料。

from django.shortcuts import render

def account(request):
    user = request.user
    support_user = {}
    if user.is_authenticated:
        support_user = {
            "name": user.get_full_name() or user.get_username(),
            "identity": {"username": user.get_username()},
        }
    return render(request, "account.html", {"support_user": support_user})

模板:

{{ support_user|json_script:"meiyi-user" }}

json_script 会生成 JSON 数据块并处理 HTML 转义。之后加入公共页面代码,不要给用户资料加 safe 直接输出。

Flask

下面使用网站已有的 Flask-Login 用户对象;采用其他登录方案时,换成对应的当前用户。

from flask import render_template
from flask_login import current_user

def account():
    support_user = {}
    if current_user.is_authenticated:
        support_user = {
            "name": str(current_user.username),
            "identity": {"username": str(current_user.username)},
        }
    return render_template("account.html", support_user=support_user)

Jinja2 模板:

<script id="meiyi-user" type="application/json">{{ support_user|tojson }}</script>

之后加入公共页面代码。使用 Jinja2 的 tojson,不直接拼接昵称。

FastAPI 与 Jinja2

下面的 request.state.user 由你自己网站已有的登录中间件或依赖准备。示例不提供登录实现;如果使用依赖注入获得用户,直接使用依赖返回的对象。

from fastapi import Request
from fastapi.templating import Jinja2Templates

templates = Jinja2Templates(directory="templates")

# 将该处理函数挂到网站现有路由。
async def account(request: Request):
    user = getattr(request.state, "user", None)
    support_user = {}
    if user is not None:
        support_user = {
            "name": str(user.username),
            "identity": {"username": str(user.username)},
        }
    return templates.TemplateResponse(
        request=request,
        name="account.html",
        context={"support_user": support_user},
    )

account.html 中使用与 Flask 相同的 Jinja2 JSON 数据块,再加入公共页面代码。FastAPI 如果只提供 JSON 接口、前端另用 Vue/React,则采用浏览器端接入示例,不需要改成模板页面。

Java Spring Boot

Spring MVC 从已有认证上下文的 Principal 读取用户名,用 Jackson 序列化后转义 HTML 敏感字符,再传给 Thymeleaf。

// 放入网站现有控制器;json 是注入的 ObjectMapper。
@GetMapping("/account")
public String account(Principal principal, Model model)
        throws JsonProcessingException {
    Map<String, Object> supportUser = new LinkedHashMap<>();
    if (principal != null) {
        String username = principal.getName();
        supportUser.put("name", username);
        supportUser.put("identity", Map.of("username", username));
    }
    String safeJson = json.writeValueAsString(supportUser)
        .replace("<", "\\u003c")
        .replace(">", "\\u003e")
        .replace("&", "\\u0026");
    model.addAttribute("supportUserJson", safeJson);
    return "account";
}

代码使用 java.security.Principal、Spring 的 Model、Jackson 的 ObjectMapper/JsonProcessingException 与 java.util 集合;示例假设 Java 9 及以上。json 请使用网站配置的 ObjectMapper。

Thymeleaf 页面:

<script id="meiyi-user" type="application/json"
        th:utext="${supportUserJson}"></script>

之后加入公共页面代码。th:utext 只能接收上面序列化并转义后的 safeJson,不能直接接收客户昵称或拼接字符串。这里输出的 {} 表示匿名。

Node Express

使用网站已有认证中间件提供的 req.user,示例模板引擎为 EJS。

function jsonForHtml(value) {
  return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (char) =>
    "\\u" + char.charCodeAt(0).toString(16).padStart(4, "0")
  );
}

app.get("/account", (req, res) => {
  const user = req.user;
  const supportUser = user
    ? {
        name: user.displayName || user.username,
        identity: { username: String(user.username) }
      }
    : {};
  res.render("account", { supportUserJson: jsonForHtml(supportUser) });
});

EJS 模板:

<script id="meiyi-user" type="application/json"><%- supportUserJson %></script>

之后加入公共页面代码。这里用未转义输出,是因为 jsonForHtml 已经处理 HTML 敏感字符;不要改成直接输出 req.user 或手工拼接 JSON。

Go

使用 encoding/json 默认的 HTML 安全转义。下面的 currentUser 来自网站现有的认证中间件;page 是已解析的 html/template 页面。

type SupportIdentity struct {
    Username string `json:"username"`
}
type SupportUser struct {
    Name string `json:"name,omitempty"`
    Identity *SupportIdentity `json:"identity,omitempty"`
}
type PageData struct {
    SupportUserJSON template.JS
}

// 放入现有 HTTP handler 中。
customer := SupportUser{}
if currentUser != nil {
    customer.Name = currentUser.Username
    customer.Identity = &SupportIdentity{Username: currentUser.Username}
}
raw, err := json.Marshal(customer)
if err != nil {
    http.Error(w, "无法生成页面", http.StatusInternalServerError)
    return
}
err = page.Execute(w, PageData{SupportUserJSON: template.JS(raw)})

Go 模板:

<script id="meiyi-user" type="application/json">{{.SupportUserJSON}}</script>

需要导入 encoding/json、html/template、net/http。template.JS 只能包裹 json.Marshal 默认转义后的 JSON,不能包裹用户原始输入;不要关闭 JSON 编码器的 HTML 转义。之后加入公共页面代码。

ASP.NET Core Razor

在现有 .cshtml 页面中,读取 ASP.NET 已确认的登录用户。默认 System.Text.Json 序列化器会转义 HTML 敏感字符。

@using System.Text.Json
@{
    var username = User.Identity?.IsAuthenticated == true
        ? User.Identity.Name ?? ""
        : "";
    var supportUser = string.IsNullOrEmpty(username)
        ? new { name = "", identity = new Dictionary<string, string>() }
        : new {
            name = username,
            identity = new Dictionary<string, string> { ["username"] = username }
        };
    var supportUserJson = JsonSerializer.Serialize(supportUser);
}
<script id="meiyi-user" type="application/json">@Html.Raw(supportUserJson)</script>

需要时添加 @using System.Collections.Generic。之后加入公共页面代码。保留默认 JSON 编码器,不使用 UnsafeRelaxedJsonEscaping,也不要把原始用户名直接交给 Html.Raw。

其他服务端语言

只要能输出 HTML 和 JSON,都可以使用同一方式:

  1. 从网站现有登录状态读取当前用户。
  2. 仅选择需要展示的姓名、用户名等字段。
  3. 使用语言的 JSON 序列化器,并保留 HTML 安全转义,将结果放进 meiyi-user 数据块。
  4. 浏览器执行公共页面代码,设置资料后加载平台脚本。

字符串中出现引号、中文或 </script> 时,也必须能安全输出。不要用字符串拼接代替 JSON 序列化,普通 HTML 实体转义也不能直接替代 JSON 编码。

接入形式只决定资料如何到达浏览器,不改变访客身份的有效期和隔离规则。登录、退出或切换账号后,请完整刷新页面;详见 登录与身份切换。

Prev
浏览器端接入示例
Next
常见接入问题