npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@littledata/headless-shopify-sdk

v1.6.0

Published

Library for connecting headless (custom) ecommerce frontends with Littledata

Downloads

28,725

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:

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.