---
title: Configure Analytics App Events
description: Declare the standard events that your app sends for Shopify Analytics.
source_url:
  html: 'https://shopify.dev/docs/apps/build/app-events/analytics/toml-configuration'
  md: >-
    https://shopify.dev/docs/apps/build/app-events/analytics/toml-configuration.md
api_name: app-events
---

# Configure Analytics App Events

**Developer preview:**

App Events in Analytics is in developer preview. The preview is available to approved apps and supports declared standard events. [Sign up for early access](https://forms.gle/2yLka2Ww3J3cNiGY8).

Use the `analytics_app_events` extension configuration to declare the standard events that your app sends for Shopify Analytics.

Declaring an event doesn't send event data. After Shopify accepts the configuration, your app must send the matching event through the App Events API.

This page covers the app configuration workflow. The standard registry is the source for event declarations, and the versioned [ShopifyQL reference](https://shopify.dev/docs/api/shopifyql/latest) is the source for queryable fields and metrics.

***

## Example configuration

Add the extension and event declaration to `shopify.extension.toml`:

```toml
[[extensions]]
type = "analytics_app_events"
handle = "app-events"


[[extensions.events]]
name = "shopify.marketing.email_sent"
kind = "standard"
```

This configuration declares the standard registry event `shopify.marketing.email_sent`. To send the event, use the same handle, `shopify.marketing.email_sent`, in the App Events API `event_handle` field.

***

## Extension fields

| Field | Required | Description |
| - | - | - |
| `type` | Yes | The extension type. Must be `analytics_app_events`. |
| `handle` | Yes | A unique identifier for the extension within your app. Contains only letters, numbers, and hyphens, doesn't start or end with a hyphen, and is no more than 50 characters. |
| `events` | Yes | One or more standard event declarations. |

### `handle`

Every entry in an `[[extensions]]` array requires a `handle`, and each handle must be unique across your app's extensions. If the `handle` is missing, then Shopify CLI fails to load the app and reports a missing handle error for the extension before it runs `app dev` or `app deploy`.

**Info:**

If your app's currently released Analytics App Events configuration includes `namespace`, then keep the field and its exact value in every future version. Omit `namespace` from new configurations and from existing configurations that don't already include it.

***

## Event fields

| Field | Required | Description |
| - | - | - |
| `name` | Yes | A handle from the [standard event registry](https://shopify.dev/docs/apps/build/app-events/analytics/standard-event-registry), such as `shopify.marketing.email_sent`. |
| `kind` | No | The event kind. Defaults to `standard` when omitted. Only `standard` is supported. |

Shopify defines the labels, attributes, and metrics for a standard event. Don't add `label`, `category`, `dimensions`, or `metrics` to a standard event declaration.

***

## Declare multiple events

Add an `[[extensions.events]]` block for each standard event that your app sends:

```toml
[[extensions]]
type = "analytics_app_events"
handle = "app-events"


[[extensions.events]]
name = "shopify.marketing.email_sent"
kind = "standard"


[[extensions.events]]
name = "shopify.marketing.sms_sent"
kind = "standard"
```

Only declare events that accurately describe activity that's reported by your app.

***

## Registry and API handles

Use the full standard registry handle, including the `shopify.` prefix, in both the `shopify.extension.toml` declaration and the App Events API `event_handle`. The declaration and the API request use the same value.

| `shopify.extension.toml` event declaration (`name`) | App Events API `event_handle` |
| - | - |
| `shopify.marketing.email_sent` | `shopify.marketing.email_sent` |
| `shopify.marketing.sms_sent` | `shopify.marketing.sms_sent` |
| `shopify.loyalty.points_earned` | `shopify.loyalty.points_earned` |

***

## Deploy the configuration

Deploy your app configuration with Shopify CLI:

```terminal
shopify app deploy
```

Shopify validates the Analytics App Events configuration during deployment. If validation fails, then the deployment returns an error. Update the configuration based on the error and deploy it again.

Validation errors can include:

* An unknown or unsupported standard registry handle.
* A field that isn't supported.
* A change that removes or modifies a previously released event declaration.
* A declaration that exceeds a supported limit.

***

## Update the configuration

Analytics App Events configuration supports additive changes. You can add another supported standard event, but don't:

* Remove a released event declaration.
* Rename an event handle.
* Change an event's `kind`.

For an incompatible change in event meaning, declare a different supported event instead.

***

## Limits

| Limit | Value |
| - | - |
| Attributes in each event payload | 15 |

The standard event registry defines the attributes and value types that are supported for each event. Payloads must also meet all [App Events API](https://shopify.dev/docs/api/app-events) requirements.

***

## Next steps

* Learn how to use [App Events in Analytics](https://shopify.dev/docs/apps/build/app-events/analytics).
* Review the [standard event registry](https://shopify.dev/docs/apps/build/app-events/analytics/standard-event-registry).
* Review the [App Events API reference](https://shopify.dev/docs/api/app-events).

***