一、综述

1. 站点接入方式

可以在如下位置添加“帮助中心”链接，点击后进入帮助中心首页：

1. 官网导航

2. 产品内（网页版、H5版）导航

2. 数据接入的内容和方式

魔音帮助中心不管理您系统的用户信息，用户的增删改等管理工作均在您自己的系统内完成，但魔音提供基于用户ID和客户ID的数据分析功能，您可以通过用户ID和客户ID来查询用户访问帮助中心的情况：

• 用户ID，即visitorId，指的是访问者本身的ID

• 客户ID，即accountId，指的是访问者所在组织的ID当用户访问帮助中心的页面时，需要您把这两个数据告诉我们，具体方式参见第二部分当然，您也可以选择不接入这两个参数，那样就无法使用我们的数据分析功能

3. 数据安全保障

魔音不记录、不存储除ID之外的其他用户信息，无需担心数据泄密。

二、技术对接方案

（一） 域名对接

1. 使用自定义域名（推荐☆☆☆）

例如您的官网域名是 www.xxx.com ， 那么帮助中心可以使用 doc.xxx.com，接入方法是：

注意：

• 使用cname需要将doc.xxx.com的证书放到魔音服务器进行托管，否则https访问会受限，同时需要您的域名在阿里云上有备案（如果没有，则参考https://help.aliyun.com/knowledge_detail/36924.html

  ）

• 如果不使用cname方式，还有一个方法是使用nginx直接在内部转发请求至xxx.dochelp.cn，由您的运维人员直接操作内部重定向即可

2. 使用魔音提供的域名

3. 使用您现有的域名+二级目录

例如您现有的域名是 xxx.com，您可以使用 xxx.com/helpcenter （或xxx.com/doc），方法是:

• 将xxx.com/helpcenter 开头的请求转发至 xxx.dochelp.cn，需要网站运维人员配置

• 以下是Nginx的参考配置：

location /helpcenter/ {
  proxy_pass      http://xxx.dochelp.cn/;
  proxy_redirect  off;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

（二）用户对接

即如何将您系统的用户ID和客户ID传入到帮助中心的页面，通常有以下三种方式：

1. 通过URL参数传递（推荐☆☆☆）

• 当用户在官网点击“帮助中心”时，您需要将visitorId和accountId两个参数拼接到帮助中心的链接里，这是最简洁的方式。

例如，如果帮助中心的链接是 https://doc.xxx.com ，当用户访问时需要在该链接上加两个参数：https://doc.xxx.com/?visitorId={visitorId}&accountId={acountId} ，这样访客的ID就传给了帮助中心

• 可以设定是否允许匿名访问，如果不允许匿名访问帮助中心，则当两个参数没有传过来时，我们会将页面重定向到默认登录页，需要告知我们默认登录页的URL

• 该默认登录页最好支持登录完成后跳回原页面，用户体验较好

2. 通过cookie隐式传递

使用该方法有一个前提：必须使用自定义域名，即 您的系统域名（xxx.com）和帮助中心的域名（doc.xxx.com）同属于同一个一级域名（xxx.com），方法如下：

• 当用户登录业务系统时，将visitorId和accountId写入cookie，注意cookie.Domain必须设置为一级域名（即 xxx.com），cookie.Path设置为“/”

• 如果不允许匿名访问帮助中心，当帮助中心检查到没有这两个cookie或cookie过期时，我们会将页面重定向到登录页，需要告知我们登录页的URL，且登录页需要支持登录完成后跳回原页面

3. 通过SSO（单点登录系统）传递

如果您有SSO系统，通常为oauth2协议，需要您提供：

• SSO对接文档，需要描述清楚实现原理、接口文档及页面跳转流程，通常需要以下信息：

  1. 用户认证URL，当未登录时跳转至该网址，携带当前URL地址，完成后跳回并携带code值

  2. 使用code换取用户信息的接口或方法

• SSO对接环境，通常包括：

  • 分配的账号ID、密钥

  • 测试用户账号及密码

  • 可以调试用的认证URL