Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Analytics API

The API for interacting with web pixels.

Anchor to StandardApiStandardApi

The base API object provided to purchase extension targets.

Anchor to analytics analytics required: The methods for interacting with Web Pixels, such as emitting an event.

Analytics

publish
Publish method to emit analytics events to [Web Pixels](/docs/apps/marketing).
```
(name: string, data: Record<string, unknown>) => Promise<boolean>
```
visitor
A method for capturing details about a visitor on the online store.
```
(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's **not** localized, and therefore should not 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

import {useState, useEffect} from 'react';

import {

Banner,

reactExtension,

useApi,

} from '@shopify/ui-extensions-react/checkout';

export const purchaseCheckoutBlockRender =

reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

const {analytics} = useApi();

analytics

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

extensionName: 'My Extension',

})

.then((result) => {

if (result) {

console.log(

'succesfully published event, web pixels can now recieve this event',

);

} else {

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

}

})

.catch((error) => {

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

console.log('error', error);

});

return <Banner>See console for result</Banner>;

}

Examples

Publish

Description

You can publish analytics events to the Shopify analytics frameworks and they will be propagated to all web pixels on the page.

React

import {useState, useEffect} from 'react';
import {
  Banner,
  reactExtension,
  useApi,
} from '@shopify/ui-extensions-react/checkout';

export const purchaseCheckoutBlockRender =
  reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

function Extension() {
  const {analytics} = useApi();

  analytics
    .publish('checkout-extension-loaded', {
      extensionName: 'My Extension',
    })
    .then((result) => {
      if (result) {
        console.log(
          'succesfully published event, web pixels can now recieve this event',
        );
      } else {
        console.log('failed to publish event');
      }
    })
    .catch((error) => {
      console.log('failed to publish event');
      console.log('error', error);
    });

  return <Banner>See console for result</Banner>;
}

JavaScript

import {extension} from '@shopify/ui-extensions-react/checkout';
import {useEffect} from 'react';

export default extension(
  'purchase.checkout.block.render',
  (root, {analytics}) => {
    useEffect(() => {
      analytics
        .publish('checkout-extension-loaded', {
          extensionName: 'My Extension',
        })
        .then((result) => {
          if (result) {
            console.log(
              'succesfully published event, web pixels can now recieve this event',
            );
          } else {
            console.log(
              'failed to publish event',
            );
          }
        })
        .catch((error) => {
          console.error(
            'failed to publish event',
          );
          console.error('error', error);
        });
    });
  },
);

Visitor

Description

You can submit visitor information to Shopify, these will be sent to the shop backend and not be propagated to web pixels on the page.

React

import {useState, useEffect} from 'react';
import {
  Banner,
  reactExtension,
  useApi,
} from '@shopify/ui-extensions-react/checkout';

export const purchaseCheckoutBlockRender =
  reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

function Extension() {
  const {analytics} = useApi();

  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 <Banner>See console for result</Banner>;
}

JavaScript

import {extension} from '@shopify/ui-extensions-react/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, {analytics}) => {
    analytics
      .visitor({
        email: 'someEmail@example.com',
        phone: '+1 555 555 5555',
      })
      .then((result) => {
        if (result.type === 'success') {
          console.log(
            `Success`,
            JSON.stringify(result),
          );
        } else {
          console.log(
            `Error`,
            JSON.stringify(result),
          );
        }
      });
  },
);

Anchor to RelatedRelated

ReferenceTargets

ReferenceComponents

ReferenceConfiguration

LearnTutorials

Was this page helpful?