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

This feature is available as an early beta. Which means, if you don't mind tinkering a little, and are fine with maybe having to change your implementation, go ahead. We're pretty sure the concept is good, and even got some external UI-security fanboys to review the concept. But it's not reality-tested yet.

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 -/-
PropertyDashboardCard 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 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, and we'll get to that later.
For the rest of the guide, we'll use the additional tab on reservations as an example.

The flow

The apaleo component used for the UI integration is the integration service, which you can find on https://integration.apaleo.com. Because we are using plain old iframes, all that is happening, is that the UI is using the URL you configured as the source attribute.

Integration is turned on or off per apaleo account, by calling

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

This allows to:

  • Toggle visibility, and only show it to your customers (or even specific customers)
  • Link the apaleo account to the account / tenant on your side
  • Have different URLs per account

You can specify a label and icon, which are displayed on tabs, the URL, and they type. For the type, please always specify 'private'. Early beta, you know.

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

Security

Now, if you would just configure a plain URL, and we would display it, that would not be secure at all. To fix this, you need to configure an endpoint which is generating and returning a secure URL. This URL should include a timestamp until which this URL is valid. Then the integration framework will know when to request a new one.
Getting the secure URL

This is the format we expect as a response from your secure-URL endpoint:

{
    url: string,
    expTimestamp: datetime
}

When constructing the secure URL, you can go wild and implement whatever security magic you want, but we recommend to do at least these:

  • Use https, this is enforced by the browser because iframes are active mixed content. You can read more about it on MDN.
  • Use a reference token to identify the account, not a plain text ID (neither from your, nor from our side). This can be a signed JWT which you'd recognise, or some long random string (like a GUID) which you map in your database.

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.

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

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