@polar-analytics/pixel-sdk NPM

Pixel SDK

A lightweight JavaScript utility for reporting user touchpoints, similar to the Polar Analytics Pixel.

Installation
Example usage
API Reference
For SDK developers

Installation

npm install @polar-analytics/pixel-sdk

Example usage

import {
  generatePayloadBase,
  sendPixelEvent,
  eventFactory,
} from "@polar-analytics/pixel-sdk";

const payloadBase = await generatePayloadBase({
  customer: {
    // Optional, include if available
    id: "some-id",
    email: "some-email",
  },
});

// An anonymous ID to identify the device + browser
// Please refer to https://community.shopify.com/c/shopify-apps/web-pixel-clientid/m-p/2664271/highlight/true#M80886
const shopifyClientId =

// <the url of the shopify store> i.e. something.myshopify.com
const shopifyShopURL =

// Use the corresponding eventFactory for the desired event type.
const data = eventFactory.cart_viewed({
    shopifyEventId: crypto.randomUUID(),
    shopifyClientId,
    shopifyShopURL,
})

/* If you want to send a custom event not supported by the event factory,
   you can use this helper instead.

   Please only use this method if the event is not supported natively by
   the eventFactory. Using the custom event handler to send a non-custom
   supported event might result in sending incomplete data.

const data = eventFactory.custom({
  shopifyEventName: "<the-name-of-the-custom-event>",
  shopifyEventId: crypto.randomUUID(),
  shopifyClientId,
  shopifyShopURL,
})
*/

sendPixelEvent(
  pixelEndpoint /* obtained from polar analytics */,
  payloadBase,
  { data },
);

API Reference

Supported Events

eventFactory.page_viewed
eventFactory.product_viewed
eventFactory.collection_viewed
eventFactory.search_submitted
eventFactory.cart_viewed
eventFactory.product_added_to_cart
eventFactory.product_removed_from_cart
eventFactory.checkout_started
eventFactory.checkout_address_info_submitted
eventFactory.checkout_contact_info_submitted
eventFactory.checkout_shipping_info_submitted
eventFactory.payment_info_submitted
eventFactory.checkout_completed
eventFactory.custom

`eventFactory.page_viewed`

The page_viewed event logs an instance where a customer visited a page. This event is available on the online store, checkout, and Order status pages.
Source: Shopify Documentation

`eventFactory.product_viewed`

The product_viewed event logs an instance where a customer visited a product details page. This event is available on the product page.
Source: Shopify Documentation

`eventFactory.collection_viewed`

The collection_viewed event logs an instance where a customer visited a product collection index page. This event is available on the online store page.
Source: Shopify Documentation

`eventFactory.search_submitted`

The search_submitted event logs an instance where a customer performed a search on the storefront. The products returned from the search query are in this event object (the first product variant for each product is listed in the array). This event is available on the online store page.
Source: Shopify Documentation

`eventFactory.cart_viewed`

The cart_viewed event logs an instance where a customer visited the cart page.
Source: Shopify Documentation

`eventFactory.product_added_to_cart`

The product_added_to_cart event logs an instance where a customer adds a product to their cart. This event is available on the online store page.
Source: Shopify Documentation

`eventFactory.product_removed_from_cart`

The product_removed_from_cart event logs an instance where a customer removes a product from their cart. This event is available on the online store page.
Source: Shopify Documentation

`eventFactory.checkout_started`

The checkout_started event logs an instance of a customer starting the checkout process. This event is available on the checkout page. For Checkout Extensibility, this event is triggered every time a customer enters checkout. For non-checkout extensible shops, this event is only triggered the first time a customer enters checkout.
Source: Shopify Documentation

`eventFactory.checkout_address_info_submitted`

The checkout_address_info_submitted event logs an instance of a customer submitting their mailing address. This event is only available in checkouts where Checkout Extensibility for customizations is enabled.
Source: Shopify Documentation

`eventFactory.checkout_contact_info_submitted`

The checkout_contact_info_submitted event logs an instance where a customer submits a checkout form. This event is only available in checkouts where Checkout Extensibility for customizations is enabled.
Source: Shopify Documentation

`eventFactory.checkout_shipping_info_submitted`

The checkout_shipping_info_submitted event logs an instance where the customer chooses a shipping rate. This event is only available in checkouts where Checkout Extensibility for customizations is enabled.
Source: Shopify Documentation

`eventFactory.payment_info_submitted`

The payment_info_submitted event logs an instance of a customer submitting their payment information. This event is available on the checkout page.
Source: Shopify Documentation

`eventFactory.checkout_completed`

The checkout_completed event logs when a visitor completes a purchase. It's triggered once for each checkout, typically on the Thank you page. However, for upsells and post purchases, the checkout_completed event is triggered on the first upsell offer page instead. The event isn't triggered again on the Thank you page. If the page where the event is supposed to be triggered fails to load, then the checkout_completed event isn't triggered at all.
Source: Shopify Documentation

`eventFactory.custom`

Use if you want to track something not covered by the standard events listed above.

For SDK developers

How to deploy a new version

Make the changes you want to make, try to be backwards compatible when possible
Create a CHANGELOG.md entry using npx changeset
Deploy to NPM using yarn deploy (You need access to the NPM 2FA)
Commit and merge the changes.
Update the Polar Shopify Extension to use the latest version of the SDK
(If relevant) inform third-parties using the SDK that there is value in updating.