Customizing Your App Lifecycle

By providing a custom Apex class, you can control the context information that’s sent to your canvas app and add custom behavior when your app is rendered.

Salesforce provides several Apex interfaces and classes in the Canvas namespace that provide additional control over the canvas app lifecycle. You can use the Canvas namespace and the CanvasLifecycleHandler interface to:

Control what sections of the CanvasRequest Context data get sent to your app. You can, for example, require that Salesforce never send the Organization information in the CanvasRequest data. Excluding sections of context data improve performance by reducing the amount of data that’s sent in the request and remove the need to process the organization data in your app.
Retrieve application context data when the app is rendered and alter the behavior of your app accordingly. You can obtain the application version and, depending on the version, change how the app runs.
Modify some of the context data, such as the canvas app URL, custom parameters, or the list of object fields that are returned in the Record data when the app is rendered.
Present a well-formed error message to the user in the Salesforce UI if something goes wrong.

Salesforce also provides a Test class in the Canvas namespace that you can use to create test context data and verify the behavior of your lifecycle handler without having to run your app.

Reference documentation for the Apex Canvas namespace is provided in the Apex Code Developer Guide.

Creating a CanvasLifecycleHandler

You can control your app lifecycle by providing an implementation of the Canvas.CanvasLifecycleHandler Apex interface that Salesforce can use.
Associating Your CanvasLifecycleHandler with Your App

After you’ve created an Apex implementation class for CanvasLifecycleHandler, you need to associate it with your canvas app by adding the class name to your canvas app configuration settings.
Filtering CanvasRequest Context Data

To filter out parts of the CanvasRequest Context data that gets sent to your canvas app, you need to provide an implementation of Canvas.CanvasLifecycleHandler.excludeContextTypes().
Controlling Canvas App Behavior

To modify the default behavior of the signed request, you need to provide an Apex class that implements Canvas.CanvasLifecycleHandler.onRender() and associate this class with your canvas app. In your onRender() implementation, you can control app behavior with custom code.
Presenting User Error Messages

You can use Canvas.CanvasRenderException to display error messages to the user.
Testing Your CanvasLifecycleHandler Implementation

You can use the Canvas.Test class to test your Canvas.CanvasLifecycleHandler.onRender() implementation without having to run your canvas app.
Distributing Your CanvasLifecycleHandler Class

If you package and distribute your canvas app, make sure to include your CanvasLifecycleHandler class in your package.