Contents

Pixels

Add custom tracking code, turn app pixels on or off, and understand where pixels run and what they receive.

Pixels send what shoppers do on your storefront, such as page views, products viewed, cart changes, checkouts and purchases, to analytics and advertising services. Open Online Store, choose your storefront, then open Pixels. The list shows your custom pixels and the pixels of the apps you installed, with their source, consent category and status. Pixels belong to the storefront, so changing your theme doesn't remove them.

Pixel	Who writes the code	Where the code runs	How it is turned on
Custom pixel	You paste JavaScript in Pixels.	In a hidden, isolated frame with no access to your pages.	With Enable this pixel when you add or edit it.
App pixel	The app's developer. The code comes with the app version you installed and can't be edited here.	In the app's own isolated frame, or directly on your pages when the pixel shows Full page access.	By you, for each storefront in Pixels. An app can also turn its pixel on for your store.

Add a custom pixel

Open Online Store, choose your storefront, open Pixels and choose Add pixel.
Enter a name you will recognize.
Choose the Consent category that matches what the code does: Analytics, Advertising or Personalized advertising.
Paste the JavaScript into Code. Paste only the script itself, without <script> tags or other HTML.
Leave Enable this pixel on to start it straight away, or turn it off to save the pixel without running it. Then choose Save.

The form shows the limits for your store. By default a storefront can have 20 custom pixels, a name can have up to 100 characters and the code up to 65,536 characters. Disabled pixels count toward the allowance. If the code of all enabled custom pixels on a page adds up to more than 512 KiB, the pixels beyond that are left out of the page.

Write the code

Custom pixel code uses two functions. tringify.pixel.subscribe(callback) calls your function for every storefront event the shopper's consent allows, including events that happened before your pixel loaded. tringify.pixel.context() returns facts about the current page: the store, the page address and type, the language, currency and country, and the shopper's consent. Each event has an event_id, a type such as page_view, product_viewed, cart_add, begin_checkout or purchase, a schema_version, a payload with the details, and a timestamp ts.

javascript

tringify.pixel.subscribe(function (event) {
  var page = tringify.pixel.context();
  fetch("https://collect.example.com/events", {
    method: "POST",
    keepalive: true,
    headers: { "Content-Type": "text/plain" },
    body: JSON.stringify({
      id: event.event_id,
      type: event.type,
      data: event.payload,
      page: page.url,
      currency: page.currency
    })
  });
});

Send event_id as the event ID wherever the service supports one. An app that also sends the same event from its server uses the same ID, so the service counts it once. The full list of events and their fields is in the canonical event reference.

What isolation means

Custom pixel code runs in a hidden, sandboxed frame. It can't read or change your pages, see what shoppers type, or use your store's cookies or browser storage.
It can send data to other services, for example with fetch or an image request, as long as the service accepts requests from a sandboxed frame.
Install snippets written to run on your page, such as ones that read the page, set cookies on your domain or add their own HTML, don't work here. Use the service's app if there is one, or its server or HTTP API.
An error in your code affects only that pixel. Your storefront and checkout keep working.

Where pixels run

On themed pages, enabled pixels start after the page has loaded or when the shopper first interacts with it, so they don't slow the page down. On checkout and order confirmation they start straight away.

Custom pixels and app pixels run on checkout and order confirmation only in an isolated frame: no app code runs in those pages themselves. An app pixel with Full page access runs there only if it also shows Runs on checkout, which means its app provides a frame for these pages; Tringify for Facebook & Instagram and Tringify for Google do. In the frame it only receives the checkout events and can't read the page.

Checkout editor previews run no pixels, and neither do visits from search engines and other bots.

When shoppers filter, sort or page through products, or choose another variant, the page updates without reloading. That isn't a new page view: pixels receive no new event, but context() returns the updated page address.

Turn pixels on or off, edit or delete them

Use the switch in the list to turn a pixel on or off for this storefront. A disabled custom pixel keeps its code.
Edit a custom pixel to change its name, consent category or code. Deleting a custom pixel removes it and its code permanently.
Changes apply to pages opened afterwards. Pages a shopper already has open keep running the earlier pixels until the page is reloaded or the shopper opens another page.

App pixels

Installing an app doesn't turn its pixel on. Turn it on for each storefront in Pixels. An app can also turn its pixel on for all your storefronts, for example when you finish its setup. Your choice wins: if you turned an app's pixel off on a storefront, the app can't turn it back on there. Storefronts you create later start with the pixel on if the app turned it on for your store.

App pixels show the app's name and consent category. You can't see or edit their code: it comes with the app version you installed and changes only when you update the app.

Most app pixels run in the app's own isolated frame, like custom pixels. A pixel marked Full page access runs the app's code directly on your storefront pages. It can read everything shown there, including what shoppers type, and send it to the app. Tringify reviews these pixels separately before an app can offer them, and asks you to confirm before you turn one on. Only turn it on for apps you trust. Runs on checkout means the pixel also runs on checkout and order confirmation, in an isolated frame that can't read those pages.

