# @univerjs-pro/collaboration-client

> Language fallback: requested `es-ES`; content is `en-US`.

- Human documentation: [https://docs.univer.ai/es-ES/reference/packages/plugins/univerjs-pro/collaboration-client](https://docs.univer.ai/es-ES/reference/packages/plugins/univerjs-pro/collaboration-client)

- Agent Markdown: [https://docs.univer.ai/es-ES/reference/packages/plugins/univerjs-pro/collaboration-client.md](https://docs.univer.ai/es-ES/reference/packages/plugins/univerjs-pro/collaboration-client.md)

- Requested language: `es-ES`

- Content language: `en-US`

- Documentation version: `1.2.0`

- Source: [packages/plugins/univerjs-pro/collaboration-client.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/packages/plugins/univerjs-pro/collaboration-client.mdx)

---

Client-side collaboration plugin for Web SDK.

```typescript
// [!code word:UniverCollaborationClientPlugin]
import type { IUniverCollaborationClientConfig } from '@univerjs-pro/collaboration-client'
import { UniverCollaborationClientPlugin } from '@univerjs-pro/collaboration-client'
import { BrowserCollaborationSocketService } from '@univerjs-pro/collaboration-client-ui'

const config: IUniverCollaborationClientConfig = {
  socketService: BrowserCollaborationSocketService,
}
univer.registerPlugin(UniverCollaborationClientPlugin, config)
```

`socketService` is required. Browser clients can use `BrowserCollaborationSocketService`; other hosts must provide their own `ICollaborationSocketService` implementation.

## Entry Points

* Facade: `@univerjs-pro/collaboration-client/facade`
* Locale: `@univerjs-pro/collaboration-client/locale/*`

The Facade entry exposes host-specific loaders for Sheets, Docs, Bases, Slides, Boards, and PDFs, including `loadPdfAsync(unitId, context?)`.

## IUniverCollaborationClientConfig

```ts
import type { IAttachmentUploadOptions, ICollaborationSocketService } from '@univerjs-pro/collaboration-client'
import type { Ctor, DependencyOverride } from '@univerjs/core'
import type { UnitObject } from '@univerjs/protocol'

export interface IUniverCollaborationClientConfig {
  socketService: Ctor<ICollaborationSocketService>
  enableCollaboration?: boolean
  enableOfflineEditing?: boolean
  enableSingleActiveInstanceLock?: boolean
  enableAuthServer?: boolean
  override?: DependencyOverride
  sendChangesetTimeout?: number
  changesetAckTimeout?: number
  maxChangesetAckTimeout?: number
  snapshotServerUrl?: string
  collabSubmitChangesetUrl?: string
  collabWebSocketUrl?: string
  wsSessionTicketUrl?: string
  loginUrlKey?: string
  retryConnectingInterval?: number
  authzUrl?: string
  objectPermissionTypes?: UnitObject[]
  downloadEndpointUrl?: string
  uploadFileServerUrl?: string
  signUrlServerUrl?: string
  attachment?: IAttachmentUploadOptions
  customHeaders?: Record<string, string>
}
```

`enableCollaboration` defaults to `true`; `enableOfflineEditing` defaults to `false`. `objectPermissionTypes` opts into stable-ID object permissions supported by your Authz server; the backend must authorize every binding change. `attachment` controls shared upload restrictions and an optional custom uploader.

## Batching and acknowledgement timeouts

| Option                   | Default     | Behavior                                                                                             |
| ------------------------ | ----------- | ---------------------------------------------------------------------------------------------------- |
| `sendChangesetTimeout`   | `2000` ms   | Batch local edits before the first send; not a network timeout.                                      |
| `changesetAckTimeout`    | `20000` ms  | Wait for acknowledgement before resending; also bounds the submission request.                       |
| `maxChangesetAckTimeout` | `120000` ms | Cap exponential backoff between resends. Set equal to `changesetAckTimeout` for a constant interval. |

The Sheets and Docs collaboration presets use a 200 ms batching delay and do not expose acknowledgement timeout options. Configure the client plugin directly when you need to change those options.

`FCollaboration.hasWritePending(unitId?)` includes queued, awaiting-acknowledgement, and offline edits. `CollaborationStatusChanged` reports existing units' current status when the listener is registered and suppresses consecutive identical statuses. `CollaborationChangesetResend` reports retries; `CollaborationConflict` carries the conflict reason and unacknowledged edits after the cache-cleanup attempt. See [synchronization and recovery](https://docs.univer.ai/es-ES/server/collaboration/browser-integration.md#sync-status).