Forward Shopify events to Croct

This integration forwards Shopify’s customer events to your application through a custom pixel. Once set up, it tracks every checkout your visitors start and every order they place, and lets you track your own events in response to any Shopify event, all attributed to the same user and session as their browsing on your storefront.

It works with both Liquid themes (the Online Store) and Hydrogen headless storefronts.

Why a pixel?

Shopify’s checkout runs no scripts from your storefront, so the Croct SDK cannot see what happens there. Pixels are how Shopify shares customer events with third parties, on the storefront and checkout alike, and this integration builds on them.

How it works

The integration has two parts that work together:

• A plugin on your storefront that runs with the Croct SDK and shares the visitor’s application, client ID, user token, and tab with the pixel. Shopify runs pixels in an isolated sandbox, so the plugin stores this information in a first-party cookie the pixel can read.
• A custom pixel in your Shopify admin that reads the information shared by the plugin and tracks events on the visitor’s behalf.

Because the pixel tracks events for the visitor the plugin identified, the events land on the same user profile and session as the rest of the visitor’s journey, including their sign-in status.

Automatic events

The pixel automatically maps the following Shopify standard events to our e-commerce events:

Both events carry the cart or order details, including the items, totals, discounts, and shipping costs.

Prerequisites

Before you start, make sure you have:

• A Croct account with a workspace and application set up.
• The Croct SDK installed on your storefront, either the JavaScript SDK on your Liquid theme or the Hydrogen SDK on your Hydrogen storefront.
• Access to the Settings section of your Shopify admin.

Set up the integration

Setting up the integration takes two steps: adding the plugin to your storefront, and creating the custom pixel in your Shopify admin.

Add the plugin to your storefront

The plugin loads alongside the Croct SDK. Follow the instructions for your storefront.

Liquid themes

1. In your Shopify admin, go to Online Store > Themes.

2. Next to your current theme, click ⋯ > Edit code.

3. In the file list, open layout/theme.liquid.

4. Paste the following code right before the closing </head> tag:

   Plugin script

   <script src="https://cdn.croct.io/plug-integration/shopify-pixel.js" defer></script>

5. Click Save.

Hydrogen storefronts

The Hydrogen SDK includes the plugin, so you only need to enable it.

1. Enable the plugin in your environment variables:

   .env

   PUBLIC_CROCT_SHOPIFY_PIXEL=true

2. Deploy your storefront.

The SDK loads the plugin and sets the cookie on the domain your storefront and checkout have in common, based on the PUBLIC_CHECKOUT_DOMAIN environment variable that Hydrogen projects use to configure the checkout domain, such as checkout.example.com. If your project does not define it, or to use another domain, set the PUBLIC_CROCT_SHOPIFY_PIXEL_COOKIE_DOMAIN environment variable.

Create the custom pixel

The pixel is the same for Liquid and Hydrogen storefronts.

1. In your Shopify admin, go to Settings > Customer events.

2. Click Add custom pixel, name it Croct, and click Add pixel.

3. Under Customer privacy, choose when the pixel runs:

   • To run it only for visitors who allow analytics, set Permission to Required and select Analytics.
   • To run it for all visitors, set Permission to Not required.

   Check which option applies to your store under the privacy laws of the regions you sell to.

4. Replace the code in the editor with the following:

   Custom pixel

   import('https://cdn.croct.io/plug-integration/shopify-pixel-tracker.js')    .then(({croctPixel}) => croctPixel()({analytics, browser, init}));

5. Click Save, then Connect.

Once connected, the pixel shows the Connected status on the Customer events page and starts tracking events right away. The pixel takes the application ID from the plugin, so there is nothing else to configure.

Verify the integration

Once the plugin and the pixel are live, place a test order to confirm the events are tracked.

1. Browse your store

   Open your storefront, add a product to the cart, and proceed to checkout.

2. Place a test order

   Complete the checkout using a test payment, such as the Bogus Gateway or your payment provider’s test mode.

3. Check the events

   Open the user profiles page in the admin app, open your profile, and look for the Checkout started and Order placed events in the Timeline tab.

Customize the pixel

Once the integration is running, you can extend the pixel to track your own events or adjust its behavior.

Track custom events

The pixel lets you track your own events in response to any Shopify event, standard or custom, such as recording a goal when a visitor adds a product to the cart.

To do so, use the track function the pixel returns. It accepts the same events and payloads as the track method of the SDK, plus the Shopify event as an optional third argument, so the event is recorded with the page and time it occurred:

import('https://cdn.croct.io/plug-integration/shopify-pixel-tracker.js')    .then(({croctPixel}) => {        const croct = croctPixel()({analytics, browser, init});
        analytics.subscribe('product_added_to_cart', event => {            croct.track('goalCompleted', {goalId: 'add-to-cart'}, event);        });    });

Options

You can customize the pixel by passing the following options to croctPixel:

autoTracking(optional)

object

The events to track automatically, all enabled by default.

checkoutStarted(optional)

boolean

Whether to track the checkoutStarted event. Defaults to true.

orderPlaced(optional)

boolean

Whether to track the orderPlaced event. Defaults to true.

logger(optional)

object

A custom logger to handle log messages, with debug, info, warn, and error functions.

By default, warnings and errors are logged to the console, and everything else is suppressed.