Latest

Blog Detail Title

Short Content Here

by Author Name

Date Published

Developer

UI Integration Guide

Andrea Stubbe January 2, 2019

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).

The basics

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.

Name Size Data  
DashboardAccountContext min. 340 x 350 -/-
DashboardPropertyContext min. 340 x 350 propertyId property dashboard
ReservationDetailsTab responsive (tab) reservationId reservation tab
CompanyDetailsTab responsive (tab) companyId
PropertyMenuReports 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.

Public integrations

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.

Private integrations

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

Getting the secure URL

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'.

The flow

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:

POST /integration/v1/ui-integrations/{target}

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.

flow when no URL is configured

This is the payload you have to pass when creating your UI integration:

Property Description Mandatory
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.
Public integrations
  • When creating/modifying a public integration we validate that the provided SourceUrl is a valid HTTPS URL.
Private integrations
  • 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 the apaleo public IP 34.240.36.71 (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.

Transmitting data

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:

GET /integration/v1/ui-integrations/{target}/{id}/$test

So, what are we testing for?

  1. Validate that the provided private URL is valid (proper body and https)
  2. Make sure that the result of the response is a successful 2xx status code
  3. Validate that the response body is not empty
  4. Check that the response body fits the expected schema, as shown in the JSON code below
  5. Validate that the expiration date is in the future in UTC time zone
  6. Make sure that the received public URL is valid (proper body and https)

The Looks

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.

 

UI integration of a reservation tab, using styling more similar to apaleo more like apaleo style

 

 

UI integration of a reservation tab, using your styling your style

 

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.

Nadia and Dmitry


Do you have content that does not fit in the targets we have defined? Then fill out this form, and let us know!

 


Andrea Stubbe

Posted by

Andrea Stubbe
Andrea started coding as a kid, paused that for some years trying to find more interesting things, but then ended up doing that for a living. After working as a freelancer, researcher, teacher, and a normal employee in small and giant corporations, she fulfilled her childhood dream and co-founded a company a year ago. Being a fan of microservices since before she knew that term, she’s still contemplating how and if to use them in micro-sized companies.
Comments

RECENT ARTICLES

by Andrea Stubbe

06/13/2019

Digital guest journey with apaleo

apaleo is building software for hotels, and our users are people that work at hotels. To create amazing guest experiences we need you, creators of guest facing ...

by Andrea Stubbe

05/02/2019

Push it! Webhooks in apaleo

The notification service allows you to build or set up apps which subscribe to certain events on apaleo (webhooks). When an event is triggered, we send an HTTP ...

by Benjamin Schmid

01/20/2019

Upsell Integration Guide

This guide explains how you can connect your upselling application, and offer extra services or room upgrades to guests. If you are new to apaleo APIs, head ...

WANT MORE AMAZING THINGS?

Subscribe to our a-list for all the fun:

  • Keep up to date with hotel trends
  • Understand what matters most to hotel clients
  • Sweet gifs and special offers

Get it in your inbox every Monday ;)

By entering your email you expressly consent to receive our newsletter every week and other material related to...