---
title: Analytics
description: The API for interacting with web pixels.
api_version: 2024-01
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/2024-01/apis/analytics
  md: https://shopify.dev/docs/api/checkout-ui-extensions/2024-01/apis/analytics.md
---

# AnalyticsAPI

The API for interacting with web pixels.

## StandardApi

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

* analytics

  Analytics

  required

  Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.

### Analytics

* publish

  Publish method to emit analytics events to \[Web Pixels]\(/docs/apps/marketing).

  ```ts
  (name: string, data: { [key: string]: unknown; }) => Promise<boolean>
  ```

* visitor

  A method for capturing details about a visitor on the online store.

  ```ts
  (data: { email?: string; phone?: string; }) => Promise<VisitorResult>
  ```

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

```ts
VisitorSuccess | VisitorError
```

### VisitorSuccess

Represents a successful visitor result.

* type

  Indicates that the visitor information was validated and submitted.

  ```ts
  "success"
  ```

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

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

  ```ts
  string
  ```

```ts
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;
}
```

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

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

  ```js
  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);
          });
      });
    },
  );
  ```

## Examples

Visitor

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.

### Examples

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

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

  ```js
  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),
            );
          }
        });
    },
  );
  ```

## Related

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

[ReferenceTargets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

[![](https://shopify.dev/images/icons/32/apps.png)![](https://shopify.dev/images/icons/32/apps-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/components)

[ReferenceComponents](https://shopify.dev/docs/api/checkout-ui-extensions/components)

[![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

[ReferenceConfiguration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

[![](https://shopify.dev/images/icons/32/tutorial.png)![](https://shopify.dev/images/icons/32/tutorial-dark.png)](https://shopify.dev/apps/checkout)

[LearnTutorials](https://shopify.dev/apps/checkout)