Migrating pixels
If you've previously added a pixel manually to your store in a location such as the theme.liquid, checkout.liquid (for stores on the Shopify Plus plan 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.
On this page
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
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
- Create a custom pixel that subscribes to your required standard and custom customer events.
-
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.
- Add your custom pixel to your store.
- 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.
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");
});