Configure Analytics App Events
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.
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.
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 is the source for queryable fields and metrics.
Anchor to Example configurationExample configuration
Add the extension and event declaration to shopify.extension.toml:
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.
Anchor to Extension fieldsExtension 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. |
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.
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.
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.
Anchor to Event fieldsEvent fields
| Field | Required | Description |
|---|---|---|
name | Yes | A handle from the 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.
Anchor to Declare multiple eventsDeclare multiple events
Add an [[extensions.events]] block for each standard event that your app sends:
Only declare events that accurately describe activity that's reported by your app.
Anchor to Registry and API handlesRegistry 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 |
Anchor to Deploy the configurationDeploy the configuration
Deploy your app configuration with Shopify CLI:
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.
Anchor to Update the configurationUpdate 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.
Anchor to LimitsLimits
| 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 requirements.
Anchor to Next stepsNext steps
- Learn how to use App Events in Analytics.
- Review the standard event registry.
- Review the App Events API reference.