App users and app developers can publish custom customer events from online store theme liquid files, [theme app extensions](/docs/apps/online-store/theme-app-extensions) and [checkout extensions](/docs/api/checkout-ui-extensions/latest/extension-points-overview). When custom customer events are published they can be accessed by all custom pixels and app pixels.
The `analytics.publish` method is available in different contexts for publishing custom events. The `analytics.publish` method takes an `event_name` and some `event_data` as parameters. The object passed into the `event_data` field is shared with subscribers to the event using the `customData` field. If you haven't set up a way for users to define custom transformation of payloads, then your app pixels might not be able to parse these custom fields. Custom pixels, though, can be changed by the users to translate custom fields to a service’s required format.
/**
* In the online store you can access the `analytics.publish` method on the Shopify object.
* Inside theme app extensions or within the `<script>` tag of theme.liquid files, you can
* insert the following code to publish your custom pixels.
*/
/**
* event_name
* type: string
* description: The name of a single event or a group of events.
*/
const event_name = 'my_custom_event';
/**
* event_data
* type: Object
* description: An object that contains metadata about the event.
*/
const event_data = {sample_event_data: 1};
/**
* @param: event_name
* @param: event_data
*
*/
Shopify.analytics.publish(event_name, event_data);
// In checkout, you can publish custom events from your checkout extensions.
/**
* event_name
* type: string
* description: The name of a single event or a group of events.
*/
const event_name = 'my_custom_event';
/**
* event_data
* type: Object
* description: An object that contains metadata about the event.
*/
const event_data = {sample_event_data: 1};
/**
* @param: event_name
* @param: event_data
*/
analytics.publish('event_name', event_data);
You can subscribe to custom events like you would standard events. Anything published to the custom event is passed to the `customData` field.
// Subscribe from web pixel app extension
import {register} from '@shopify/web-pixels-extension';
register(({analytics}) => {
analytics.subscribe('my_custom_event', (event) => {
/*
event = {
id: "123",
clientId: "2cabc5d8-e728-4359-9173-4b31265cbac0",
name: "my_custom_event",
timestamp: "2011-10-05T14:48:00.000Z",
context: { ... },
customData: {
foo: { bar: '123' },
abc: { def: 'geh' }
}
}
*/
});
});
// Publish from Checkout Extension
analytics.publish('my_custom_event', {
foo: {
bar: '123',
},
abc: {
def: 'geh',
},
});
The 'analytics.visitor' method helps merchants to identify visitors to their store. The method is primarily intended for use cases involving visitor-provided information to aid Shopify, and app features that use the data to enhance the customer experience. For example, if a visitor submits their email address to receive a 30% off coupon, then the email can be relayed to a Partner app using Server Pixels to power loyalty features. The storefront experience can be personalized based on existing information that the merchant already has about the customer. It's important to ensure that, when utilizing this API, all necessary notices and consent in the visitor's region are provided.
/**
* In the online store, you can access the `analytics.visitor` method on the Shopify object.
* Inside theme app extensions or within the `<script>` tag of liquid files, you can
* insert the following code to publish your custom pixels.
*/
/**
* @param {Object} visitorInfo - The parameters for the visitor information.
* @param {string} [visitorInfo.phone] - The phone number.
* @param {string} [visitorInfo.email] - The email address.
* @param {Object} [options] - Additional settings and context for calls to visitor.
* @param {string} [options.appId] - The App Id of the calling app.
* @returns {boolean} - Returns `true` if the visitor method was successful, and returns `false` if the payload was rejected. This method will raise an error if there is an issue with the payload.
*/
// Usage:
Shopify.analytics.visitor(
{
email: 'someEmail@example.com',
phone: '+1 555 555 5555',
},
{
appId: '1234',
},
);
// In checkout, you can emit visitor information from your checkout extensions using the analytics API within the StandardAPI.
/**
* @param {Object} visitorInfo - The parameters for the visitor information.
* @param {string} [visitorInfo.phone] - The phone number.
* @param {string} [visitorInfo.email] - The email address.
* @returns {Promise<VisitorResult>} - Returns a VisitorResult object. See https://shopify.dev/docs/api/checkout-ui-extensions/unstable/apis/standardapi#properties-propertydetail-analytics
*/
// Usage:
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));
}
});