UNPKG

@canva/cli

Version:

The official Canva CLI.

85 lines (55 loc) • 4.42 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
# Data Connector Template ## Overview This template provides a working example of a data connector app which uses the Canva Connect API as a data source. It demonstrates how to log in with OAuth and then fetch data from an external source, using Canva's API for listing Designs and Brand Templates. There are instructions below for how to configure your authentication settings to try it out. The template provides a list / detail interface for choosing a data source. The user would first select the data source they want to import from a list. Next, they configure the data source to select the desired query by applying search filters or sort criteria. The app turns their configured data source into an API request and then returns the data in a table format for use in a Canva Design. ## Best Practices This template captures best practices for improving user experience in your application. ### State Management In this template, we've set up state management using `React Context`. It's just one way to do it, not a strict rule. If your app gets more complicated, you might want to check out other options like `Redux` or `MobX`. ### Routing As your application evolves, you may find the need for routing to manage multiple views or pages. In this template, we've integrated React Router to illustrate how routing can facilitate seamless navigation between various components. ### App UI Kit The App UI Kit is a React-based component library designed for creating apps that emulate Canva's look and feel. We strongly recommend using the App UI Kit if you're planning to release an app to the public, because this makes it easier to comply with our [design guidelines](https://www.canva.dev/docs/apps/design-guidelines/). ### Data Sources A data source is a type of data that this connector can retrieve. It has: - properties that define the configuration for this source - e.g. search criteria, ordering conditions, selection filters - UI for how to edit this configuration - columns to display for each data item - logic for how to fetch the data from an external API The initial data sources for the Canva Connect API (Designs and Brand Templates) in this template are located in `src/api/data_sources/`. This template provides a `DataSourceHandler` class in `src/api/data_source.ts` as a suggested starting point for defining a reusable concept for a data source and convert API responses into data table outputs. ## Setup - Authentication This template is a working app that reads the [Canva Connect API](https://www.canva.dev/docs/connect/). To run it and authenticate with the Canva Connect API via OAuth you must first complete some authentication setup steps. ### 0. Set up an App - If not already handled by the Canva CLI, you need to create an app. Go to [Your Apps](https://www.canva.com/developers/apps) and create an app. - On the **Configuration** page, enable the `Data Connector` intent. ### 1. Set up a Connect API Integration - Go to [Your Integrations](https://www.canva.com/developers/integrations/connect-api) and create a new integration - On the **Configuration** page, generate a client secret - you need the client ID and client secret in the app setup. - On the **Scopes** page, add the `designs:meta` and `brandtemplate:meta` read scopes - On the **Authentication** page, set `https://www.canva.com/apps/oauth/authorized` as an Authorized redirect ### 2. Set up OAuth for the app - Go to [Your Apps](https://www.canva.com/developers/apps) and open your data connector app. - On the **Authentication** page, add an OAuth 2.0 provider with the following settings: > Provider: `CanvaConnect` > > Client ID: `(generated in step 1)` > > Client secret: `(generated in step 1)` > > Credential transfer mode: `Headers (default)` > > Authorization server URL: `https://www.canva.com/api/oauth/authorize` > > Token exchange URL: `https://api.canva.com/rest/v1/oauth/token` > > Proof Key for Code Exchange (PKCE): `Enabled` ### 3. Run your app - Run `npm start` to run the app. - You should be able to log in and then choose from the available data sources. ### To use another OAuth source - `src/api/oauth.ts` has a `scope` property that will be used in the oauth flow. - This template starts with the scope for the Canva Connect API login set to `["design:meta:read", "brandtemplate:meta:read"]` - It should match the scopes set in Step 1.