Canvas Docs
Search
K

Embeds

Step-by-step guide for using Canvas to create embeds for your application

Embed Walkthrough

We will walk through the full embed process, from creating your embed in Canvas to embedding this in your own product. We will also handle displaying different data for each of your users.
This example is from the perspective of a Canvas customer Acme. Acme wants to embed a chart in their application that shows Acme users their usage activity in the Acme platform. We assume that Acme has already connected this usage data to Canvas.

1. Create the chart in Canvas

First we pull in the User Activity table. This table contains all the events that occurred in Acme, across all accounts.
Next we create a chart that shows the count of unique Session IDs, aggregated by week.
This chart shows sessions across all customers, but Acme wants to show only each of their customers the activity from their account. To do this, we add a global filter on the User Domain field. This allows us to select from the list of User Domains and filter the dataset to just that domain:
If we select [ford.com](<http://ford.com>) we will see only the events filtered to that user domain:
We’re now ready to create our embed. From the dropdown menu we select Save embed
This opens a menu where we can pick what filters should be required when accessing this embed. Acme wants to enforce that their customers can only see the events data scoped to those from their domain, so we include this filter as a scope. The scope user_domain entered here will now be required in the authorization grant for any user accessing this embed.
After clicking save we’re given the Embed ID and an example scope payload to use in our own application.
Finally we need to generate an Embed API Key. Navigate to the settings page and scroll to the Embed API section to generate a key. Keep this key secure; this key as the ability to generate authorization tokens granting access to your data.

2. Adding embeds to your application

Now that we’ve built the embed in Canvas we can add this to Acme’s app. This requires changes on the frontend and backend.
On the frontend, we use Canvas’ React library to add the chart component using the Embed ID from above:
import { Chart } from "canvas-embed";
import "canvas-embed/dist/index.css";
<Chart
chartId={embedId}
authToken={authToken}
/>
We use the backend to generate the authToken. We need to generate a token that grants access to the scopes we defined in our embed, specific for the Acme user in question. This implementation will depend on your backend and the scopes required. Acme uses Rails and in this case needs to grant access to the user’s domain:
class ApplicationController < ActionController::Base
def generate_embed_token
# this is the secret signing key from Canvas
key = ENV['CANVAS_SIGNING_KEY']
user_domain = Current.user.domain
scopes = { user_domain => user_domain }
authorization_duration_seconds = 7200
authToken = Canvas::Embed.generate_embed_token(key,
scopes,
authorization_duration_seconds,
Current.user.external_id
)
render json: { 'authToken' => authToken }
end
end
We use the authToken returned by this function in the Chart component. We can re-use this token for any other embeds the user might have on this page.