App Events API
App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version.
App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version.
Use the App Events API to send events to Shopify about how app users interact with your embedded app, without a request to your app's backend. Events that Shopify accepts are visible in the Dev Dashboard logs.
Anchor to MethodsMethods
The object sends events to Shopify about how app users interact with your app, without a request to your app's backend. Embedded apps that load App Bridge can send an event with . Shopify adds your app and the shop to each event, so you don't need an access token or a shop ID.
Events that Shopify accepts are visible in the Dev Dashboard logs, together with the events that your app sends with the App Events API. Events from App Bridge aren't processed for billing. To report usage for Shopify App Pricing, send a billing event from your app's backend.
is always defined. Where the Shopify admin doesn't offer App Events, emit resolves {success: false, error: 'Emit is unavailable.'}.
- Anchor to emitemitemit(eventHandle: string, attributes?: Record<string, AppEventAttributeValue>) => Promise<AppEventEmitResult>(eventHandle: string, attributes?: Record<string, AppEventAttributeValue>) => Promise<AppEventEmitResult>requiredrequired
Sends an event to Shopify. The Promise never rejects. It resolves after App Bridge connects to the Shopify admin, and stays pending while the Shopify admin hasn't answered App Bridge's handshake. Don't
awaitit before a save, a navigation, or another step the app user waits for.is the name of the event. Use a descriptive name, such asor. To send a standard event for Shopify Analytics, use the full standard registry handle that you declared, including theshopify.prefix. The name has a maximum of 128 characters and can contain only alphanumeric ASCII characters, underscores, periods, hyphens, and forward slashes.attributesis an optional object of key/value pairs that contains the event data. Don't include any data that, alone or in combination with other data, could identify an individual, such as names, email addresses, phone numbers, staff member IDs, and customer IDs. The object has the following restrictions:- Maximum 15 keys.
- Keys are limited to 64 characters and can contain only alphanumeric ASCII characters, underscores, periods, and hyphens.
- String values are limited to 128 characters (UTF-8).
- Only scalar values are allowed: strings, finite numbers, and Boolean values. Arrays and nested objects aren't supported.
The Promise resolves with an object:
{success: true}: The Shopify admin accepted the event. An accepted event can still go unsent.{success: true}doesn't confirm that Shopify received it.{success: false, error}: The Shopify admin didn't send the event, anderrordescribes why.
For example,
errordescribes the failure in these cases:- If the
orattributesdon't meet the restrictions, thenerrordescribes each violation. - If the app exceeded the rate limit, then
errorisExceeded emission rate limit. - If the app runs where the Shopify admin doesn't offer App Events, such as Shopify Point of Sale (POS), then
errorisEmit is unavailable.
The Shopify admin sends the event as soon as your app calls
emit(), without asking the app user for consent. It doesn't send the event in these cases, andemit()resolves{success: false}:- If a Shopify employee is logged in to the store's Shopify admin, then the Shopify admin doesn't send the event.
- If the logged-in staff member doesn't have access to your app, then the Shopify admin doesn't send the event, and it doesn't ask them to request access.
Each app can send a burst of up to 20 events from one Shopify admin tab, then 2 events per second. Your app's pages, modals, and app intents in that tab share this limit. After the limit is exceeded,
emit()resolves{success: false}and doesn't send the event, until the rate falls below the limit.Shopify records the time that it receives each event. Events from App Bridge have no
timestampor, so each call toemit()creates a separate event. Callemit()once for each occurrence.Shopify validates each event again after the Shopify admin sends it. Shopify drops an event that fails this validation. Dropped events don't appear in the Dev Dashboard, and your app isn't notified. Shopify drops an event in these cases:
- The
orattributesdon't meet the restrictions above. - The
starts withshopify.but isn't in the standard event registry. - Your app isn't installed on the shop.
- Shopify can't verify the app's session token.
To check that your events arrive, go to the Dev Dashboard and open Logs.
AppEventAttributeValue
A value of an app event attribute.
string | number | booleanAppEventEmitResult
The result of an `emit` call. A failed call has a message for the developer.
{success: true} | {success: false; error: string}js
Examples
Track an export
Description
Send an event when the app user exports a report. Shopify adds the app and the shop to the event, so the event needs only a handle and attributes.
js
// Send an event when the app user exports a report. // Shopify adds the app and the shop, // so the event needs only a handle and attributes. shopify.appEvents.emit("report_exported", { format: "csv", row_count: 120, });Check the result
Description
Check the result of an event. If `success` is `false`, `error` describes why the Shopify admin didn't send the event.
js
const result = await shopify.appEvents.emit("report_exported", { format: "csv", }); if (!result.success) { // For example, "Exceeded emission rate limit." console.warn(result.error); }