Custom stores: keeping the click

On a store you built yourself, you do three things: save the click id when a shopper lands, add the page script, and attach the click id to the order.

On WooCommerce, the plugin does all of this for you.

1. Save the click id on landing

When a request arrives with sbid in the query string, set the referral cookies from your server, on your registrable domain. Server-set cookies last longer in Safari than cookies set by JavaScript.

Node (Express style)js
const LOOSE = /^sb[0-9]\.[A-Za-z0-9._-]{20,96}$/;
const DAYS = 30; // your offer's referral window

app.use((req, res, next) => {
  const id = req.query.sbid;
  if (typeof id === 'string' && LOOSE.test(id)) {
    const old = req.cookies._sbid;
    // Keep the newer click. Click ids sort by time after the "sb1." prefix.
    if (!old || id.split('.')[1] > old.split('.')[1]) {
      const opts = { domain: '.yourstore.co.za', path: '/', maxAge: DAYS * 86400000,
                     sameSite: 'lax', secure: true, httpOnly: true };
      const history = old ? [old, ...(req.cookies._sbh || '').split(',')].filter(Boolean).slice(0, 3) : [];
      res.cookie('_sbid', id, opts);
      if (history.length) res.cookie('_sbh', history.join(','), opts);
      res.cookie('_sbt', '1', { domain: '.yourstore.co.za', path: '/', sameSite: 'lax', secure: true });
      res.set('Cache-Control', 'private, no-store');
    }
  }
  next();
});
  • Accept any id that matches the loose pattern. Never try to check the signature yourself.
  • Do not replace an existing cookie with a click id minted more than an hour ago (the link was reused, not clicked).
  • Any response that sets the cookies must be no-store, so your page cache never replays them to someone else.

2. A touch route for cached pages

If a page is served from a cache, your server never sees the query string. The page script then calls a same-origin route with the click id, and your route sets the same cookies and answers 204 with Cache-Control: no-store.

Request from the page scripthttp
POST /api/sentby/touch
Content-Type: application/json

{"sbid":"sb1.01JD3H8M2Q4W7XKZP0A9BCDEF0.7Hk2pQ9x.K4M2QX7PZA"}

3. Add the page script

Download s.js from your SentBy settings and serve it from your own domain. It is under 3 KB, has no dependencies and sets no cookies itself. Load it on every page except cart, checkout and order confirmation.

In your page layouthtml
<script src="/assets/sentby/s.js" data-key="pk_live_..." data-touch="/api/sentby/touch" defer></script>

On each page the script:

  1. Reads sbid from the address. If the server has not saved it yet, it calls your touch route.
  2. Confirms the landing to https://api.sentby.co.za/v1/landing with your publishable key. This only confirms a click; it never creates one.
  3. Removes only sbid from the address bar, after your analytics have read the page. UTM tags stay. Inside in-app browsers it leaves sbid in place, so “Open in browser” carries it.
JavaScript APIjs
window.sentby.clickId();     // the current click id, or null
window.sentby.consent(true); // call when the shopper accepts marketing cookies

4. Attach the click to the order

When an order is created, copy _sbid and _sbh from the request cookies onto the order. When it is paid, send them to SentBy as click_id and click_history in an order.paid event.