集成协作提供者

协作提供者与协作后端一起，构成了实时协同编辑的基础架构。它们建立并管理用户之间的通信通道，确保文档的更新和更改在所有参与者之间同步。

提供者处理实时数据交换的复杂性，包括冲突解决、网络可靠性和用户在线状态感知。

TiptapCollabProvider 增加了针对协作环境的高级功能，如 WebSocket 消息认证、调试模式和灵活的连接策略。

设置提供者

首先，在您的项目中使用以下命令安装提供者包（确保使用提供者 v2，因为 v3 需要 Tiptap v3，而 Tiptap v3 仍处于测试阶段）：

Set up private registry

请注意，您需要按照这里的说明设置对私有注册表的访问。

此外，您可能需要将以下行添加到您的 .npmrc 文件中：

@tiptap-cloud:registry=https://registry.tiptap.dev/

npm install @tiptap-cloud/provider

基本设置中，通过指定文档名称、您的应用 ID（云端设置）或基础 URL（本地部署），以及 JWT 令牌来连接协作后端。

根据您的框架，注册连接到协作后端的回调，如 React 中的 useEffect() 或 Vue.js 中的 onMounted()。

const doc = new Y.Doc()

useEffect(() => {
  const provider = new TiptapCollabProvider({
    name: note.id, // 文档标识符
    appId: 'YOUR_APP_ID', // 替换为云端控制台中的 YOUR_APP_ID
    token: 'YOUR_JWT', // 认证令牌
    document: doc,
    user: userId,
  })
}, [])

本地部署用户的提示

如果您在本地托管协作环境，请在提供者配置中用 baseUrl 替换 appId 参数，以连接到您的服务器。

配置协作提供者

Tiptap 协作提供者支持多种设置，用于自定义配置。请查看下表，了解所有参数、实际用例及诸如“awareness”等关键概念。

设置名	默认值	说明
`appId`	`''`（空字符串）	适用于协作云端的应用标识
`baseUrl`	`''`（空字符串）	用于连接本地服务器的 URL。作为 `appId` 的替代选项，适用于本地部署
`name`	`''`（空字符串）	文档名称
`token`	`''`（空字符串）	认证令牌，用于安全连接。支持字符串、函数和 Promise
`document`	`new Y.Doc()`	Yjs 文档实例。若未提供，则默认为新文档
`user`	`null`	用户 ID 或名称，用于标注文档更改
`connect`	`true`	初始化后是否连接服务器
`preserveConnection`	`true`	关闭提供者后是否保持 WebSocket 连接
`broadcast`	`true`	是否启用不同浏览器标签页之间的文档同步
`forceSyncInterval`	`false`	是否按固定间隔（毫秒）强制进行服务器同步
`quiet`	`false`	是否抑制警告信息输出
`WebSocketPolyfill`	`WebSocket`	Node.js 环境的 WebSocket 实现。可以使用 `ws` 或其他实现

优化重连时间

提供者的重连设置预设为生产环境的最佳性能。如需针对特定场景调整这些参数，可通过延迟配置完成。

您可以调整初始延迟、应用指数退避，或设置最大等待时间，以微调应用的重连行为，平衡响应速度和服务器效率。

设置名	默认值	说明
`delay`	`1000`	两次重连尝试之间的基础延迟，单位毫秒
`factor`	`2`	延迟倍率，每次尝试后指数级增加
`initialDelay`	`0`	第一次重连尝试前的延迟时间，单位毫秒
`maxAttempts`	`0`	最大重连尝试次数。`0` 表示无限次
`jitter`	`true`	是否添加抖动，通过在 `minDelay` 和计算延迟之间随机选取值增加重连的随机性
`minDelay`	`1000`	启用抖动时的最小延迟。如果禁用抖动则无效
`maxDelay`	`30000`	重连尝试之间允许的最大延迟。设置为 `0` 时，延迟将无限制增长，遵循指数退避（`factor`）规律
`timeout`	`0`	每次重连尝试的最大持续时间，单位毫秒，超时则停止尝试
`messageReconnectTimeout`	`30000`	等待服务器消息的时间上限，单位毫秒。若未收到消息，连接将自动关闭

速率限制

为维护系统稳定性并防止配置错误的客户端，我方基础设施（包括管理 API 和通过 TiptapCollabProvider 的 WebSocket 连接）均受速率限制管理。

默认速率限制（每来源 IP）：

请求数： 100 次
时间窗口： 5 秒
突发容量： 最多 200 次请求

如在正常使用情况下遇到限制，请通过电子邮件联系我们。