NoPaperManuals™

Documentation

Technique

白标 (Whitelabel) 技术准则

3级白标集成与部署的完整指南。

Dernière mise à jour : 23/03/2026

白标 (Whitelabel) 技术规格

本文档定义了 NoPaperManuals™ 在白标模式下的基础设施配置标准。

[!NOTE] 根据您的技术需求，我们提供3个渐进式的集成等级：

等级 1 (Level 1)：DNS 委托（通过颜色和徽标进行的简单定制）。

等级 2 (Smart Embedded)：智能嵌入（通过 Iframe 顺畅集成至您现有的网站）。

等级 3 (Reverse Proxy)：反向代理（远程获取以注入您完整的原生 HTML）。

🚀目标

其目标是确保主站点与产品目录之间的平滑过渡，并在整个过程中保持您的视觉形象（品牌定制）和导航架构。


🔗 集成级别和定制

根据您的品牌需求和技术资源，我们提供三个级别的集成。

Level 1

DNS 授权

在几分钟内将您自己的子域名重定向到我们的服务器。

最适合:

希望立即设置的草创公司和中小企业。

自定义域名 (docs.brand.com)
自定义颜色和徽标
Portal Lite (标准版)
自动 SSL 证书
设置时间< 5 分钟
Level 2

智能嵌入

通过智能 iframe 将 NoPaperManuals 嵌入到您的网站中。

最适合:

希望保留导航栏的电子商务或支持网站。

无代码集成
优化的 'Portal Lite' UI（无页眉）
智能自动调整大小
在外壳中流畅导航
设置时间~ 15 分钟
Level 3

反向代理 (Shell)

终极集成，NoPaperManuals 成为您网站的原生部分。

最适合:

要求完美 SEO 和用户体验的大型集团。

零 Iframe（原生集成）
最佳 SEO（根域名上的内容）
远程获取（动态页眉）
通过代理密钥确保安全
设置时间自定义
安全说明: 所有模式均受益于完全的数据隔离（多租户）和 AES-256 加密。



🎨 等级 1：DNS 委托 (品牌外观微调)


对于 DNS 委托，客制化被设计为简单、快速，并将由我们的技术团队进行配置。


1. 域名配置 (CNAME)

您必须首先为您的说明书选择一个专用的子域名（例如 manuals.your-brand.com）。 然后，在您域名的 DNS 管理界面中，您需要创建一个指向我们基础设施的 CNAME 记录：fallback.nopapermanuals.com。


2. 我们可以为您定制的内容：

  • 视觉形象：上传您的高分辨率徽标和自定义网站图标 (Favicon)。

  • 调色板：定义您的“强调色”，将应用于按钮和活动元素。

  • 快速导航栏 (页眉)：配置简单菜单（链接名称，URL）以重建对您主要页面的访问。

  • 页面底部 (页脚)：整合指向您社交网络和法律声明页面的链接。




🧩 等级 2：智能嵌入 (Iframe 集成)


“智能嵌入” 方法非常适合将说明书直接集成到您的电子商务网站 (Shopify, PrestaShop) 或您现有的支持内容管理系统中。

此方法使您可以摆脱 NoPaperManuals 页眉或页脚的设计限制，同时保证物理二维码的扫描能将您的客户重定向到 您的 环境。


1. Host URL 配置

在与我们的团队配置您的白标帐户时，您必须提供托管 Iframe 的确切 URL（例如：https://support.your-brand.com/manuals）。


2. 嵌入 JS 脚本 (Snippet)

