Editor embedding

The embed layer lets any web page open the O3O Office Online editor in an <iframe>, without Nextcloud or a WOPI-speaking storage system. Your page needs just two things: a URL the O3O server can download the source file from, and (if you want the edited copy back) a callback URL.

Components#

What happens when a document opens#

1. Your page loads http://localhost:8080/o3o/api.js and calls new O3O.Editor("id", config). api.js derives the server address from the src of its own script tag.
2. api.js posts the config (without events) to POST /o3o/embed/session.
3. The gate checks the origin and JWT, downloads document.url under the SSRF rules, applies the connection cap, then returns the editor address with the session access_token.
4. api.js builds the iframe and submits a form POST into it; the token travels in the form body, never in a URL.
5. The editor server reads the file from the gate over the internal network. On save, the gate stores a new version, answers the editor server at once, then sends a callback to callbackUrl.
6. Your page receives events via postMessage: onReady, onDocumentLoaded, onModified, onSaved, onClose, onLimitReached, onError.
7. Once everyone has left for 30 seconds, the gate sends a closed callback, keeps the working copy for 24 hours, then deletes it.

Shortest example#

<!-- Minimal HTML page, runs on a DEV machine (O3O_DEV_MODE=1) -->
<div id="o3o-editor" style="height: 720px"></div>
<script src="http://localhost:8080/o3o/api.js"></script>
<script>
  const editor = new O3O.Editor("o3o-editor", {
    document: {
      url: "http://localhost:8080/o3o/demo/sample.docx",
      title: "sample.docx",
      fileType: "docx",
      key: "sample-1"
    },
    editor: { mode: "edit", lang: "en-US", user: { id: "u-1001", name: "Jane Doe" } },
    events: {
      onDocumentLoaded: () => console.log("loaded"),
      onSaved: (e) => console.log("saved version", e.version),
      onError: (e) => console.error(e.code, e.message)
    }
  });
</script>

When to use the embed layer#

What v1 includes#

• O3O.Editor with 7 events and 5 methods.
• Config signing with JWT HS256; HMAC SHA-256 signed callbacks.
• Two modes, edit and view; view sessions do not count as connections.
• Connection cap reached: new sessions open read-only with a Vietnamese banner; open sessions are never cut and saves are never blocked.
• Keeps the 5 latest versions plus the original for 24 hours; signed download URLs.
• SSRF rules for every URL the server calls itself; a /o3o/demo test page on DEV machines.