Migration from iframe v3 API

Use this guide when your application still uses the deprecated LIQA iframe v3 API and you want to move users to the current LIQA web component.

The main client impact is a newer embedded UI, optional image upload, structured event handling, and access to current customization guides. The technical migration focuses on replacing iframe messaging with the web component, adapting image output from base64 to blob, and updating event/error handling.

Versions Comparison Summary

Feature	previous (iframe v3)	current (web component v6)
Delivery method	CDN	CDN
Integration method	iframe	web component
Image format by default	base64	blob
User Interface	included, old design	included, new design
Option to upload image from device gallery	no	yes, optional

Migration Steps

WARNING

We recommend fully removing the previous LIQA version integration from your application code before starting.

1. Start by following the Quick Start integration with default settings
2. Add a function to perform image conversion from blob to base64 to match the /upload SaaS API.
3. If your application allows users to upload images from the device gallery, allow this option in the new LIQA by default and remove this feature from your application code.
4. Customize the LIQA interface style and texts. See UI styling and text replacement documentation pages.
5. Add error handling logic.
6. Test your application on mobile devices. Check system requirements for the best performance.
7. Check our recent updates regularly on the What's new? page.

Features Compatibility Notes

Cache LIQA content

The previous version (v3) offered a way to cache LIQA iframe content by setting the Cache-Control header. The current version (v6) does not support this feature and we recommend to remove it from your code.

Change appearance

The previous version (v3) offered a way to change selected colors by passing a "style" dictionary object via iframe.contentWindow.postMessage. The current version (v6) supports inline CSS styles or external CSS stylesheets via styles API. Check more on the UI styling documentation page.

Catch events and errors

The previous version (v3) offered a way to receive a limited list of events and errors by subscribing to .data.status observable via window.onmessage. The current version (v6) offers a more verbose and structured API to catch events and errors, see LIQA Event Map documentation page. Please, note that the events structure and error codes have changed.

Exit LIQA session

The previous version (v3) offered a way to exit LIQA iframe by injecting the "Exit" command via iframe.contentWindow.postMessage. The current version (v6) does not support this feature.