Anchor to Getting startedGetting started
To use analytics components in your app, you need to import the analytics UI library using a script tag.
This library has dependencies on the Polaris and App Bridge libraries, so make sure your app imports them too in the order shown in the example. You also need to specify your app’s API key.
To learn more see Adding App Bridge to your app and Adding Polaris to your app.
Before you start, check the access requirements.
HTML
Anchor to ComponentsComponents
Use metric cards to handle queries and display the results. Metrics cards send the query through App Bridge, wait for the response, format the values, and render a visualization.
To arrange metrics cards in your app, use the metrics bar component. A metrics bar handles only layout; it doesn't run ShopifyQL.
Each component is a custom element that you add to your HTML.
| Component | What it does |
|---|---|
| Metric card | Renders one ShopifyQL result as a chart, table, or list. |
| Metrics bar | Groups metric cards into a row with consistent spacing and a shared loading state. |
Metric cards wait for initialization internally. To choose your own loading or unavailable state, check availability with the ShopifyQL API.
Anchor to QueriesQueries
Add a ShopifyQL query to a metrics card component using the query property. Use the VISUALIZE clause in your query to select between different chart type such as trends over time, comparisons, percentage breakdowns, and ranked lists.
See Metric card to learn more.
HTML
Anchor to LayoutLayout
Wrap metric cards in s-metrics-bar to lay them out in a row with consistent spacing, sizing, and a shared loading state. The bar sizes the cards for you, so you don't need to set size on each card. When the cards overflow, the row scrolls horizontally.
You can add an s-metrics-bar-date-picker to the bar to show a range selector above the cards. The picker fires a change event when the selection changes, but it doesn't rewrite card queries. Listen for the event and update each card's query with the matching date range.
To learn more, see Metrics bar.
HTML
Anchor to Access requirementsAccess requirements
To use analytics web components, configure the following access requirements:
- Enable direct API access by setting
embedded_app_direct_api_accesstotrueunder[access.admin]in your app'sshopify.app.tomlconfiguration file. - Request the
read_reportsaccess scope so that your app can read analytics and reporting data. - Request Level 2 access to protected customer data.
Anchor to Content Security PolicyContent Security Policy
The analytics UI script downloads the ShopifyQL parser and compiles it from WebAssembly in your app's iframe. If your app sets a Content Security Policy, then update it on every route that renders analytics web components:
- Add
'wasm-unsafe-eval'toscript-src, so that the browser can compile the parser. Without it, the browser blocks the parser and metric cards don't load data. - Allow
https://cdn.shopify.cominscript-src, so that the required scripts load. - Allow
https://cdn.shopify.cominconnect-src, so that the analytics UI script can download the parser and its translations.
If your policy omits script-src or connect-src, then the browser applies default-src in its place, so add these sources to default-src.
Bubble maps need additional Content Security Policy sources. See Bubble maps.
'unsafe-eval' also lets the browser compile WebAssembly, but it allows JavaScript eval() as well. Use 'wasm-unsafe-eval', which allows only WebAssembly.
'unsafe-eval' also lets the browser compile WebAssembly, but it allows JavaScript eval() as well. Use 'wasm-unsafe-eval', which allows only WebAssembly.
HTTP header
Anchor to Versioning and compatibilityVersioning and compatibility
Analytics UI uses a separate version scheme from Polaris. See Versioning and compatibility for script and TypeScript guidance.