@littledata/headless-shopify-sdk

Littledata Headless Shopify SDK

Littledata's headless frontend SDK helps Shopify stores with a custom (headless) frontend connect the visitor tracking with Littledata’s serverside infrastructure. This allows Litledata to provide uninterrupted session tracking.

It is written in Typescript, and can work on any JS frontend framework.

This SDK supports:

• Google Analytics 4 (via gtag)
• Facebook / Meta Conversions API (via Meta Pixel)
• Segment (via AnalyticsJS)
• TikTok (via TikTok Pixel)

Quickstart guide for Google Analytics using Checkout API

1. Load gtag with all page views (client-side)

Even if you are not using gtag for tracking events, this is required to set and update the cookies that Google Analytics relies on.

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-MEASUREMENTID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'G-MEASUREMENTID'); // replace with your Measurement ID
</script>

Note: gtag('config') will automatically track page view events to Google Analytics, but you would need to trigger any pre-checkout events (e.g. view_item, add_to_cart) using the gtag events API from your headless storefront.

2. Fetch the Google client ID (client-side) and pass to your server

import littledata from '@littledata/headless-shopify-sdk'

const ga4MeasurementId = 'G-MEASUREMENTID' // replace with your Measurement ID

const littledataNoteAttributes = littledata.fetchClientIds({ ga4MeasurementId })

// SEND these note attributes to your back end server
// and then on to Shopify's checkout API in step 3

See below for how to collect identifiers for other marketing platforms.

2. Include Littledata note attributes with the checkout (server-side)

This example uses the Shopify Buy SDK, but you might also use the Storefront checkout API

This does NOT load the Littledata Headless Shopify SDK, which is only for use within the browser.

import Client from 'shopify-buy';

const shopifyClient = Client.buildClient({
  domain: 'your-shop-name.myshopify.com',
  storefrontAccessToken: 'your-storefront-access-token'
});

const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8';
const input = { customAttributes: littledataNoteAttributes }; // passed in step 1 from the browser

shopifyClient.checkout.updateAttributes(checkoutId, input)

4 After a checkout token is created, pass the client IDs direct to Littledata (client-side)

Optional step for further accuracy

The sendCheckoutToLittledata method allows Littledata to link the session with the checkout, even if the checkout attributes are accidentally overwritten.

import littledata from '@littledata/headless-shopify-sdk'
// if you have checkout token on the storefront, then also run
// this method to send payload to Littledata for extra accuracy 

littledata.sendCheckoutToLittledata(SHOPIFY_CHECKOUT_TOKEN).then(()=> {
  // optionally wait for payload to be sent
})

This SHOPIFY_CHECKOUT_TOKEN can be parsed from the GraphQL identifier - the final sequence of numbers in gid://shopify/Checkouts/1234567

Using the Shopify Cart API

If your storefront interacts with the Shopify cart API, you can alternatively use the sendCartToLittledata method with a Shopify cart token.

import littledata from '@littledata/headless-shopify-sdk'

const ga4MeasurementId = 'G-MEASUREMENTID' // replace with your Measurement ID

littledata.fetchClientIds({ ga4MeasurementId })

littledata.sendCartToLittledata(SHOPIFY_CART_TOKEN).then((noteAttributes) => {
  // then add noteAttributes to the Shopify cart
})

This SHOPIFY_CART_TOKEN can be parsed from the GraphQL identifier - the final sequence of numbers in gid://shopify/Carts/1234567

Adding Facebook Pixel tracking

To support the Facebook Conversions API destination from Littledata, you will need to include Facebook Pixel and then fetch that pixel ID.

import littledata from '@littledata/headless-shopify-sdk'

const littledataNoteAttributes = littledata.fetchClientIds({ 
  ga4MeasurementId: 'G-MEASUREMENTID',
  fbPixelId: 'PIXEL_ID'
  })

// SEND these note attributes to your back end server

Adding Segment tracking

To support the Segment destination from Littledata, you will need to include the AnalyticsJS library and fetch for that write key.

import littledata from '@littledata/headless-shopify-sdk'

const littledataNoteAttributes = littledata.fetchClientIds({ segmentWriteKey: 'YOUR_WRITE_KEY' })

Adding TikTok tracking

To support the TikTok destination from Littledata, you will need to include the TikTok pixel and fetch for that pixel ID.

import littledata from '@littledata/headless-shopify-sdk'

littledata.fetchClientIds({ tiktokPixelId: 'PIXEL_ID' })

Using fetchClientIds method

littledata.fetchClientIds accepts at least one of the following keys in the argument object:

Key	Description
ga4MeasurementId	Google Analytics 4 Measurement ID (eg G-123ABC123)
fbPixelId	Facebook Pixel ID
segmentWriteKey	Segment write key
tiktokPixelId	TikTok pixel ID

The purpose of fetchClientIds method is to fetch client or session IDs from the frontend trackers Littledata supports (GA4, Segment, Facebook, TikTok), save to localstorage and output into a note attributes format for adding to the Shopify cart or checkout.

Here is an example of what this method outputs when tracking GA4, Facebook and TikTok:

[
  { key: "_ga4session-clientID", value: "1708520334"}
  { key: "_fbp-clientID", value: "fb.1.1231321.4564654" },
  { key: "_fbc-clientID", value: "fb.1.1231321.bfcm_campaign" },
  { key: "_ttp-clientID", value: "9ien4kKu3pyvo1Ld12Or-GYFahP" },
  { key: "_ttclid-clientID", value: "al23lkj234lkjladfj23l4kjKJHKyKHKNk" },
]

Using sendCartToLittledata and sendCheckoutToLittledata methods

littledata.sendCartToLittledata accepts a Shopify cart token as a single parameter, picks up the noteAttributes object from local storage, and Shopify Cart token to Littledata

It returns a promise with the formatted noteAttributes payload (containing the tracking IDs) that you can use to update the cart attributes.

littledata.sendCheckoutToLittledata works in the same way, but accepts a Shopify Checkout token instead of a cart token to send to Littledata.

The littledataIDs localStorage object

This package gets the visitors' session IDs from the tracking scripts or cookies and saves them in the localStorage (named littledataIDs). You choose which IDs will be saved depending on the argument given:

Key	Parameter saved in littledataIDs localStorage
shopifyCartToken	cartID
shopifyCheckoutToken	checkoutID
ga4MeasurementId	_google-clientID and _ga4session-clientID
segmentWriteKey	_segment-clientID
fbPixelId	_fbp-clientID and _fbc-clientID
tiktokPixelId	_ttp-clientID and _ttclid-clientID

Facebook tracking

In some countries and legislative areas fbp and fbc IDs are not created in the visitor's browser by Facebook’s own script. In those cases, Littledata’s library creates these IDs so that visitor’s session can linked to the server-side tracking. Without the fbp ID created in the browser, ad and campaign data wouldn’t be attributed when the conversion (transaction) happens.