The Canvas SDK is versioned starting in the Spring ‘13 release. I sat down with Jay Hurst, the PM for Canvas, to talk with him about the SDK and how it’s versioned.

D: Jay, thanks for meeting with me.

J: No problem.

D: So today we’re going to talk about versioning of the Canvas SDK. What’s that all about?

J: Well, I thought I’d cover three main points: why we did it, what we did and the migration path for developers.

D: Sounds great.

J: I’ll start with why we did it. As you know, Winter ’13 was the first release of the feature in pilot including the SDK on GitHub. As we were working on the feature for the following release, Spring  ’13, we realized that we were going to have to add new functionality and change some functionality. So one of the side effects of those changes was that the SDK would break compatibility.

We looked at what the other teams in Salesforce–like the API team and the Chatter team–were doing around versioning and how they support backwards compatibility. As a result, we felt this was the best thing to do now and long-term for our customers and partners that are using Canvas.

In a nutshell, we’re versioning each release of the Canvas SDK such that when we go from Winter release to Spring release or Spring release to Summer release, our customers’ code isn’t going to break. Essentially, versioning allows us to support backward compatibility.

D: So that explains the “why.”

J: Right. Now, for what we did. At the mechanical layer, we implemented versioning by adding version information to the signed request. For Spring ’13, the version is 27.0 which aligns with our API versions.

Here’s an example of the version information in the signed request:
"api": "27.0",
"season": "SPRING"

As a developer, when you make a call back through the Canvas SDK into Salesforce, you provide the version of the SDK that you’re using. Then on the Salesforce side, we can see ‘Oh, they’re using version 27.0.’ We then know what the SDK expects in the JSON being returned and can send back the correct information.

D: It’s great that the versions match the version of all the other APIs.

J: Exactly. So version 27.0 came out in Spring ’13. When we move to Summer ’13, everything will go to version 28.0, and so on.

D: Finally, you were going to talk about migration?

J: Now when we start to think about how to migrate existing canvas apps, it can be a little bit tricky depending on what your canvas app does. The process varies for each customer depending on how they’re using the Canvas SDK.

If you have a simple Web app exposed as a canvas app, and it doesn’t use the SDK–a clock app, for example–then your app won’t break. That said, we still recommend that you upgrade and upgrading will be pretty straightforward. If you’re not using the authentication piece and you’re not making AJAX calls back and forth, then it’s not too difficult to upgrade.

Similarly, if you’re just using canvas as a means to get the authentication information for Salesforce and perform server to server side calls, your app may still function.  So, if you use the signed request to pull out the OAuth token and then you’re using that token to make a SOAP API call from your server to the Salesforce server, your canvas app may still work.

Really, it’s only if you’re making cross-domain calls using our XHR bridge, that’s when you’re going to have to make some changes.

D: That’s good to know. So, if someone’s being testing out Canvas in the pilot version, and they don’t have a complex integration, then upgrading won’t be too difficult.

J: Right. The structure of the signed request JSON that we send back has changed, so they should upgrade. And you can see the structure of the signed request in the Canvas Developer’s Guide.

We’ve moved a few things around, for example, the OAuth token used to be at the root level, but now it’s inside of the Client object, added version information, things like that. So we recommend that everyone upgrade to the latest and greatest.

Just to clarify, when I say “break,” it’s not that your canvas apps are now unsecure or you’re going to lose data or anything like that. But since we moved things around in the signed request JSON and relocated fields in the Client object, your canvas app may not work as it did previously.

D: Can you give an example of one of those changes?

Sure. So, for example, in code prior to Spring ’13, when making a call in, in the AJAX call, you’d set the token to be equal to your OAuth token. There was a key/value pair with the key name being “token” and the value being your scoped access token. In the new version, instead of having the token key, we have something called a client key. The Client is actually an object that contains other information in addition to the token.

D: Great, thanks. Developers can get the latest version 27.0 of the SDK on GitHub, right?

J: Exactly, it’s on GitHub at If you need the previous version, the explains how to check it out.

D: Awesome. Thanks for explaining this!

J: No problem, Dianne. We are definitely excited to see what our customers and partners build using Canvas.

Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS