@littledata/ld-headless-fetchclientid

Headless ClientId Fetching Library

Headless ClientId Fetching Library has been written to support the Shopify stores with a custom (headless) frontend. Its role is to connect the frontend visitor tracking with Littledata’s serverside infrastructure and provide uninterrupted session tracking.

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

The NPM library consists of the three main functions, fetchClientId, sendCartToLittledata and sendCheckoutToLittledata, and a group of helper functions within the folder Helpers. It also contains typings in the file types.ts in the directory named Types.

The purpose of fetchClientId function is to fetch and save tracking (client or session) IDs from the frontend trackers LD supports (GA3, GA4, Segment, Facebook). sendCartToLittledata sends these IDs and Cart token to LD’s Transaction Monitor, and as an output, provides the data payload (containing the tracking IDs) that a merchant should use to update Shopify’s Note Attributes. sendCheckoutToLittledata works in the same way (as sendCartToLittledata), with the difference of sending the Checkout token to the LD's servers.

How to run it

The fetchClientId function should be run on every page of the headless store, after all of the targeted tracking libraries are loaded. What it means is that, for example, GA library has to be loaded first, and then the fetchClientId function should be run.

As an argument, the function expects an object that contains tracking/pixel IDs for GA3, GA4, FB, and Segment (more details below).

This is how the function and its arguments look like:

fetchClientId({ga3PropertyId: string, ga4MeasurementId: string, fbPixelId: string, segmentWriteKey: string})

For the library to work, at least one of the tracking/pixel IDs is required (ga3PropertyId or ga4MeasurementId or fbPixelId or segmentWriteKey)

You might be forming the cart via Shopify's API immediately after the headless store has been initialized, or you might be doing that at the moment of an addition of a product to a cart. You also might have decided to be storing the cart contents in the actual Checkout, thus this is what you are forming via the API. Whether you create a Cart or Checkout via Shopify API on your custom frontend, you would need to fire our sendCartToLittledata or sendCheckoutToLittledata function, with the appropriate token (you get from Shopify) as a string.

Argument	Description	Usage
ga3PropertyId	Universal Analytics (GA3) property ID (ex. UA-123123-1)	Send it with every call of the function
ga4MeasurementId	Google Analytics 4 measurement ID (ex. G-123ABC123	Send it with every call of the function
fbPixelId	Facebook pixel ID	Send it with every call of the function
segmentWriteKey	Segment.io write key that you get after making a source	Send it with every call of the function

How it works

This integration assumes all the tracking scripts (gtag, FB pixel, and/or Segment’s analytics library) to be already installed on the custom frontend and loaded before the LD’s clientID fetching library.

The LD library gets the visitors' session IDs from the tracking scripts and saves them in the localStorage (named littledataIDs). You can choose which IDs will be saved depending on the arguments given in the function's input. For example, if you provide your Universal Analytics property ID as one of the arguments, the function will pick up the generated clientId from the gtag library and save it in the localStorage variable.

Depending on the input argument, Littledata is saving:

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

Facebook tracking

In the case of Facebook, 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 be pertained to when the server-side tracking starts. Without the fbp ID created in the browser, ad and campaign data wouldn’t be attributed when the conversion (transaction) happens. Also, fbc is made in the same way by Littledata’s library from the fbclid query parameter in the URL of the landing page. We are saving the fbclid parameter in littledataIDs localStorage whenever it appears in the URL. If the visitors arrive from two separate Facebook ad campaigns during the same session, we will store the latest campaign data (from fbclid).

Cart and Checkout

Some headless stores use Shopify Cart, while some use Shopify Checkout to store the products added to the cart.

Whichever of these two your headless store is using, the moment you get the Cart or Checkout token back from Shopify API, you need to run the fetchClientId function with either of those two as the argument. LD library returns a Promise containing the Note Attributes object contents that you should send to Shopify. This means you should wait for the output of the LD’s function and use that object as the input for the Cart Update or Checkout Update API call to Shopify.

Here is an example of how that function call might look like (when the Shopify Checkout is used as a cart storage):

sendCartToLittledata('fjlal776aiihOiaoRG').then((output)=>{...this is when you run a function to send the 'output' object to Shopify...})

Here is an example of how an output object from a Promise might look like:

{
  customAttributes: [
    { key: "google-clientID", value: "ga.1.122311321.4564654" },
    { key: "fbp-clientID", value: "fb.1.1231321.4564654" },
    { key: "fbc-clientID", value: "fb.1.1231321.bfcm_campaign" },
  ];
}

The example above assumes you have GA and FB trackers loaded on the webiste and that you have fired fetchClientId function with GA3/4 ids and FB pixels id as arguments.

Littledata assumes you would use Shopify JS Buy SDK to send the data and update the Checkout or Cart. The method used from within this SDK would be https://shopify.github.io/js-buy-sdk/#updating-checkout-attributes. If you need a different output to match another Shopify API, please use this LD library’s output object as an input for your function and convert it to the format you need for your API integration.