Migrating pixels

If you've previously added a pixel manually to your store in a location such as the theme.liquid, checkout.liquid (for Plus merchants only), or Additional scripts in your checkout settings, then you can migrate your pixels to be compatible with a Shopify app pixel, or a custom pixel. Some benefits of migrating your old pixels include:

• Easier access to tracking customer events, including checkout events
• Built in tools for privacy compliance

Learn more about Shopify's pixel manager, and the full benefits of migrating to Shopify app pixels or custom pixels.

Note

This page is a general guideline for migrating your manually added pixels. Steps for different pixels vary, and are unsupported by Shopify. You should consult each third-party pixel documentation for more detailed instructions.

Preparing to migrate a pixel

To avoid duplicating or missing customer events, you can consider migrating your pixels during a less busy period for your store.

You can connect your new custom pixel before or after removing your old pixel code. Consider the following when deciding on your migration workflow:

• If you want to minimize missing any customer events, then connect your new custom pixel before you remove your old pixel.
• If you want to avoid duplicating customer event tracking, then connect your new custom pixel after removing your old pixel.

Migrate an old pixel to be compatible with an app pixel

Note

If you’ve installed an app pixel, and you haven’t added any additional code, then you don’t need to migrate or make any changes. The app developer will make improvements to your pixel integration for you automatically.

You might want to migrate an old pixel to be compatible with an app pixel if both of the following conditions apply:

• You've installed a Shopify app pixel that collects customer events automatically.
• You've also added some additional code for custom events that are't tracked by the app pixel.

In this case, you should follow the app developer's instructions to migrate the old pixel.

Migrate an old pixel to a custom pixel

You might want to migrate an old pixel to a custom pixel if both of the following conditions apply:

• You have a previously installed pixel that you manually wrote code for, without any Shopify app installed.
• There is no Shopify app pixel that meets your requirements.

Steps

1. Create a custom pixel that subscribes to your required standard and custom customer events.
2. Remove, or replace any previously added pixel code from your liquid files or Additional scripts in your checkout settings. This might include the following:
   • Find and remove old pixel code that includes the Javascript SDK.
   • Find and remove old pixel code that collects standard events.
   • Find and remove old pixel code that collects non-standard events.
3. Add your custom pixel to your store.
4. Connect your custom pixel.

Finding old pixel code

In order to migrate an old pixel, you need to find your old pixel code so that you can remove or modify it. Most pixels have two components that you'll need to find:

• A base Javascript SDK
• At least one function for tracking customer events

Find old instances of the pixel Javascript SDK

The Javascript SDK is a base set of code provided by every pixel that loads the pixel's library of functions. It's normally the first snippet of code that you need to place on your online store when you add a pixel.

The Javascript SDK is often placed in your header, and can be found in the theme.liquid and Additional scripts in your checkout settings.

Shopify Plus

If you're a Shopify Plus merchant, then you should also check your checkout.liquid for old Javascript SDK.

Find old pixel code for collecting customer events

To find old pixel for tracking customer events, you should check your third-party pixel's documentation for how customer events are located so that you know what to search for. For example, Meta's pixel has a method called fbq(), and Google pixels often use gtag() or dataLayer.push().

You can usually find this code in your theme's liquid files, and Additional scripts in your checkout settings.

Removing or replacing old pixel code

As you find your old pixel code, you need to either remove it, or replace it with Shopify's Shopify.analytics.publish() method, depending on what kind of event the pixel is tracking:

• You can remove all instances of the Javascript SDKs that you find.
• If the old pixel is tracking a standard customer event, and the custom pixel or app pixel that you want to add supports collecting the standard customer event, then you should remove its code.
• If the old pixel is tracking a custom customer event, and the custom pixel or app that you want to add supports collecting custom customer events, then you should replace its code.

This is an example of an old pixel code that tracks a non-standard customer event:

<script>fbq("trackCustom", "my_custom_event");</script>

This is an example of the equivalent code to replace it with:

<script>Shopify.analytics.publish("my_custom_event");</script>

If you're creating a custom pixel, then you should include code subscrbing to the custom event, such as this example:

analytics.subscribe("my_custom_event", event => { fbq("trackCustom", "my_custom_event"); });