# Forward Shopify events to Croct

Track checkouts, orders, and any Shopify event with a custom pixel.

This integration forwards Shopify's [customer events](https://help.shopify.com/manual/promoting-marketing/pixels/overview) 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](https://shopify.dev/docs/storefronts/themes/liquid) themes (the Online Store) and [Hydrogen](https://hydrogen.shopify.dev) 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.

> **Visitors must come through your storefront**
>
> The pixel only tracks events for visitors the plugin has seen on your storefront. If a visitor opens the checkout directly, such as from an abandoned cart email, there is no visitor to attribute the events to, and the pixel skips them.

### Automatic events

The pixel automatically maps the following Shopify [standard events](https://shopify.dev/docs/api/web-pixels-api/standard-events) to our [e-commerce events](/reference/event/overview):

| Shopify event        | Croct event                                                            |
| -------------------- | ---------------------------------------------------------------------- |
| `checkout_started`   | [`checkoutStarted`](/reference/event/types/ecommerce/checkout-started) |
| `checkout_completed` | [`orderPlaced`](/reference/event/types/ecommerce/order-placed)         |

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](/reference/sdk/javascript/integration) on your Liquid theme or the [Hydrogen SDK](/reference/sdk/hydrogen/integration) 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**

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

5. Click **Save**.

> **Load order does not matter**
>
> The plugin registers itself with the SDK whenever it loads, so it can load after the SDK without delaying your page, as Shopify recommends for theme scripts.

#### Hydrogen storefronts

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

> **Checkout on a subdomain**
>
> Your checkout must be on a subdomain of your storefront's domain, such as `checkout.example.com` for a storefront on `example.com`, as [recommended by Shopify](https://shopify.dev/docs/storefronts/headless/hydrogen/analytics/validation). Browsers do not share cookies between unrelated domains, so the integration does not work on local development or Oxygen preview environments.

1. Enable the plugin in your environment variables:

   **.env**

   ```bash
   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`](/reference/sdk/hydrogen/api/environment-variables) 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**

   ```js
   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.

> **Consent-aware**
>
> When the pixel requires permission, Shopify only runs it for visitors who grant the permissions you selected, so events are only tracked with their consent.

## 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](https://help.shopify.com/manual/checkout-settings/test-orders), such as the Bogus Gateway or your payment provider's test mode.

3. **Check the events**

   Open the [user profiles page](https://app.croct.com/redirect/organizations/-organization-/workspaces/-workspace-/profiles) 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](https://shopify.dev/docs/api/web-pixels-api/emitting-data), such as recording a [goal](/reference/event/types/engagement/goal-completed) 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`](/reference/sdk/javascript/api/plug/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:

**Custom pixel**

```js
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`: `object` (optional)

  The events to track automatically, all enabled by default.

  - `checkoutStarted`: `boolean` (optional)

    Whether to track the [`checkoutStarted`](/reference/event/types/ecommerce/checkout-started) event. Defaults to `true`.

  - `orderPlaced`: `boolean` (optional)

    Whether to track the [`orderPlaced`](/reference/event/types/ecommerce/order-placed) event. Defaults to `true`.

- `logger`: `object` (optional)

  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.

## Explore

- [Events](/reference/event/overview#event-types): Learn how to track user events for analytics and personalization.
- [Experiences](/explanation/experience/introduction): Discover what an experience is and how it works.