---
title: Analytics for App Home
description: 'Display ShopifyQL data as charts, tables, and lists in apps in App Home.'
api_version: v1.0
source_url:
  html: 'https://shopify.dev/docs/api/analytics-ui/latest'
  md: 'https://shopify.dev/docs/api/analytics-ui/latest.md'
api_name: analytics-ui
---

# Analytics for App Home

Analytics web components display [ShopifyQL](https://shopify.dev/docs/api/shopifyql/latest) 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](https://shopify.dev/docs/api/app-home/latest) without building your own charts.

## Getting 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](https://shopify.dev/docs/api/app-home/latest/apis#adding-app-bridge-to-your-app) and [Adding Polaris to your app](https://shopify.dev/docs/api/app-home/latest/web-components/versioning#adding-polaris-to-your-app).

Before you start, check the [access requirements](#access-requirements).

## HTML

```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>
```

***

## Components

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](https://shopify.dev/docs/api/analytics-ui/latest/metric-card) | Renders one ShopifyQL result as a chart, table, or list. |
| [Metrics bar](https://shopify.dev/docs/api/analytics-ui/latest/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](https://shopify.dev/docs/api/analytics-ui/latest/apis/shopifyql-api).

***

## Queries

Add a ShopifyQL query to a metrics card component using the `query` property. Use the [`VISUALIZE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/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](https://shopify.dev/docs/api/analytics-ui/latest/metric-card) to learn more.

## HTML

```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>
```

***

## Layout

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](https://shopify.dev/docs/api/analytics-ui/latest/metrics-bar).

## HTML

```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>
```

***

## Access requirements

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](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration).
2. Request the `read_reports` [access scope](https://shopify.dev/docs/api/usage/access-scopes) so that your app can read analytics and reporting data.
3. Request [Level 2 access to protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).

***

## Content 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](https://shopify.dev/docs/api/analytics-ui/latest/metric-card#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

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

***

## Versioning and compatibility

Analytics UI uses a separate version scheme from Polaris. See [Versioning and compatibility](https://shopify.dev/docs/api/analytics-ui/latest/versioning) for script and TypeScript guidance.

***
