Skip to main content

Handling Private Images Using the fetchImage Callback

Learn how to securely load authenticated or private images into the Unlayer image editor by bypassing cloud proxies and fetching image data directly within the user's browser.

Written by Saifullah Bhatti

Overview

By default, when a user opens an image in the Unlayer image editor, Unlayer uses a cloud proxy (api.tools.unlayer.com) to retrieve the image file. However, if your application stores images behind a secure firewall, requires active session cookies, or relies on Authorization headers (e.g., Bearer tokens), the cloud proxy will fail to load the image because it does not possess the user's local authentication credentials.
​

To handle private images, you must register the fetchImage callback. This intercepts the request, bypassing the Unlayer cloud proxy entirely, and delegates the image retrieval directly to the user's browser where their active session or authorization token already exists.
​

Implementation Snippet

To intercept the image request, add the fetchImage callback to your application where unlayer.init() is configured:

JavaScript

unlayer.registerCallback("fetchImage", function (params, done) {
  if (!params?.url) return;

  // fetch image in your own way here
  // ...

  const result = {
    // blob: ...,
    // error: ...,
  };

  done(result);
});

How the Callback Flow Works

  1. User Opens Image Editor: When the user attempts to crop, filter, or edit an image, Unlayer intercepts the network request and triggers your fetchImage callback instead of making an external call to Unlayer's servers.

  2. Local Blob Handshake: Once the frontend receives the image, it converts it to a Blob and passes it to the callback's done({ blob: imageBlob }) function. Unlayer then loads this raw binary data straight onto the editing canvas.

Important Notes

Before implementing this workflow, keep the following technical constraints in mind:

  • Strictly Client-Side: Raw image files never cross Unlayer's servers or leave your internal infrastructure. The entire fetch operation and editing rendering takes place locally inside the user's browser, maintaining total data privacy.

  • CORS Requirements: Because your frontend application is now executing the fetch request, the server or storage bucket hosting the images (e.g., AWS S3, Google Cloud Storage) MUST be configured to allow Cross-Origin Resource Sharing (CORS). If CORS is blocked, the browser will block the fetch operation.

  • Host Application Responsibility: Unlayer only provides the bridge (the callback). Your development team is entirely responsible for writing the asynchronous fetch logic, handling network errors, and managing the secure tokens required to successfully retrieve the image Blob.

Common Use Cases

Implementing this configuration is necessary when:

  • Secure SaaS Platforms: Your application restricts media access strictly to logged-in users via Authorization tokens or secure session cookies.

  • Intranets & Firewalls: The Unlayer editor is hosted on internal company networks or VPNs where public external proxies cannot reach the image URLs.

  • Expiring Access: Images are stored in private cloud buckets requiring signed URLs generated dynamically by your frontend.

Did this answer your question?