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

# 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"
name = "App Events"


namespace = "example-app"


[[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`. |
| `name` | Yes | The extension name that's shown in app configuration tooling. |
| `namespace` | Yes | A stable identifier for your app's analytics schema. |
| `events` | Yes | One or more standard event declarations. |

### `namespace`

The namespace must:

* Begin with a lowercase letter.
* Contain only lowercase letters, numbers, and hyphens.
* Contain no underscores, dots, spaces, or uppercase letters.
* Contain no more than 64 characters.

Choose a namespace that identifies your app, and don't change it after release. Changing the namespace is a breaking configuration change.

***

## 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"
name = "App Events"


namespace = "example-app"


[[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` 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 namespace that doesn't start with a lowercase letter, contains characters other than lowercase letters, numbers, and hyphens (such as uppercase letters, underscores, dots, or spaces), or exceeds 64 characters.
* A change to the namespace of a released Analytics App Events configuration.
* 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:

* Change the namespace.
* 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 |
| - | - |
| Namespace length | 64 characters |
| 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).

***