Canvas App Previewer
The Canvas App Previewer is the Salesforce developer tool that lets engineers test a Canvas App before publishing it to end users.
Definition
The Canvas App Previewer is the Salesforce developer tool that lets engineers test a Canvas App before publishing it to end users. Canvas Apps are third-party web applications embedded inside Salesforce (in the Service Console, on Lightning record pages, in Chatter publisher) through the Canvas framework. The Previewer is a Setup page that mimics how the Canvas App will appear inside Salesforce, lets the developer feed in a context (a record ID, a user, a session), and renders the app live. It is the standard testing surface during Canvas App development before the app gets a Connected App registration and is rolled out to production users.
Canvas App Previewer matters because Canvas Apps are complex integrations. The framework passes a signed JSON payload with user, org, and record context to the embedded web app via OAuth. Testing all the moving parts (the auth handshake, the signed payload, the iframe rendering, the cross-window messaging back to Salesforce) without the Previewer would require manually building and tearing down a Connected App for every test cycle. The Previewer makes the loop short: paste the Canvas App URL, run the preview, debug the integration. Once it works in the Previewer, the integration is ready for production registration through Connected Apps.
How the Canvas App Previewer fits Canvas App development
What a Canvas App is
A Canvas App is a third-party web application that embeds inside Salesforce. The framework passes user, org, and record context to the external app via a signed JSON payload (signed OAuth or signed request). The app renders inside an iframe in the Service Console, Lightning record pages, or Chatter publisher. Canvas Apps existed before Lightning Web Components and are still used for integrations that need their own UI hosted elsewhere.
How the Previewer works
The Previewer is at Setup, search for Canvas App Previewer. The page takes a Canvas App URL plus a context (a record ID, a user ID), simulates the signed payload Salesforce would send to a production Canvas App, and renders the result in a frame. Developers iterate on the external web app and refresh the Previewer to see the result.
Authentication during preview
The Previewer uses the running user's session to construct the signed payload. The external Canvas App receives the same payload it would in production, which lets developers test the full OAuth handshake plus the context propagation. After preview validates, the app gets registered through a real Connected App for production rollout.
Connected App registration
Production Canvas Apps register through Setup, App Manager, New Connected App. The Connected App configuration includes the Canvas App URL, OAuth scopes, and signed-request settings. The Previewer skips this registration step, letting developers iterate before committing to the Connected App configuration.
Lifecycle from Previewer to production
Typical development flow: build the external web app, host it on a developer URL, test through Canvas App Previewer, register a Connected App when the app stabilises, assign permissions to test users, validate in sandbox, promote to production. The Previewer is the early-stage loop; the rest is standard Connected App lifecycle.
Canvas App declining popularity
Canvas Apps were popular when Lightning Components and LWC did not yet exist. Modern Salesforce development favours LWC for in-platform UI and uses Canvas Apps only when the external app must be hosted outside Salesforce (legacy systems, third-party UI components, partner-built tools). New development rarely starts with a Canvas App.
Debugging through the Previewer
The Previewer surfaces the signed payload, the iframe behaviour, and any Canvas API calls back to Salesforce. Browser developer tools work normally inside the Previewer iframe, which lets engineers debug the embedded web app with familiar tools. Most Canvas App debugging happens in this loop.
Common pitfalls
Three patterns recur. Developers who skip the Previewer and go directly to Connected App registration spend longer debugging. Cross-origin iframe issues hide until the app is embedded; preview reveals them early. And signed-request validation failures on the external app side trace to clock skew or incorrect Consumer Secret usage, both of which the Previewer surfaces clearly.
How to test a Canvas App in the Previewer
The Previewer is a developer-time tool. Use it for every iteration of the external app before committing to a Connected App registration.
- Host the external Canvas App
Deploy the external web app to a publicly-reachable HTTPS URL (a local tunnel or staging URL works for development).
- Open the Canvas App Previewer
Setup, search for Canvas App Previewer. Paste the Canvas App URL.
- Configure the preview context
Set the record ID, user, and any expected context attributes. The Previewer constructs a signed payload from these values.
- Run the preview and debug
Click Preview. The Previewer renders the Canvas App inside an iframe. Use browser dev tools to debug the embedded app and the signed payload it receives.
- Register the Connected App for production
Once preview validates, register the Canvas App through a Connected App in Setup. Configure scopes, callback URL, signed-request settings, and assign access to the right users.
- Skipping the Previewer and registering directly as a Connected App lengthens debug cycles significantly.
- Cross-origin iframe issues hide until embedding. The Previewer reveals them; standalone testing of the external app does not.
- Signed-request validation failures trace to clock skew or Consumer Secret mismatches. Both show up clearly in Previewer logs.
- New Salesforce development should default to Lightning Web Components, not Canvas Apps. Only use Canvas for legitimately external-hosted UI needs.
Trust & references
Cross-checked against the following references.
- Canvas Developer GuideSalesforce Developer Docs
- Connected AppsSalesforce Help
Straight from the source - Salesforce's reference material on Canvas App Previewer.
- Canvas Signed RequestSalesforce Developer Docs
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. Who can benefit from understanding Canvas App Previewer?
Q2. What architecture concept is Canvas App Previewer an example of?
Q3. How does Salesforce's multi-tenant model affect Canvas App Previewer?
Discussion
Loading discussion…