Choose a version:

Analytics

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

export interface Analytics {
  /**
   * Publish method to emit analytics events to [Web Pixels](/docs/apps/marketing).
   */
  publish(name: string, data: Record<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.

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

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

Preact

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(

'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 (

<s-banner>See console for result</s-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.

Preact

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(
          '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 (
    <s-banner>See console for result</s-banner>
  );
}

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.

Preact

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 relatedRelated

ReferenceTargets

ReferenceComponents

ReferenceConfiguration

LearnTutorials

Was this page helpful?