Rasterex API/docs/getting-started/iframe-init

Initialize Canvas

Embed the Canvas iframe and dispatch the first view payload.

Overview

Set the Canvas URL, mount the iframe, and send a view message after the canvas is ready to receive host messages.

Keep the canvas origin and URL in a single configuration module.
Attach the iframe load handler before assigning iframe.src.
Wait briefly after iframe load before posting the first message.
Send a view payload with a file URL to bootstrap the session.

Define the Canvas URL

Define the Canvas URL once and reuse it across canvas sessions.

javascript

// Centralize the Canvas URL for reuse.
const CANVAS_URL = 'https://beta.viewer.viewsoft.com'
const FILE_URL = 'https://res.cloudinary.com/dvgeew3bj/image/upload/v1779169700/Main_version_1.pdf_1_ifrgjq.pdf'
const viewerOrigin = new URL(CANVAS_URL).origin

Define the Canvas URL

Initialize the iframe

Create the iframe without src in the markup. Register the load handler first, then assign iframe.src. This prevents a fast iframe load from firing before your handler exists.

javascript

const iframe = document.querySelector('[data-viewer-iframe]')
if (!iframe) {
  throw new Error('Canvas iframe not found')
}

let fileLoadStarted = false

function sendToCanvas(message) {
  iframe.contentWindow?.postMessage(message, viewerOrigin)
}

function openFile() {
  sendToCanvas({
    type: 'view',
    payload: {
      fileUrl: FILE_URL,
    },
  })
}

iframe.addEventListener('load', () => {
  window.setTimeout(openFile, 500)

  window.setTimeout(() => {
    if (!fileLoadStarted) {
      openFile()
    }
  }, 1500)
})

// Assign src after the load handler is registered.
iframe.src = CANVAS_URL

Initialize the iframe

Load Order Warning

Do not put src directly on the iframe if your integration depends on catching the first load event. The browser can load a cached iframe before your script registers the handler.

Also avoid sending view immediately at iframe load time. The iframe document may be loaded while the canvas app is still registering its message listener.

javascript

// Preferred order
const iframe = document.querySelector('[data-viewer-iframe]')

iframe.addEventListener('load', () => {
  window.setTimeout(openFile, 500)
})

iframe.src = CANVAS_URL

Load Order Warning

Type the payload (TypeScript)

Reuse a typed payload shape to keep canvas messages consistent.

typescript

type ViewMessage = {
  type: 'view'
  payload: {
    fileUrl: string
  }
}

const viewerOrigin = getViewerOrigin()
const iframe = document.querySelector('[data-viewer-iframe]') as HTMLIFrameElement | null

const message: ViewMessage = {
  type: 'view',
  payload: {
    fileUrl: 'https://res.cloudinary.com/dvgeew3bj/image/upload/v1779169700/Main_version_1.pdf_1_ifrgjq.pdf',
  },
}

const sendToCanvas = (nextMessage: ViewMessage) => {
  iframe?.contentWindow?.postMessage(nextMessage, viewerOrigin)
}

// Send this after iframe load and a short canvas boot delay.
window.setTimeout(() => sendToCanvas(message), 500)

Type the payload (TypeScript)

Handle progress events

Use progressStart and progressEnd to drive loading UI while the canvas prepares files. progressStart also confirms that the first view message was received.

javascript

window.addEventListener('message', (event) => {
  if (event.origin !== viewerOrigin) return

  if (event.data?.type === 'progressStart') {
    fileLoadStarted = true
    setIsLoading(true)
  }

  if (event.data?.type === 'progressEnd') {
    setIsLoading(false)
  }
})

Handle progress events

Complete Implementation

A full example with configuration, iframe lifecycle, and the initial view message.

javascript

// CONFIGURATION
const CANVAS_URL = 'https://beta.viewer.viewsoft.com'
const FILE_URL = 'https://res.cloudinary.com/dvgeew3bj/image/upload/v1779169700/Main_version_1.pdf_1_ifrgjq.pdf'
const viewerOrigin = new URL(CANVAS_URL).origin

// IFRAME SETUP
const iframe = document.querySelector('[data-viewer-iframe]')
if (!iframe) {
  throw new Error('Canvas iframe not found')
}

let fileLoadStarted = false

function sendToCanvas(message) {
  iframe.contentWindow?.postMessage(message, viewerOrigin)
}

function openFile() {
  sendToCanvas({
    type: 'view',
    payload: {
      fileUrl: FILE_URL,
    },
  })
}

window.addEventListener('message', (event) => {
  if (event.origin !== viewerOrigin) return

  if (event.data?.type === 'progressStart') {
    fileLoadStarted = true
    setIsLoading(true)
  }

  if (event.data?.type === 'progressEnd') {
    setIsLoading(false)
  }
})

iframe.addEventListener('load', () => {
  window.setTimeout(openFile, 500)

  window.setTimeout(() => {
    if (!fileLoadStarted) {
      openFile()
    }
  }, 1500)
})

// Set src only after all first-load handlers are registered.
iframe.src = CANVAS_URL

Complete Implementation