trailhead

Use Heroku to Run Salesforce Canvas Apps

Learning Objectives

After completing this unit, you'll be able to:

  • Understand the authentication process of Canvas apps.
  • Understand how to use Heroku to run Salesforce Canvas apps.

Salesforce Canvas

With Salesforce Canvas, you can embed a UI or web app that runs on Heroku into the Salesforce UI. The primary advantage of Canvas is the ability to use a plethora of open-source web technologies to build a web app that easily integrates with Salesforce. The Canvas SDK is used from JavaScript in a web app to access Salesforce data that the user has access to. You can develop Canvas apps on your local machine and use typical developer flows for change management and deployment.

Under the covers, Canvas apps are loaded into Salesforce through an iframe. Of course, you can load any web app into Salesforce’s UI through an iframe, but with Canvas you can use a secure communication protocol via JavaScript to communicate with Salesforce. When you need functionality beyond what the Canvas JavaScript API implements, you can combine the authentication handled by Canvas with the Salesforce REST APIs, potentially using a REST API wrapper like JSforce.

Diagram showing that Heroku apps can interact with Salesforce through a Canvas Javascript bridge

Authentication

Canvas apps use a connected app in Salesforce and can use either a signed request or the typical OAuth flow to handle authentication. One advantage of a signed request method is that when a Salesforce admin has permitted users to access the Canvas app, no intermediate authorization is required for the app to make requests to Salesforce. After the Canvas app has been loaded, the app can begin accessing Salesforce data that the user has access to.

When running a Canvas app on Heroku, the app needs the connected app's consumer secret, which is provided to the app through a Heroku Config Var, available to the app as an environment variable.

Basic Canvas App

A basic Canvas app loads the Canvas SDK JavaScript library:

<script type="text/javascript" src="https://.salesforce.com/canvas/sdk/js/36.0/canvas-all.js"></script>
<script type="text/javascript">
    // callback to access the OAuth access token and context object
    Sfdc.canvas(function() {
        // Save the token
        Sfdc.canvas.oauth.token(window.signedRequestJson.oauthToken);
        window.alert("hello, " + window.signedRequestJson.context.user.fullName);
    });
</script>

The context data of the app depends on where the app is running within Salesforce. You can load Canvas apps into Chatter feeds, Chatter tabs, layouts, mobile cards, publisher actions, and VisualForce pages. Each can provide a different context to a Canvas app. For instance, if a Canvas app is rendered in an account page’s layout, the context contains the account’s data. JavaScript in the Canvas app can then use that data to render the information.

Resources

retargeting