Skip to main content

Analytics for App Home

Analytics web components display ShopifyQL data as charts, tables, and lists. A metric card runs a ShopifyQL query and renders the result. A metrics bar arranges cards in a row.

Use these components to add live analytics to an app in App Home without building your own charts.

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

<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script>
<script src="https://cdn.shopify.com/shopifycloud/analytics-ui-1.js"></script>
</head>

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.

ComponentWhat it does
Metric cardRenders one ShopifyQL result as a chart, table, or list.
Metrics barGroups 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.


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

<s-shopifyql-metric-card
heading="Total sales"
query="FROM sales
SHOW total_sales
TIMESERIES day
WITH TOTALS, PERCENT_CHANGE
DURING last_month
COMPARE TO previous_period
ORDER BY day ASC
VISUALIZE total_sales TYPE line"
></s-shopifyql-metric-card>

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

<s-metrics-bar accessibilityLabel="Store performance">
<s-shopifyql-metric-card
heading="Total sales"
query="FROM sales
SHOW total_sales
TIMESERIES day DURING last_month
VISUALIZE total_sales TYPE line"
></s-shopifyql-metric-card>
<s-shopifyql-metric-card
heading="Orders"
query="FROM sales
SHOW orders
TIMESERIES day DURING last_month
VISUALIZE orders TYPE line"
></s-shopifyql-metric-card>
</s-metrics-bar>

To use analytics web components, configure the following access requirements:

  1. Enable direct API access by setting embedded_app_direct_api_access to true under [access.admin] in your app's shopify.app.toml configuration file.
  2. Request the read_reports access scope so that your app can read analytics and reporting data.
  3. 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' to script-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.com in script-src, so that the required scripts load.
  • Allow https://cdn.shopify.com in connect-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.

Info

'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

Content-Security-Policy: script-src 'self' https://cdn.shopify.com 'wasm-unsafe-eval'; connect-src 'self' https://cdn.shopify.com;

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.


Was this page helpful?