This guide explains how you can include your views into the apaleo user interface. This allows users to see information or even trigger actions in your product. Let them generate access keys, send emails, see the guest's loyalty status, display rate recommendations, or videos of little puppy dogs - anything, really. It works best, when you already have an API-integration in place, as that allows you to look up additional data for the context you are in (like, the guest's name).
In the apaleo UI, there are well-defined places, targets, where you can put your content. Each of them has a specific size, and can forward specific data to you application.
|DashboardAccountContext||min. 340 x 350||-/-|
|DashboardPropertyContext||min. 340 x 350||propertyId|
|PropertyMenuReports||responsive (full content page)||propertyId|
|PropertyMenuApps||responsive (full content page)||propertyId|
Want something else? Let us know.
Technically, those placeholders are iframes. This has the benefit that you can use whatever technology you want, to create this page. Server-side generation of pages or client-side rendering? Up to you. "Wait," we hear you say, "you said iframe? Is that secure?" It sure is! Modern browsers use sandboxed environments for iframes, which means that your integration can co-exist with apaleo's UI and we won't be able to hurt each other. Additionally, you must use HTTPS URLs for the iframe source. This is enforced by the browser because iframes are active mixed content and apaleo UI is only served via HTTPS. You can read more about it on MDN.
For the rest of the guide, we'll use the additional tab on reservations as an example.
There are two different types of integrations with apaleo One, public and private integrations. Both do the same, but they present some fundamental differences that are worth mentioning.
Having a public integration means that the URL that you configure is directly used as the source of the iframe. That's the way to go for the puppy-dog videos, or anything else that needs no security. Keep in mind that the source URL must be HTTPS.
With a private integration, the URL that you provide is not included directly, but instead used to fetch the public URL from your service. This approach is recommended as it provides an additional layer of security, which we will discuss later. For these kinds of integrations, both afore mentioned URLs must be HTTPS.
The image below shows how the integration service fetches the public URL from your service using the private URLs
This is the format we expect as a response from your secure-URL endpoint:
Be aware that datetime must be a ISO 8601 string such as '2019-06-06T12:55:38Z'.
Now that we have gone through the basics, let's get to the fun part. How do I get this to work?
In order to publish your integrations, you will need to access the apaleo integration service here https://integration.apaleo.com. It provides the endpoints to set everything up, and even run tests for you, to be sure that your integration is doing what you want
Set up integration
Setting up an integration is as easy as riding a bike on a sunny day, all you need to do is call the creation endpoint:
However, before we jump into the chapter, you might have the question "How do I make this available to customers?" lingering around your mind. The answer is simple: Because manual work is for non-lazy people, and remembering to do something is error-prone, you should plug that into the connect and setup flow. So, whenever a user connects your product to apaleo, they immediately get it in their apaleo UI. But of course, nothing stops you from adding the integration for the users from your desired customised flow and UI.
When no URL is configured for a specific apaleo account, no content will be displayed. This is what you want, but don't forget to configure the integration every time a new connection is made. Because manual work is for non-lazy people, and remembering to do something is error-prone, you should plug that into the connect flow.
This is the payload you have to pass when creating your UI integration:
|Code||The identifier of your integration. If no code is provided the target of the integration is used as code.||-|
|Label||The text shown in the header of your widget, for example the tab, or title of a dashboard tile. If you do not know what to use, your product name is a good choice.||Yes|
|IconSource||Nice icon to brand that part of the apaleo UI as yours.||-|
|SourceUrl||The URL of your integration. Basically, the most important part of your integration.||Yes|
|SourceType||Whether your integration is a public (SourceUrl is public) or a private (SourceUrl is private) integration.||Yes|
|PropertyIds||Property-IDs for which your integration is enabled. If no properties are provided, then the integration is available for all of them.||-|
Here is a sample payload for a private integration limited to the properties "AWE" and "SOME":
There are certain things to keep in mindwhen creating or modifying your integrations.
For both source types
- You can have multiple integrations for the same target, as long as they have different URLs and codes.
- The separation of properties is completely optional and if no properties are provided then the integration will be available for all properties.
- When creating/modifying a public integration we validate that the provided SourceUrl is a valid HTTPS URL.
- When creating/modifying a private integration in addition of validating that it is a valid HTTPS URL, we validate and run the complete test suite. To learn more about the tests executed refer to the Test section in this guide here.
Securing private integrations
When constructing the secure URL, you can go wild and implement whatever security magic you want, but it's your responsibility to make sure that only apaleo can call your service. Not doing this may lead to intruders getting an easy way into the connected application. Here are some measures that might be helpful:
- Make it so that your endpoint is only accessible from one of the apaleo public IP addresses: 184.108.40.206, 220.127.116.11, 18.104.22.168 (Whitelist the public IP if required)
- Attach some sort of long key / string / guid as a query parameter which is recognised by your service (https://www.example.com/integration?token=[GUID/JWT]), like a JWT or reference token: http://docs.identityserver.io/en/latest/topics/reference_tokens.html.
When calling the final URL, apaleo appends the data to the URL, as a query parameter. Check the table of available integration targets to see which data that is.
Testing your integration
This section only applies toprivateintegrations, public integrations are not testable.
If you make any changes on your side, you may want to make sure that our integration service can get your integration without any hiccups. That is where our nice test suite comes into play. Just call:
So, what are we testing for?
- Validate that the provided private URL is valid (proper body and https)
- Make sure that the result of the response is a successful 2xx status code
- Validate that the response body is not empty
- Check that the response body fits the expected schema, as shown in the JSON code below
- Validate that the expiration date is in the future in UTC time zone
- Make sure that the received public URL is valid (proper body and https)
We would recommend to develop your apaleo UI snippet as a separate page, and not just include a page or view from your prodcut. That way you can style it differently, and optimize the content. The downside is that it might be out of sight and out of mind, and break without you noticing. Make sure to include it in your tests.
Make it clearly visible, that this is your content and not apaleo's. You should get the fame for what you built – and the support tickets, too.
The apaleo UI is responsive, and works from phones to giant screen. Many hotels still have old and non-high-res screens standing around, take that into account when designing and building your UI. As font, we use Roboto, background is white, text is black and sentence case. We usually don't do bold, italic or all-caps. Our brand new branding is using #363942 (grey), #5C832E (green), #382513 (brown), #D9CBA8 (sand), #2C8693 (blue) and #F19721 (orange), where the last one is the primary color for buttons. The layout is Material design-ish, and we also use their icons.
You don't have to use the same style as we do, but we think the users would be happy, if it is not looking completely different. So would Nadia and Dmitry, and if you want to, they can do a quick review of what you built.
Posted byAndrea Stubbe