Choose a version:

Analytics API

The Analytics API provides methods to interact with Shopify's analytics framework. Use this API to publish custom events that are forwarded to all registered web pixels, or to submit visitor contact details directly to the shop backend.

Events published with publish() are forwarded only to web pixels. They aren't sent to the shop backend. Visitor data submitted with visitor() goes only to the shop backend. It isn't propagated to web pixels on the page.

Anchor to Use casesUse cases

Publish custom analytics events: Emit events from your extension that web pixels on the page can react to.
Submit visitor information: Send buyer contact details to the shop backend for attribution and analytics purposes.
Track extension-specific interactions: Publish events when buyers interact with your extension's UI to measure engagement.

Support

Targets (33)

Supported targets

Anchor to Properties and methodsProperties and methods

The shopify global object provides analytics capabilities for the current checkout. Access the following properties and methods on shopify to publish custom events and submit visitor data. Available to purchase extension targets.

Anchor to analytics analytics required: Tracks custom events and sends visitor information to Web Pixels. Use publish() to emit events and visitor() to submit buyer contact details.

Analytics

Tracks custom events and sends visitor information to [Web Pixels](/docs/apps/marketing). Use `publish()` to emit events and `visitor()` to submit buyer contact details.

publish
Publishes a custom event to [Web Pixels](/docs/apps/marketing). Returns `true` when the event is successfully dispatched. The Promise resolves to `true` when the event was dispatched. The boolean indicates dispatch confirmation only. It doesn't indicate whether any specific web pixel processed the event.
```
(name: string, data: Record<string, unknown>) => Promise<boolean>
```
visitor
Submits buyer contact details for attribution and analytics purposes.
```
(data: { email?: string; phone?: string; }) => Promise<VisitorResult>
```

VisitorResult

Represents a visitor result.

VisitorSuccess | VisitorError

VisitorSuccess

Represents a successful visitor result.

type
Indicates that the visitor information was validated and submitted.
```
'success'
```

VisitorError

Represents an unsuccessful visitor result.

message
A message that explains the error. This message is useful for debugging. It isn't localized and shouldn't be displayed to the buyer.
```
string
```
type
Indicates that the visitor information is invalid and wasn't submitted. Common causes include using the wrong data type or omitting a required property.
```
'error'
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

shopify.analytics

.publish('checkout-extension-loaded', {

extensionName: 'My Extension',

})

.then((result) => {

if (result) {

console.log(

'Successfully published event',

);

} else {

console.log('Failed to publish event');

}

})

.catch((error) => {

console.error('Publish error', error);

});

return (

<s-banner>See console for result</s-banner>

);

}

Examples

Description

Send custom events to all web pixels registered on the page. This example calls `shopify.analytics.publish()` with an event name and payload that web pixels can react to.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  shopify.analytics
    .publish('checkout-extension-loaded', {
      extensionName: 'My Extension',
    })
    .then((result) => {
      if (result) {
        console.log(
          'Successfully published event',
        );
      } else {
        console.log('Failed to publish event');
      }
    })
    .catch((error) => {
      console.error('Publish error', error);
    });

  return (
    <s-banner>See console for result</s-banner>
  );
}

Description

Submit buyer contact details to the shop backend. This example sends visitor data through `shopify.analytics.visitor()`. Unlike when using `shopify.analytics.publish()`, data isn't forwarded to web pixels on the page.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  shopify.analytics
    .visitor({
      email: 'someEmail@example.com',
      phone: '+1 555 555 5555',
    })
    .then((result) => {
      if (result.type === 'success') {
        console.log('Success', result);
      } else {
        console.error('Error', result);
      }
    });

  return (
    <s-banner>See console for result</s-banner>
  );
}

Anchor to Best practicesBest practices

Respect buyer privacy consent: Before publishing analytics events, check whether analytics processing is allowed using the Customer Privacy API. Read shopify.customerPrivacy.value.allowedProcessing.analytics and only publish events when it's true.
Use descriptive event names: When calling publish(), use specific event names that clearly describe the interaction (for example, "loyalty_points_redeemed" instead of "click"). This makes it easier for web pixel implementations to filter and process events.
Separate analytics from visitor data: Use publish() for events that web pixels should process and visitor() for contact details that should go to the shop backend. Don't use publish() to send visitor contact information.

Was this page helpful?