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. Include gtag with all page views

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 GA, but you would need to trigger any pre-checkout events (e.g. view_item, add_to_cart) using gtag from your headless storefront.

2. After a checkout is created, add the GA client ID and session ID as note attributes

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

// 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(()=> {
  // wait for payload to be sent
})

3. On your server, include Littledata note attributes with the checkout

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

import Client from 'shopify-buy';

// Initializing a client
const client = 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 }; // from client

client.checkout.updateAttributes(checkoutId, input)

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 cart
})

Adding Facebook Pixel tracking

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

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

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

Adding Segment tracking

If you want to also 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'

littledata.fetchClientIds({ segmentWriteKey: 'YOUR_WRITE_KEY' })

Adding TikTook tracking

If you want to also 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 arguments:

| Argument | Description | |:------------------:|:------------------------------------------------------:| | ga3PropertyId | Universal Analytics (GA3) property ID (eg UA-123123-1) | | ga4MeasurementId | Google Analytics 4 Measurement ID (eg G-123ABC123) | | fbPixelId | Facebook pixel ID | | segmentWriteKey | Segment write key that you get after making a source | | tiktokPixelId | TikTok pixel ID |

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

You can also fetch IDs from multiple trackers by passing multiple arguments. For example:

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

littledata.fetchClientIds({ ga4MeasurementId: 'G_ID', fbPixelId: 'PIXEL_ID', tiktokPixelId: 'PIXEL_ID' })

Here is an example of what this method outputs:

[
  { key: "_google-clientID", value: "915202628.1708444611" },
  { 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 sends these IDs and Shopify Cart token to Littledata, and as an output, provides the data payload (containing the tracking IDs) that a merchant should use to update Shopify’s Note Attributes.

littledata.sendCheckoutToLittledata works in the same way, with the difference of sending the Shopify Checkout token with the payload to Littledata.

How it works

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 arguments given:

| Argument | Parameter saved in littledataIDs localStorage | |:----------------------:|:-------------------------------------------------:| | shopifyCartToken | cartID | | shopifyCheckoutToken | checkoutID | | ga3PropertyId | _google-clientID | | 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.