> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the public docs of Meridian for Shopify apps: hosting, billing (Plan Builder and the @the-meridian/sdk package), CRM, emails and automations for Shopify app developers.
> Start with these pages: Meridian MCP (https://help.the-meridian.ai/mcp-server.md) to connect a coding agent, AI coding agents (https://help.the-meridian.ai/ai-agents.md) for the agent skill, SDK quickstart (https://help.the-meridian.ai/sdk-quickstart.md), Running your app with the CLI (https://help.the-meridian.ai/cli-dev.md), Deployment (https://help.the-meridian.ai/deployment.md), and Errors (https://help.the-meridian.ai/errors.md) to look up an error code or message.
> Fetch one page at a time as Markdown (the page URL followed by .md), using the index in https://help.the-meridian.ai/llms.txt. llms-full.txt holds every page in one file of about 900 KB, so avoid loading it whole.
> With Meridian MCP connected, search these docs with docs_search and docs_get, and read live facts (feature and event keys, plan ids, environments, deployments, logs) from the MCP tools instead of guessing them.

# Web Vitals: how fast your embedded app loads

> Meridian reads LCP, INP and CLS from Shopify App Bridge in your embedded app, scores them like Built for Shopify, and shows them on Home and in four built-in reports.

Shopify scores an embedded app on three Core Web Vitals, measured in the merchant's browser. Built for Shopify needs the 75th percentile (p75) of each to stay under a limit. Meridian collects the same figures from your app and shows where you stand, before Shopify tells you.

It is on by default for apps that use the [React SDK](https://help.the-meridian.ai/sdk-provider.md). There is nothing to set up, and no separate page: the figures are on [Home](https://help.the-meridian.ai/home.md) and in four [built-in reports](https://help.the-meridian.ai/report-builder.md#built-in-reports).

## What is collected

[`MeridianProvider`](https://help.the-meridian.ai/sdk-provider) subscribes to the Web Vitals that Shopify App Bridge reports for your embedded app, and sends these three to Meridian:

| Metric | What it measures | Built for Shopify limit |
| - | - | - |
| **LCP** (Largest Contentful Paint) | How long the main content of a page takes to appear | 2.5 s |
| **INP** (Interaction to Next Paint) | How long the page takes to update the screen after a click, tap or key press | 200 ms |
| **CLS** (Cumulative Layout Shift) | How much the content moves on its own while the page is open | 0.1 |

App Bridge also reports FCP and TTFB. The SDK drops them, and Meridian stores nothing else from the report.

Each sample carries the metric and its value, the page the app opened on, the device (desktop or mobile), the store, and the time Meridian received it. It carries no user agent, no IP address and no identity of the person using the app. The country App Bridge reports is not sent.

## How it is counted

* **One page view is one load of your app.** App Bridge hands over the load's LCP, INP and CLS once the merchant interacts with the page. A load the merchant leaves without a click or a key press in your app may not be counted.
* **Every sample counts against the page the app opened on.** App Bridge does not say which screen a report comes from, so the SDK sends the route the app loaded on with every metric of that load. A merchant who opens `/app` and then moves to `/app/bundles/:id` inside the app counts once, on `/app`: a slow click or a layout shift on the bundle screen counts against `/app`. A screen gets samples of its own only when the app opens on it, after a reload or from a link straight to it.
* **p75 uses the nearest rank.** The value that 75% of samples are at or under, with no interpolation. Home and the reports use the same calculation.
* **The window is the last 28 days**, today included. The reports compare with the 28 days before.
* **At least 100 samples** of a metric are needed before Home says whether it passes. A page counts as failing only with at least 100 page views in the window and a p75 over a limit.
* **Test stores are left out** (development stores and stores with only test charges), as in the rest of Meridian.
* **The figures are self-reported by your app's own frontend.** Meridian records what the browser sends, rate-limited and checked for range, and cannot verify it. Delivery is best effort: the SDK sends half a second after App Bridge reports, so a load the merchant leaves within that half second, or a request the browser drops, is never counted. Your p75 can differ from the one Shopify scores.

## Pages

Meridian stores the route, not the address. Anything that looks like an identifier or personal data becomes `:id`:

* the query string and the hash are dropped,
* a segment that is all digits, a UUID, a long hex string, a Shopify global id, a long token with a digit, or anything with a character outside letters, digits, `-` and `_` (an email address, a file name, an encoded value) becomes `:id`,
* a route keeps at most 8 segments and 200 characters.

So `/app/bundles/123` is stored as `/app/bundles/:id`, and `/app/customers/jane@shop.com` as `/app/customers/:id`. A short plain word stays as it is, because it cannot be told from a route name: keep search terms and names in the query string, which is dropped, not in the path.

An app is kept to 500 distinct pages. Pages seen after that are stored as `/(other)`.

## Where you see it

* **Home**: the **Built for Shopify** card shows LCP, INP and CLS over the last 28 days, each with its p75, whether it passes, and how far it is from the limit. Its **Built for Shopify** badge is greyed out until all three pass, and hovering it lists the requirements. A row in **Needs attention** says how many pages fail. See [Home](https://help.the-meridian.ai/home.md).
* **Reports**: four built-in reports under **Web performance**. **Web Vitals by day** is a table of LCP, INP and CLS p75 for each day. **LCP by day**, **INP by day** and **CLS by day** are line charts, each against its limit. They read the **Page views** dataset, so you can group by page or device, filter, change the period and compare. See [Report Builder](https://help.the-meridian.ai/report-builder.md).

## Limits

| | |
| - | - |
| Requests | 20 a minute per store, and 6,000 a minute per app |
| Samples stored | 3,000 a day per store. Above that, requests are accepted and the samples are dropped |
| Pages | 500 per app, then `/(other)` |
| Batch | At most 30 metrics and 5 page views per request |

A request over the rate limit answers `429`. These requests are not counted against your plan's SDK request allowance.

## Plans

Web Vitals are available on every plan that includes the SDK. The Private plan has no SDK, so there is nothing to send. They are not metered and not part of the Plan Builder.

## Data and retention

Samples are kept for 180 days, then deleted. They are deleted with the app, and for one store when Shopify sends that store's `shop/redact` request. They are never shown to anyone but the app's own members.

## Turn it off

Pass `webVitals={false}` to the provider:

```tsx theme={null}
<MeridianProvider shopToken={shopToken} webVitals={false}>
  <Outlet />
</MeridianProvider>
```

Without the provider, `captureWebVitals()` does the same job. Call it once in the browser, as early as you can, and keep the function it returns to stop.

## If your app reads Web Vitals too

App Bridge keeps a single `shopify.webVitals.onReport` callback: a second call replaces the first. The SDK shares it with your app. A callback you register in an effect, or anywhere after `MeridianProvider` first renders, keeps receiving every report beside Meridian, and your `onReport(null)` clears only yours. A callback registered before that, at module level, is replaced: move it into an effect.

## Sample applications

In [demo mode](https://help.the-meridian.ai/demo-mode.md), the sample applications carry 60 days of Web Vitals samples written on the day demo mode was turned on. Nothing refreshes them, so after about four weeks the card says **No page views yet**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.