Choose a version:

Analytics API

The Analytics API lets you publish custom events and visitor information to web pixels configured on the store. Use this API to track customer behavior in your extension and send conversion data to third-party analytics services.

Anchor to Use casesUse cases

Track extension interactions: Publish custom events when customers interact with your extension, such as viewing a product recommendation or clicking a promotion banner.
Measure conversions: Send conversion events from customer account pages to analytics platforms for attribution and reporting.
Identify returning visitors: Submit visitor contact information so downstream analytics tools can associate sessions with known customers.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides the analytics interface for customer account extensions. Access the following properties on shopify to publish custom events and send visitor data to web pixels.

Anchor to analytics analytics required: Tracks custom events and sends visitor information to web pixels. Use publish() to emit events and visitor() to submit visitor data.

Note
Requires connecting a third-party domain to Shopify for your customer account pages.
Note: Requires <a href="https://help.shopify.com/en/manual/domains/add-a-domain/connecting-domains/connect-domain-customer-account">connecting a third-party domain</a> to Shopify for your customer account pages.

Analytics

Tracks custom events and sends visitor information to [web pixels](/docs/apps/build/marketing-analytics/pixels). Use the Analytics API to emit analytics events from your extension, such as tracking product views, button clicks, or conversion funnels.

publish
Emit an analytics event to web pixels. The event name and data are forwarded to all registered pixels on the page.
```
(name: string, data: Record<string, unknown>) => Promise<boolean>
```
visitor
Submits visitor contact information (email or phone) to the shop backend. This data is sent to Shopify and is not propagated to web pixels on the page.
```
(data: { email?: string; phone?: string; }) => Promise<VisitorResult>
```

VisitorResult

The result returned by `Analytics.visitor()`. Check the `type` property to determine whether the submission succeeded or failed.

VisitorSuccess | VisitorError

VisitorSuccess

Returned when visitor information was validated and submitted successfully.

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

VisitorError

Returned when visitor information is invalid and wasn't submitted. Contains a `message` with details about what went wrong.

message
A message that explains the error. This message is useful for debugging. It's not localized, and therefore shouldn't be presented directly to the buyer.
```
string
```
type
Indicates that the visitor information is invalid and wasn't submitted. Examples are using the wrong data type or missing a required property.
```
'error'
```

Examples

jsx

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

import {render} from 'preact';

import {useEffect} from 'preact/hooks';

export default async () => {

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

};

function Extension() {

useEffect(() => {

shopify.analytics

.publish(

'customer-account-extension-loaded',

{

extensionName: 'My Extension',

},

)

.then((result) => {

if (result) {

console.log(

'successfully published event, web pixels can now receive this event',

);

} else {

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

}

})

.catch((error) => {

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

console.log('error', error);

});

}, []);

return (

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

);

}

Examples

Publish a custom analytics event

Description

Publish a custom event to all web pixels configured on the store. This example fires a `customer-account-extension-loaded` event when the extension mounts and logs whether the publish succeeded.

jsx

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

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

function Extension() {
  useEffect(() => {
    shopify.analytics
      .publish(
        'customer-account-extension-loaded',
        {
          extensionName: 'My Extension',
        },
      )
      .then((result) => {
        if (result) {
          console.log(
            'successfully published event, web pixels can now receive this event',
          );
        } else {
          console.log('failed to publish event');
        }
      })
      .catch((error) => {
        console.log('failed to publish event');
        console.log('error', error);
      });
  }, []);

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

Submit visitor information

Description

Send visitor contact details to the store backend for identity resolution. This example submits an email and phone number using `shopify.analytics.visitor()` and handles the success or error response.

jsx

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

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

function Extension() {
  useEffect(() => {
    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

Publish events inside useEffect: Trigger analytics calls after the component mounts so you don't block the initial render.
Handle publish failures gracefully: Always attach a .catch() handler to shopify.analytics.publish() so undelivered events don't cause uncaught promise rejections.
Use descriptive event names: Choose event names that clearly identify the interaction, such as loyalty-points-redeemed or subscription-upgraded, so pixel consumers can filter and act on them.
Avoid sending sensitive data in event payloads: Don't include passwords, full payment details, or other personally identifiable information beyond what's needed for analytics.

Anchor to LimitationsLimitations

Custom events published through this API are only delivered to web pixels that are configured on the store. If no pixels are active, the publish call resolves but has no downstream effect.
The shopify.analytics.visitor() method sends data to the store backend only. Visitor information isn't propagated to web pixels on the page.
Event payloads must be JSON-serializable. Functions, DOM nodes, and circular references can't be included.

Was this page helpful?