@littledata/headless-shopify-sdk
v1.6.0
Published
Library for connecting headless (custom) ecommerce frontends with Littledata
Downloads
27,216
Readme
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.