我们的技术团队将直接为您提供预先为您的特定品牌配置的 Javascript 代码段。当用户扫描二维码 (?npm_shortcode=XYZ) 时，此代码会读取 URL 并动态创建我们 Iframe 的 URL (https://nopapermanuals.com/s/XYZ?embedded=true)。

<!-- 您的页面上 Iframe 的目标位置 -->
<iframe id="npm-iframe" style="width:100%; height:100vh; border:none;"></iframe>

<script>
  // 1. 从 URL 中读取 'npm_shortcode' 参数
  const params = new URLSearchParams(window.location.search);
  const shortcode = params.get('npm_shortcode');
  
  // 2. 定义 iframe 的最终 URL（无初始菜单的极简模式）
  const iframeUrl = shortcode 
    ? `https://nopapermanuals.com/s/${shortcode}?embedded=true` 
    : `https://nopapermanuals.com/tenant/your-identifier?embedded=true`;

  // 3. 透明地加载内容
  document.getElementById('npm-iframe').src = iframeUrl;
</script>

3. 扫描期间的用户旅程

  • 第 1 步：用户扫描您产品上的二维码 (qrmanual.app/ABC)。
  • 第 2 步：我们的服务器检测到此产品处于 Smart Embedded 模式。
  • 第 3 步：用户被立即重定向到您的页面：https://support.your-brand.com/manuals?npm_shortcode=ABC。
  • 第 4 步：代码段读取 "ABC"，从 NoPaperManuals 加载说明书，并将其实例化注入此页面。您的用户将 留在您的域名上。



🚀 等级 3：反向代理 (Shell 模式)


代理模式 (Reverse Proxy) 是最高级的集成方式。它允许将 NoPaperManuals 完全合并到您自身的 Web 基础设施核心中。

内容是 直接从您的域名 分发的，这在搜索引擎优化 (SEO) 方面达到最佳效果，并提供最透明的体验。


通过“远程获取”进行定制 (动态)

为了不必手动重新创建您的菜单，NoPaperManuals 会通过特定的 URL 实时获取您页眉和页脚的片段。

  • 主要优势：100% 自动同步。您主站点的任何修改都会立刻反映在“说明书”部分中。
  • 技术前提：您必须提供仅返回您的页眉和页脚结构的 HTML 端点（不能包含全局标签 <body> 或 <html>）。

🔒 保护通信安全

您的基础设施与 NoPaperManuals 之间的“服务器到服务器 (Server-to-Server)”通信必须受到严格的安全 Header 认证，以防范任何身份欺骗：

| HTTP Header | 预期值 | | :--- | :--- | | X-NPM-Custom-Host | 您的官方域名名称（例如 manuals.your-brand.com） | | X-NPM-Proxy-Secret | 您的加密密钥（与我们的技术团队共享） |

[!WARNING] 关键保护功能活跃 如果 X-NPM-Proxy-Secret Header 丢失、不正确或被泄露，NoPaperManuals 防火墙将拒绝提供内容，以保护您品牌的完整性。


⚙️ 必需的架构：独立的子域名

对于单页面应用程序 (SPA)，反向代理必须 强制 定位在专用的子域（例如：manuals.your-brand.com），并截获此域名根目录 / 处的流量。

[!WARNING] 我们强烈不建议对子文件夹（例如 your-brand.com/manuals/）进行配置。它需要技术验证以避免与我们的资产（/_next/，/api/ 等等）发生冲突。在 95% 的情况下，我们推荐的解决方案是子域名。


🛠️ Nginx 范例

需使用的标准 Nginx server 块级模版：

server {
    listen 443 ssl http2;
    server_name manuals.your-brand.com;
    
    # 1. 有效的 SSL 证书（需由您自行维护）
    ssl_certificate /path/to/cert/fullchain.pem;
    ssl_certificate_key /path/to/cert/privkey.pem;
    
    location / {
        # 2. 将代理设置指向 NoPaperManuals 根目录
        proxy_pass https://nopapermanuals.com/;
        
        # 3. 必要的安全性 Headers
        proxy_set_header X-NPM-Custom-Host "your-brand.com";
        proxy_set_header X-NPM-Proxy-Secret "YOUR_CRYPTOGRAPHIC_SECRET";
        
        # 4. 常规传输 Headers
        proxy_ssl_server_name on;
        proxy_set_header Host nopapermanuals.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}



🛠️ 验证与部署


  • 视觉验证：在投入生产环境之前，为了验证您的颜色、徽标和品牌选项的渲染效果，我们可以为您设置一个专属的测试环境。请联系我们以进行激活。

  • 安全测试：（仅限等级 3）确保您的安全 Headers 被正确配置并生效中。


[!NOTE] 我们的技术支持团队对您的品牌设置进行的任何更新，都会实时应用到您的白标域名上。

NoPaperManuals™ - Documentation de spécifications whitelabel