Unity Messaging API

The Unity Messaging API allows the external application frontend to interact with Pricefx Unity frontend. Via the API you can ask Unity to create a new quote, update or fetch quote inputs, etc.

To enable the Messaging API, set the feature flag feIntegration.active to true.

To call Unity from the external app frontend, use the window.postMessage() method from JavaScript in the browser.

Example of Unity embedded in an external application:

const iframe = document.getElementById('pfx-iframe');
const messageHandler = (event) => console.log(event.data);
window.addEventListener(messageHandler);
iframe.contentWindow.postMessage({
  "source": "pfxParentMessage",
  "type": "getUserData"
}, *);

In this case, you will attach a handler that logs the message it receives from Unity, and also will message Unity requesting the logged in user data.

Example of an external application embedded in Unity:

const messageHandler = (event) => console.log(event.data);
window.addEventListener(messageHandler);
window.parent.postMessage({
  "source": "pfxParentMessage",
  "type": "getUserData"
}, *);

The messages must have 2 fields: source and type. For most messages, there will be also the payload field which will contain additional data for the sent message.

• source refers to the origin of the message, which can be either pfxParentMessage or pfxChildMessage.

• type defines which kind of message is being sent, and can be any of the following values described in the tables below.

Some kinds of messages will also return data which will be sent through postMessage too.

Note: Messages described in the table below (except for getUserData and addClicLineItems) have the same signature as described here.

The following messages are available for both cases (where Unity is either the parent or a child page):

{
  "source": "pfxParentMessage",
  "type": "getUserData"
}

{
  "source": "pricefx",
  "type": "GET_USER_DATA",
  "payload": {
    "locale": "en-gb",
    "email": "your@email.com",
    "loginName": "login.name",
    "roleNames": [...]
  }
}

{
  "source": "pfxChildMessage",
  "type": "getClicHeaderValue",
  "payload": {
    "fieldName": "externalRef"
  }
}

{
  "source": "pricefx",
  "type": "HEADER_VALUE",
  "payload": {
    "fieldName": "externalRef",
    "fieldValue": "externalReference"
  }
}

{
  "source": "pfxParentMessage",
  "type": "updateClicHeaderValue",
  "payload": {
    "fieldName": "externalRef",
    "fieldValue": "new externalRef"
  }
}

{
  "source": "pfxChildMessage",
  "type": "recalculate"
}

{
  "source": "pfxParentMessage",
  "type": "getClicLineItems",
  "payload": {
    "queryData": "AK_0001"
  }
}

{
  "source": "pricefx",
  "type": "LINE_ITEMS",
  "payload": {
    "queryData": "AK_0001",
    "lineItems": []
  }
}

{
  "source": "pfxParentMessage",
  "type": "addClicLineItems",
  "payload": {
    "lineItems": [
      {
        sku: "AK_0001',
        inputs: {
          Quantity: 3
        }
      }
    ]
  }
}

There are also messages which are exclusive to the case where Unity is embedded in an external application, since they manipulate the window location:

{
  "source": "pfxParentMessage",
  "type": "newQuote",
  "payload": {
    "targetPageState": {
      "targetPageFields": {
        "externalRef": "created by message"
      }
    }
  }
}

{
  "source": "pfxParentMessage",
  "type": "navigate",
  "payload": {
    "targetPage": "priceShopPage",
    "id": "123"
  }
}

There are also events in Unity that will trigger a message. When submitting or recalculating a CLIC, a message will be sent containing all CLIC data, such as:

{
  "source": "pricefx",
  "type": "QUOTE_RECALCULATED",
  "payload": {
    "version": 7,
    "typedId": "2147493723.Q",
    "uniqueName": "P-2147493723",
    "label": "New Quote",
    "targetDate": "2023-05-29",
    "workflowStatus": "DRAFT",
    ...
  }
}