---
title: App Events API
description: >-
  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.
api_version: v2.0
source_url:
  html: >-
    https://shopify.dev/docs/api/app-home/latest/apis/device-and-platform-integration/app-events-api
  md: >-
    https://shopify.dev/docs/api/app-home/latest/apis/device-and-platform-integration/app-events-api.md
api_name: app-home
---

# App Events API

**Info:**

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](https://shopify.dev/docs/apps/build/dev-dashboard/monitoring-and-logs) logs.

### Methods

The `appEvents` 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](https://shopify.dev/docs/api/app-home) can send an event with `shopify.appEvents.emit()`. 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](https://shopify.dev/docs/apps/build/dev-dashboard/monitoring-and-logs) logs, together with the events that your app sends with the [App Events API](https://shopify.dev/docs/api/app-events/latest/creating-events). Events from App Bridge aren't processed for billing. To report usage for [Shopify App Pricing](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing), send a billing event from your app's backend.

`shopify.appEvents` is always defined. Where the Shopify admin doesn't offer App Events, `emit` resolves `{success: false, error: 'Emit is unavailable.'}`.

* **emit**

  **(eventHandle: string, attributes?: Record\<string, AppEventAttributeValue>) => Promise\<AppEventEmitResult>**

  **required**

  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 `await` it before a save, a navigation, or another step the app user waits for.

  `eventHandle` is the name of the event. Use a descriptive name, such as `report_exported` or `campaign_published`. To send a standard event for [Shopify Analytics](https://shopify.dev/docs/apps/build/app-events/analytics), use the full standard registry handle that you declared, including the `shopify.` prefix. The name has a maximum of 128 characters and can contain only alphanumeric ASCII characters, underscores, periods, hyphens, and forward slashes.

  `attributes` is 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, and `error` describes why.

  For example, `error` describes the failure in these cases:

  * If the `eventHandle` or `attributes` don't meet the restrictions, then `error` describes each violation.
  * If the app exceeded the rate limit, then `error` is `Exceeded emission rate limit.`
  * If the app runs where the Shopify admin doesn't offer App Events, such as Shopify Point of Sale (POS), then `error` is `Emit 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, and `emit()` 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 `timestamp` or `idempotency_key`, so each call to `emit()` creates a separate event. Call `emit()` 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 `eventHandle` or `attributes` don't meet the restrictions above.
  * The `eventHandle` starts with `shopify.` but isn't in the [standard event registry](https://shopify.dev/docs/apps/build/app-events/analytics/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.

```ts
string | number | boolean
```

### AppEventEmitResult

The result of an \`emit\` call. A failed call has a message for the developer.

```ts
{success: true} | {success: false; error: string}
```

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

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

  ```js
  const result = await shopify.appEvents.emit("report_exported", {
    format: "csv",
  });

  if (!result.success) {
    // For example, "Exceeded emission rate limit."
    console.warn(result.error);
  }
  ```

***
