Configure Analytics App Events

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

Anchor to [object Object]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.

Anchor to Event fieldsEvent fields

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.

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

Anchor to Update the configurationUpdate 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.

Anchor to LimitsLimits

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.