Create custom pixel code

This page includes instructions to create custom pixel code for a third-party pixel, so that you can track specific customer events. After you create the code for your custom pixel, you can add the pixel to your Shopify store.

Note

Before you create a custom pixel, you should review available apps for improved stability, security, and performance. However, if there isn't an app that meets your needs, then you can create a custom pixel.

Preparing to create a custom pixel

Before you create a custom pixel, review the following information to make sure that you understand how to configure your pixel:

• risks associated with pixels
• limitations of Shopify's pixels sandbox
• using the Shopify pixels sandbox API
• customer event tracking schema

When you add a custom pixel, you specify the following information:

• the third-party JavaScript pixel
• the behavioral events you want to track

Create the code for a custom pixel

Note

This is an advanced tutorial, and is unsupported by Shopify. If you need help adding a custom pixel, then you can hire a Shopify Partner.

Creating the code for a custom pixel involves the following steps:

1. Prepare the third-party Javascript SDK.
2. Configure your pixel to track customer events.

Preparing the third-party Javascript SDK

The third-party service you're working with provides you with the code that is integrated with the pixel. A pixel usually has two components, a Javascript SDK and the tracking code. Any HTML in the third-party service code needs to be removed, as the Shopify pixel sandbox only supports JavaScript.

Here is an example of a Meta pixel. Pixels will differ slightly from one third-party to another.

​​<!-- Meta Pixel Code -->
​​<script>
!function(f,b,e,v,n,t,s)
{if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};
if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];
s.parentNode.insertBefore(t,s)}(window, document,'script',
'https://connect.facebook.net/en_US/fbevents.js');
fbq('init', YOUR_PIXEL_ID);
fbq('track', 'PageView');
</script>
<noscript><img height="1" width="1" style="display:none"
src="https://www.facebook.com/tr?id=618182112209280&ev=PageView&noscript=1"/></noscript>
<!-- End Meta Pixel Code -->

After removing the HTML from Meta's code, you're left with Meta's pixel SDK and code to initialize it. The PageView event tracking code has also been removed, because it'll be added in the next step.

​​!function(f,b,e,v,n,t,s)
{if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};
if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];
s.parentNode.insertBefore(t,s)}(window, document,'script',
'https://connect.facebook.net/en_US/fbevents.js');
fbq('init', YOUR_PIXEL_ID);

Meta's pixel SDK doesn't automatically transmit data from a Shopify custom pixel. To transmit data, you need to subscribe to events.

You might come across pixels that are loaded using script src=. HTML isn't supported in Shopify's pixels, so you'll need to replace script src= with the JavaScript equivalent.

Here's a sample Google Analytics pixel:

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=YOUR_PIXEL_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', ''YOUR_PIXEL_ID'');
</script>

The script src= portion can be replaced by the JavaScript equivalent. Always ensure your src attribute matches the HTML version:

const script = document.createElement('script');
script.setAttribute('src', 'https://www.googletagmanager.com/gtag/js?id=YOUR_PIXEL_ID');
script.setAttribute('async', '');
document.head.appendChild(script);

window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'YOUR_PIXEL_ID');

Google's pixel SDK doesn't automatically transmit data from a Shopify custom pixel. To transmit data, you need to subscribe to events.

Track customer events

After loading and initializing the pixel's SDK, you need to pass events into it for tracking. This is done by subscribing to events, and then passing the event data into the pixel's SDK to be processed by the third-party service.

Subscribe to standard events

Shopify offers a standard set of events, which makes it easy to ensure your pixel is collecting the data it needs to.

You can subscribe to events using the Shopify Pixels Extension API. You'll need to place the third-party pixel code in with the event you're subscribing to.

This is an example of the PageView event for Meta's pixel. Note that fbq("track") is part of Meta's code, and each company will have their own version that you'll need to reference their documentation for.

analytics.subscribe("page_viewed", async (event) => {
  fbq('track', 'PageView');
});

Some events have metadata that you can pass into your pixel. Here's an example of passing some product details into Meta's ViewContent event:

analytics.subscribe("product_viewed", async (event) => {
  fbq('track', 'ViewContent', {
    content_ids: [event.data?.productVariant?.id],
    content_name: event.data?.productVariant?.title,
    currency: event.data?.productVariant?.price?.currencyCode,
    value: event.data?.productVariant?.price.amount,
  });
});

Subscribe to custom customer events

If you want to track additional customer events, such as when someone clicks a button, then you can add custom customer events. Custom events can be subscribed to the same way as standard events. Declare the name of the event that you want to subscribe to and pass the information on to the third-party service provider’s pixel.

This is an example of how a published custom event might appear in your theme's liquid files:

<script>Shopify.analytics.publish("special_email_signup", { email_campaign_id: 123});</script>

This is an example of how you might configure your pixel to subscribe to that custom event:

analytics.subscribe("special_email_signup", event => {
  window.dataLayer.push({event: emailSignUp, emailCampaignId: event.customData.email_campaign_id});
});

For more information about custom events, refer to Shopify developer documentation.

Configuring consent

Web pixels only run when visitors have provided consent for Marketing and Analytics purposes in markets that you have configured consent to be required. Each pixel might have a different name for each purpose. You should consult the pixel documentation to understand how it maps to Shopify’s definitions.

For example, the following is how the Marketing and Analytics purposes map to Google’s Consent Mode:

gtag('consent', 'update', {
  'ad_storage': 'granted',
  'analytics_storage': 'granted',
  'ad_user_data': 'granted',
  'ad_personalization': 'granted',
});

Custom pixel example

Below is an example of the code for a Meta pixel. Pixel code will vary depending on the third-party service provider, and the events that you want to track. Refer to the customer event reference for a list of available events.

Custom Meta pixel

!function(f,b,e,v,n,t,s)
{if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};
if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];
s.parentNode.insertBefore(t,s)}(window, document,'script',
'https://connect.facebook.net/en_US/fbevents.js');

// replace YOUR_PIXEL_ID with the pixel ID provided by third-party
fbq('init', YOUR_PIXEL_ID);

// integrate third-party pixel tracking
analytics.subscribe("page_viewed", (event) => {
  fbq('track', 'PageView');
});

analytics.subscribe("product_viewed", (event) => {
  fbq('track', 'ViewContent', {
    content_ids:  [event.data?.productVariant?.id],
    content_name: event.data?.productVariant?.title,
    currency: event.data?.productVariant?.price.currencyCode,
    value: event.data?.productVariant?.price.amount,
  });
});

analytics.subscribe("search_submitted", (event) => {
  fbq('track', 'Search', {
    search_string: event.searchResult.query
  });
});

analytics.subscribe("product_added_to_cart", (event) => {
  fbq('track', 'AddToCart', {
    content_ids: [event.data?.cartLine?.merchandise?.productVariant?.id],
    content_name: event.data?.cartLine?.merchandise?.productVariant?.title,
    currency: event.data?.cartLine?.merchandise?.productVariant?.price?.currencyCode,
    value: event.data?.cartLine?.merchandise?.productVariant?.price.amount,
  });
});

analytics.subscribe("payment_info_submitted", (event) => {
  fbq('track', 'AddPaymentInfo');
});

analytics.subscribe("checkout_started", (event) => {
  fbq('track', 'InitiateCheckout');
});

analytics.subscribe("checkout_completed", (event) => {
  fbq('track', 'Purchase', {
    currency: event.data?.checkout?.currencyCode,
    value: event.data?.checkout?.totalPrice?.amount,
  });
});