IFrame Events

The event messaging protocol sends business events to the parent document of the iframe, such as the completion of the booking journey or the conclusion of a video consultation.

Overview #

Communication occurs between the parent window and the iframe through the postMessage API. The protocol facilitates unidirectional communication from an eMed iframe to the partner website parent document through message events in JSON format.

The eMed iframe initiates and dispatches message events to the parent document. The parent document can choose to process the events, enabling it to update its state and user interface accordingly (e.g., redirecting to a different page).

We have defined a standard structure for these messages using our iframe to ensure interoperability.

Message structure #

{
    "schema": "schema_name",
    "version": "schema_version",
    "type": "message_type",
    "data": {
        // Various JSON values depending on the message type
    }
}

schema: Indicates the name of the schema defining the message structure. e.g. “EVENT”.

version: Denotes the version of the schema used for the message. e.g. “1.0”

type: Specifies the type of message being transmitted. e.g. “appointment.booking.complete” or “appointment.booking.cancelled”

data: Contains the data payload associated with the message, structured as per the message type requirements. E.g.

{
  "patient_id": "6c8d0944-7cbc-4cd7-bd54-51b869499010",
  "appointment_id": "456"
}

Messages can be of different types based on the nature of the communication. The payload within each message can vary based on the message type. It may include one or more values relevant to the message context. Examples of payload elements include:

appointment_id: Unique identifier for an appointment.

patient_id: Unique identifier for a patient.

Implementation #

The partner website parent document must define event listeners to receive messages from the eMed iframe. Upon receiving a message event, parse the data and process it accordingly.

On the parent document’s side, it can listen for these messages using the window.addEventListener('message', function (e) {}); method. This event listener listens for the ‘message’ event, triggered when a message is received from any source.

Example #

window.addEventListener('message', (event) => {
   // Validate the origin
   if (event.origin !== 'https://embed.emed.com') { //  Change the origin for the environment being used
       return;
   }


   let message;
   try {
       message = JSON.parse(event.data);
   } catch (e) {
       console.error('Invalid JSON:', event.data);
       return;
   }


   // Validate the schema and version
   if (message.schema !== 'EVENT' || message.version !== '1.0') {
       console.error('Unsupported message:', message);
       return;
   }


    switch (message.type) {
        case 'appointment.booking.complete':
           // Extract the appointment ID and patient ID
           const appointmentId = message.data.appointment_id;
           const patientId = message.data.patient_id;
           console.log(`Received appointment.booking.complete event with appointment ID ${appointmentId} and patient ID ${patientId}`);
           break;
        case 'appointment.booking.cancelled':
           const appointmentId = message.data.appointment_id;
           const patientId = message.data.patient_id;
           console.log(`Received appointment.booking.cancelled event with appointment ID ${appointmentId} and patient ID ${patientId}`);
           break;
        case 'consultation.call.ended':
           const appointmentId = message.data.appointment_id;
           console.log(`Received consultation.call.ended event with appointment ID ${appointmentId}`);
           break;
        default:
           console.error('Unknown message type:', message.type);
           return;
   }
});

Message Types #

The following messages are currently emitted (more events can be added on request):

Security #

To safeguard your application, please align with general security best practices and guidelines. Essential considerations include, but are not limited to, the points outlined below: Avoid exposing unnecessary or sensitive information via console.log - the example code above is just for illustrative purposes. Implement proper origin validation to prevent unauthorised communication.

window.addEventListener("message", (event) => {
    if (event.origin !== "https://embed.emed.com") return;
    // …
});

See Environments for the list of origins. Sanitise incoming data to mitigate risks associated with cross-site scripting (XSS) attacks.