Salesforce Canvas Pages: Building Seamless Integrations

BookingBug is a broad and sophisticated platform with a huge range of configuration and customization options to let businesses use the platform in exactly the way they need.

However, when we integrated with Salesforce we wanted a solution that gave users the best and most seamless experience from within Salesforce. One solution would have been to rebuild BookingBug completely as a native Salesforce App, however wanting to get something released in less than the six years it took us to build BookingBug the first time around, we needed a solution that worked quickly, but let us smoothly segment parts of BookingBug directly into different Salesforce screens.

The problem with embedding an existing platform

Salesforce has for some years had methods for allowing the adding of iframes directly anywhere you can add a Visual Force page – which could be a tab, a section in a Publisher feed, or it could be just be a block within a layout of a specific Object. This is really the only way of effectively combining an existing web platform into Salesforce.

However, this method does suffer from a number of drawbacks, that potentially limit their use.

  • Lack of authentication or authorization
  • Fixed size
  • Poor mobile experience
  • No context

The first of these is a real drag for external apps that have their own existing authentication and authorization structures. For us it is paramount that when rolling out to a large organization, not to impose yet another system in which to have to add every one of their staff accounts and set their access levels – that’s why they purchased Salesforce in the first place – the give them a single platform! Unfortunately with iframes there was no good or secure way of doing this, without rolling your own complex Single Sign-On methods and passing them in the URL, or requiring a double sign in.

The second of these is a real drag when you want to create a smooth, seamless user experience. If your embedded app involves anything remotely complex, it’s hard to provide a rich experience in a fixed height – without creating embedded scroll bars, or simply having to link out to an external page. Both of which provide a terrible user experience.

Next, of course, mobile is increasingly vital for businesses, and Salesforce1 is an important part of Salesforce’s customer strategy. We found that other than the sizing issues, loading a Visual Force page that in turn loaded an APEX iframe actually involved so many iframes embedded in iframes, that the experiences were simply too slow and too clunky.

Finally: context. We wanted to build a lot of integrations in places all over the Salesforce app, and with each one we wanted to understand the context of the page and the data we were looking at. For each iframe, we had to write a lot of custom APEX code to discover this and only then try and securely pass it into the iframe itself.

Enter the Salesforce Canvas

The Canvas is fairly new to Salesforce and while we were possibly a little slow to realize the scope of what it could do, Salesforce has continued to expand it’s features over the past year and it was our Salesforce Technical Evangelist who switched us on to how it could benefit our project.

The Salesforce Canvas, we found, solves almost all of the issues we found with iframes, and most importantly it was insanely easy to implement – we went from reading it to having our app working with it in multiple uses cases in less than a day!

Essentially a Canvas is just an iframe. However, it’s an iframe that passes you a huge amount of context.

BookingBug as a platform is written in Ruby on Rails, and we were already using OAuth keys, and the Force Rails gem to connect to our Salesforce app. This means, all we had to do was create a Canvas that pointed to a controller and view in our core rails app. The data passed into the view we simply passed into the decodesignedrequest() function with our keys and boom – we suddenly had all of the information we could possibly want and more besides. And best of all because it was encoded with the Salesforce OAuth key, we knew we could trust that it came from Salesforce and was valid.

The data includes:

  • Organization and instance details
  • Full user details
  • Application details
  • Environment and dimension
  • API version
  • The current record
  • Custom parameters

With that information we could immediately do a number of critical things:

  1. Identify the correct business in BookingBug that has already preconfigured their Salesforce and BookingBug connectivity using the Organization details
  2. Identify the staff member/user and either log them into to BookingBug or ensure they had the correct permissions
  3. Ensure any page we showed had the correct dimensions and layout using the environment parameters
  4. Using the custom parameters, show different pages under different contexts, which we controlled using different Visual Force Pages

This first version, identifying the organization and user and showing them the correct page securely, we got working within an hour or so of first setting up our Canvas pages.

Pushing things a little further

Next we started to add a little more sophistication. We discovered that the Salesforce Javascript library, into which we could load our decoded context, could communicate outside the iframe with the top level Salesforce app – something we’ve struggled to do before with the cross domain limits of Visual Force pages. In particular, it allowed iframe resizing. 

This was supposed to have two modes, one that allowed you to set a specific size, and another that was supposed to auto-size the iframe. We found the auto-sizing did not work as advertised – however it was trivial to write a short Javascript that kept track of the size ourselves and called the manual size set, to the same effect. Luckily for BookingBug – we’ve been dealing with iframe widgets and resizing across domain for years, so it was hardly a challenge. There were a few sizing confusions between Salesforce1 and desktops, but the some tweaking we were able to provide clean scrolling interfaces for mobile and nice resizing interfaces on desktop.

The next interesting aspect was when we realized we were getting valuable contextual information, including the Object type and ID if they were relevant to the canvas at that time.

It was trivial then to use the REST to dig more into that record. Sometimes, we didn’t need it, just the record ID was enough to identify the context. Other times, we could use the REST API to pull up more information about the relevant record, be that a Contact, or a Lead.

Finally, the last issue was speed. I don’t think I’d be the first one to say that Salesforce can sometimes be a little sluggish. Given how much it’s doing that’s not surprising – however, the Canvas pages were noticeably faster than the iframe mess we had before.


In short, as you may be able to tell I was pleased with the Canvas for it’s ease of implementation and sophistication, and it stands above other authentication and access methods in platforms, particularly given the number of places you may need to use it within a large Salesforce app. That said, it’s not without it’s foibles. Resizing is intermittent and sizing params are sometimes weird (please why tell me the max height is 14px on a mobile!?). I’d also like to be able to pass other custom params in without relying on a Visual Force page to do so, such as in Publisher Feeds and other circumstances, but given how quickly Salesforce adds and implements many changes, I’m sure changes will not be far behind!

If you want to see the BookingBug for Salesforce in action join us at Dreamforce stand N2320 for a hands-on demo. You can find more on that here.