Window postMessage API

6min
LiSA supports safe cross-origin communication between the LiSA viewer app and embedding Window objects; e.g., with pages that embed the LiSA viewer app in an iFrame.
This article describes the messages and event actions that LiSA accepts and exposes.
Messages
LiSA utilizes the Window.postMessage APO event’s data object to pass information between windows. All messages relevant to LiSA implement the Message interface.
The Message interface provides information about the specific target and action of the event it represents, as well as sender and (optional) recipient information.
TypeScript
interface Message {
  /** Action of this message */
  readonly action: string;
  /** Map of additional message payload data */
  readonly additional: {
    [key: string]: boolean | number | string | undefined;
  };
  /** Recipient for messages sent to LiSA - Static value: 'LiSA' */
  readonly recipient?: 'LiSA';
  /** Sender of this message - Static value 'LiSA' for messages from LiSA */
  readonly sender: 'LiSA' | string;
  /** Target of this message */
  readonly target: string;
}
interface Message {
  /** Action of this message */
  readonly action: string;
  /** Map of additional message payload data */
  readonly additional: {
    [key: string]: boolean | number | string | undefined;
  };
  /** Recipient for messages sent to LiSA - Static value: 'LiSA' */
  readonly recipient?: 'LiSA';
  /** Sender of this message - Static value 'LiSA' for messages from LiSA */
  readonly sender: 'LiSA' | string;
  /** Target of this message */
  readonly target: string;
}
﻿
Receiving messages from LiSA
To receive messages from LiSA you need to add an event listener to your storefront, that listens for dispatched messages, sent by the LiSA viewer app. The message payload is accessed using the event's data property.
To only listen for messages sent by LiSA, please filter by sender as set in the payload's sender property. For messages from LiSA the value of that property will always be LiSA.
JS
(function () {
  var method;
  var eventName;
  if (window.addEventListener) {
    method = 'addEventListener';
    eventName = 'message';
  } else if (window.attachEvent) {
    method = 'attachEvent';
    eventName = 'onmessage';
  }
  window[method](eventName, function (e) {
    if (e && e.data && e.data.sender === 'LiSA') {
      var payload = e.data;

      // your code goes here
    }
  });
})();
(function () {
  var method;
  var eventName;
  if (window.addEventListener) {
    method = 'addEventListener';
    eventName = 'message';
  } else if (window.attachEvent) {
    method = 'attachEvent';
    eventName = 'onmessage';
  }
  window[method](eventName, function (e) {
    if (e && e.data && e.data.sender === 'LiSA') {
      var payload = e.data;

      // your code goes here
    }
  });
})();
﻿
Sending messages to LiSA
When sending messages to LiSA, please make sure to set the optional field recipient with value LiSA. Otherwise the message be ignored by the LiSA viewer app.
Here is an example message to revoke the like action on a carousel item:
JS
var frameRef = document.querySelector('.lisa--viewer-frame');

frameRef.contentWindow.postMessage(
  {
    sender: 'noon',
    recipient: 'LiSA',
    target: 'carousel.item',
    action: 'like.revoke',
    item: {
      id: 'cbbf81a6-e515-495a-be53-3b451bf395a2',
    },
  },
  'https://public.loveslisa.tech',
);
var frameRef = document.querySelector('.lisa--viewer-frame');

frameRef.contentWindow.postMessage(
  {
    sender: 'noon',
    recipient: 'LiSA',
    target: 'carousel.item',
    action: 'like.revoke',
    item: {
      id: 'cbbf81a6-e515-495a-be53-3b451bf395a2',
    },
  },
  'https://public.loveslisa.tech',
);
﻿
Important: Please make sure to replace the targetOrigin parameter with your LiSA URL, or the wildcard *.
Available message types
﻿AppMessage﻿ 
﻿CarouselItemMessage﻿ 
﻿CartMessage﻿ 
﻿CTAMessage﻿ 
﻿LinkMessage﻿ 
﻿PlayerMessage﻿ 
﻿ShowEngagementMessage﻿ 
﻿ShowHostMessage﻿ 
﻿ShowMessage﻿ 
﻿UserMessage﻿ 
Debugging
To enable logging of sent and received messages within the browser's console, please add query parameter debug=Messaging to your LiSA URL. 
Enable debug message
https://public.loveslisa.tech?debug=Messaging
https://public.loveslisa.tech?debug=Messaging
﻿
﻿
Updated 25 Mar 2024
Did this page help you?
Platform communication
AppMessage