Choose a version:

Analytics
API

The API for interacting with web pixels.

Anchor to standardapiStandardApi

The base API object provided to purchase, and customer-account.order-status extension targets.

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

Docs_Standard_AnalyticsApi

analytics
Methods for interacting with [Web Pixels](/docs/apps/marketing), such as emitting an event.
```
Analytics
```

export interface Docs_Standard_AnalyticsApi
  extends Pick<StandardApi, 'analytics'> {}

Analytics

publish
Publish method to emit analytics events to [Web Pixels](/docs/apps/marketing).
```
(name: string, data: { [key: string]: unknown; }) => Promise<boolean>
```
visitor
A method for capturing details about a visitor on the online store.
```
(data: { email?: string; phone?: string; }) => Promise<VisitorResult>
```

export interface Analytics {
  /**
   * Publish method to emit analytics events to [Web Pixels](/docs/apps/marketing).
   */
  publish(name: string, data: {[key: string]: unknown}): Promise<boolean>;

  /**
   * A method for capturing details about a visitor on the online store.
   */
  visitor(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"
```

export interface VisitorSuccess {
  /**
   * Indicates that the visitor information was validated and submitted.
   */
  type: 'success';
}

VisitorError

Represents an unsuccessful visitor result.

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

export interface VisitorError {
  /**
   * Indicates that the visitor information is invalid and wasn't submitted.
   * Examples are using the wrong data type or missing a required property.
   */
  type: 'error';

  /**
   * 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.
   */
  message: string;
}

Was this section helpful?

Publish

import React, {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 React, {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);
        });
    });
  },
);

Anchor to examplesExamples

Anchor to example-visitorVisitor

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.