Link

Client-side functionalities

Basics

All set to go on communicating with apaleo’s UI? Before we jump into the funny part, let’s start with the basics.

Your app is running in an iframe. That means, that the parent of your Window Object is apaleo. Because of that, you can communicate with us in a message based way.

To achieve this, you have to use the following methods:

  • window.parent.postmessage(<your message>, "*")
    • With this method you will be able to send us a message.
    • We expect a stringified JSON as a message. That means you have to convert your JSON / message to a string before you send it.
    • In case you want to check more about the postMessage method.
  • window.addEventListener("message", <your callback>)
    • With this method you will be able to receive a message from us.
    • You might want also to check out the addEventListener method.

Response

The response which you can listen with window.addEventListener("message", <your callback>) has the following structure.

PROPERTY DESCRIPTION
from It is a hardcoded string [apaleo]. With this you will know that the response is from us.
message The message is a string which is used to give the user information about the problem or it can be a success message.
extra Extra can be anything. This is used to send you additional information.

Here is a sample response

{
  "from": "[apaleo]",
  "message": "A stringified json was expected but it was something else",
  "extra": "<- here would be your message that you send ->"
}

If you want to navigate in the apaleo UI without causing a reload, then you can send us this payload.

PROPERTY DESCRIPTION
type This is an identifier for us to know which type of message you send to us. For navigation messages it should be navigate.
path The path describes the navigation endpoint you want to go.
context Context can be account-level, property-level or both.
id The identifier is needed to differentiate between multiple navigation endpoints. As an example if you want to navigate to a reservation, then the id would be the reservation id.
  • account-level: You can only navigate in the account context. Allowed value: $ACCOUNT.
  • property-level: You can only navigate within properties. You can only navigate to properties where you have access to. Allowed values: $CURRENT_PROPERTY or the property id.
  • both: It means that the path is available in account-level and property-level.

Endpoint details

Here you can see the available endpoints and in which context they can be used.

PATH CONTEXT LEVEL ID NEEDED DESCRIPTION
apps both YES Navigates to a UI Integration
properties account-level - Navigates to the properties overview in the account context
reservation-details property-level YES Navigates to the reservation details of a reservation

Here is a sample payload to navigate to the reservation details of the reservation with the id “SOME-1” and property “AWE”:

{
  "type": "navigate",
  "path": "reservation-details",
  "context": "AWE",
  "id": "SOME-1",
}

Here is a sample payload to navigate to the reservation details of the reservation with the id “SOME-1” in the current property:

{
  "type": "navigate",
  "path": "reservation-details",
  "context": "$CURRENT_PROPERTY",
  "id": "SOME-1",
}

Notifications

Showing a notification is also easy. You can use the apaleo UI notification service to display any sort of message above your iframe, just as shown in the screenshot below.

In order to do so, you can send us the following payload

Here is a sample payload to show a success notification:

{
  "type": "notification",
  "title": "apaleo",
  "content": "rocks",
  "notificationType": "success"
}

Properties

PROPERTY OPTIONAL DESCRIPTION
type - This is an identifier for us to know which type of message you send to us. For notification messages it should be notification.
title - The title of the toast message.
content YES The content of the toast message.
notificationType - Type can be success, alert or error.

Language and translations

In order for you to be able to manage the language of your integration, we provide the current language of the apaleo UI to the iframe as a query parameter. So, if you want to translate your integration so it is in the same language as the apaleo UI, you can use the lang query parameter.

For example, when we load your integration into the iframe with your URL we provide the query parameters as follows

https://www.yourintegration.com?accountCode=[CurrentUserAccountCode]&lang=en&subjectId=[CurrentUserSubjectId]

As you can see the URL contains the query parameter lang=en which you can use in your integration in order to show in the desired language.