Many advertising apps also send events such as purchases from their server. Turning an app's pixel off stops only what it receives in shoppers' browsers. Manage its server events in the app's own settings, or uninstall the app. Both use the same event IDs, so the service counts each event once.

Uninstalling an app removes its pixels and their switches from all your storefronts. If you install it again, its pixels stay off until you or the app turn them on.

Consent and the data pixels receive

Every pixel has one consent category. Where your consent banner applies, a pixel starts only after the shopper allows its category, and it receives only events that happened while that category was allowed. When a shopper withdraws a category, its pixels stop receiving events at once, and a page running a Full page access pixel of that category reloads so the pixel stops. When a shopper allows a category later, the page reloads if it needs to add that category's pixels. The shopper's other open tabs of your store follow within a second. See Understand visitor consent categories.

Custom pixels and app pixels in a frame get a shortened page address: your store's address and the page path, plus campaign parameters such as utm_source, gclid or fbclid, and the page and variant parameters. Other parameters are removed. Checkout, order confirmation and account pages show only their route, such as /checkout. The referrer is shortened to the referring site's address.
Pixels with Full page access can read the full page address and referrer.
Search events include the words shoppers searched for. Shoppers sometimes type personal details into search, so only use pixels you trust with that text.
Advertising pixels also receive an advertising browser ID and campaign attribution.
An app can declare its own ad click IDs, the parameters its ad links add to your storefront address, and cookies its own code sets on your storefront. Tringify records them only when the shopper allows Advertising, keeps them through checkout with the order's campaign attribution, and gives them only to that app, with its server events and in its isolated frame pixel. Other apps and custom pixels never receive them. The app's install screen lists them under Ad click IDs and cookies.
An app receives hashed customer details, such as a hashed email address or phone number, only if it was approved for customer matching and the shopper allowed both Advertising and Advertising data. Custom pixels never receive customer details.

Test your pixels

Previews in the checkout editor run no pixels. Test on your live storefront in a private browser window: allow the pixel's consent category in the banner, then browse, add to cart and go through checkout.
Use the service's own test tools, such as a test events view, debug mode or a test pixel ID, to see what arrives without affecting your reports.
In your browser's developer tools, the Network tab shows the requests your pixel sends. Custom pixels run in a frame: choose that frame in the Console to see messages from your code.

Troubleshooting

Problem	What to check
A pixel sends nothing.	Check that it is enabled for this storefront, that you allowed its consent category in the banner, and that you reloaded the page after saving.
The code can't be saved.	Remove `<script>` tags and other HTML, and keep within the limits the form shows.
A vendor's snippet does nothing.	Snippets written for the page can't reach the page, its cookies or its storage from the isolated frame. Use the vendor's app, or its server or HTTP API.
Conversions are counted twice.	Send `event_id` as the service's event ID so browser and server events are deduplicated.
An app pixel doesn't run on checkout.	A pixel with Full page access runs on checkout and order confirmation only if its app provides a frame for these pages (it then shows Runs on checkout). Pixels in the app's frame always run there.
An app pixel is off again after reinstalling the app.	Uninstalling removes its switches. Turn the pixel on again in Pixels.
Some events never arrive.	Browser delivery is best effort: ad blockers, browser privacy settings and closed tabs can stop events. Events from before the shopper allowed a category are never sent. For reliable conversion counts, use an app that also sends server events.

Manage pixels with the Store API and AI assistants

Your own integrations and connected AI assistants can manage pixels too, with an API token or a connection you approved. Reading needs the read_storefront permission and changes need write_storefront. Apps can't use these endpoints with their own tokens.

Task	Store API	AI assistant tool
List custom pixels, without their code	`GET /api/2025-01/storefronts/{storefrontId}/custom-pixels`	`list_custom_pixels`
Read one custom pixel with its code	`GET /api/2025-01/storefronts/{storefrontId}/custom-pixels/{pixelId}`	`get_custom_pixel`
Add a custom pixel	`POST /api/2025-01/storefronts/{storefrontId}/custom-pixels`	`create_custom_pixel`
Change a custom pixel	`PUT /api/2025-01/storefronts/{storefrontId}/custom-pixels/{pixelId}`	`update_custom_pixel`
Delete a custom pixel	`DELETE /api/2025-01/storefronts/{storefrontId}/custom-pixels/{pixelId}`	`delete_custom_pixel`
List app pixels and their switches	`GET /api/2025-01/storefronts/{storefrontId}/app-pixels`	`list_app_pixels`
Turn an app pixel on or off	`PUT /api/2025-01/storefronts/{storefrontId}/app-pixels/{appId}/{embedKey}`	`set_app_pixel`

A custom pixel takes name, code, consent_category and enabled, with the same rules as in Store Admin. Turning on a Full page access pixel needs acknowledge_privileged set to true: it is the same confirmation you give in Store Admin, so ask your assistant to show you the warning first. Changes made this way appear in the activity log under the token or tool name.

Was this page helpful?