PartnerConsole Pixel

The PartnerConsole Pixel lets you capture and analyze how merchants use your app. See where they spend their time, find the screens they love and the ones they never discover, and give your support team the context of what a merchant did before they wrote in. Take it a step further and build a funnel from the moments that matter, or send custom events to see exactly how well your new onboarding flow is performing.

Adding the pixel is a simple drop-in JavaScript tag, nothing more is needed, we handle the rest. Every event is automatically attributed to the correct shop in your PartnerConsole account.

Set up your pixel

Open your app in the console, click Settings in the top right, and find the card labeled "PartnerConsole Pixel".
Hit the Enable tracking button.
Copy the <script> tag and put it in your app where it will be loaded on every page:

<script src="https://api.partnerconsole.co/px.js?token=pcpx_..." defer></script>

That's it! Your app will send usage events for each page view and user session start, and the card shows "Receiving data" the moment the first one arrives. Next, let's dig into the data that's being sent and what you can do with it.

The data

The pixel sends events into the same stream as the usage events API, so everything built on usage events (web analytics, funnels, usage metrics, flow triggers, customer activity) works the same whichever way events arrive.

We automatically send page_view and user_session_start events, you do not need to instrument these in any way to start using them. A new session starts after 30 minutes of inactivity.

The properties sent with each event, including custom events, include:

url: the browser URL when the event occurred
path: the full path when the event occurred, such as /orders/8842/edit
route: the normalized path, such as /orders/[id]/edit
session_id: the unique session ID for the user's current session
query: the url parameters, as nested properties (auth parameters are stripped)
referrer: the referring page, when there is one

When you build funnels and page reports, we recommend using a filter on the normalized route property, so every order-edit page counts as one screen no matter which order was open.

We also enrich pixel events server-side from the connection itself: every event gets a country property (resolved locally from the merchant's IP, no third-party service involved), session starts carry the ip, and the customer profile shows where each shop was last seen from. Server-sent events are never enriched this way, since they come from your backend, not the merchant.

Properties are capped at 8KB per event (oversized payloads are replaced with {"truncated": true}), and events are retained for 400 days.

How the shop is detected

Embedded apps always know their shop, and the pixel resolves it automatically. It checks, in order: the customerId you pass to startTracking (see Advanced usage), the App Bridge global, the shop URL parameter, the decoded host parameter, and finally the value cached from a previous page in the same tab. Events queue until a shop is known.

The token in your snippet is publishable: it can only push events, never read anything, and it only accepts real .myshopify.com shops. If it ever leaks somewhere you didn't intend, regenerate it from the console and every deployed tag goes dead instantly.

Content Security Policy

If your app sets a Content-Security-Policy header (embedded apps often do), allow PartnerConsole in two directives:

script-src ... https://partnerconsole.co;
connect-src ... https://partnerconsole.co;

script-src lets the tag load and connect-src lets events send. If you paste the tag and nothing happens, this is almost always why.

Custom events

While we automatically send page_view and user_session_start events, you may have other events that are important to track. Sending custom events is a single line of JavaScript:

pcTrack.track('onboarding_complete');

You can also include custom properties in these events using the properties option:

pcTrack.track('report_exported', {
  properties: {
    rows: 120,
    format: 'csv',
  },
});

You can use these events in the same reports as the automatic events. For example if you want to track conversion of a new onboarding flow, open your funnel report and select your custom onboarding event along with the important events around it (installed and subscribed, for example).

Advanced usage

If you want to prevent auto initialization of the tracking library, include the skipStart=1 URL parameter on the script tag URL. You can then start tracking when your app is ready, including custom (optional) configuration:

pcTrack.startTracking({
  customerId: shop.myshopifyDomain,
  properties: {
    user_id: currentUser.id,
  },
  beforeSend: (event) => !currentUser.isStaff,
});

The arguments to startTracking are all optional:

customerId can be included to overwrite the script's automatic shop detection. This can be the myshopify.com domain.
properties are a pre-set set of properties that will be included with all events sent, merged with any properties you include on the event itself.
beforeSend is a callback you can use to dynamically send or not send the event; if it returns false the event will not be sent.

Session recording

Take it a step further and watch sampled sessions back. Turn on Session recording in the same PartnerConsole Pixel card and the Pixel records how merchants move through your app (DOM changes, clicks, scrolling), replayable under Behavior › Recordings. Nothing else to install: the recorder loads only for sessions that are actually being recorded.

Recording is built to keep you on the right side of Shopify's protected customer data rules:

Form inputs are always masked; passwords are never recordable.
Choose Mask all text to redact every text node while keeping structure and interactions visible.
Add the pc-no-capture class to any element you never want captured.
The recorder runs inside your app's own frame, so it can only ever see your app's UI, never the Shopify admin around it or other apps.
Recordings are kept for 30 days, and any recording can be deleted from the console.

Pick a sample rate (10 to 100% of sessions) to match your traffic. Your beforeSend callback and the rest of the pixel are unaffected either way.

Pixel or server-side API?

Use both. The pixel is the right tool for page views, sessions and anything that happens in the browser. Use the server-side API for events the browser can't see or that must not be spoofable: billing-adjacent counters, webhook-driven activity, background jobs. They land in the same stream.

On this page