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.
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.
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.
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.
<script src="/assets/sentby/s.js" data-key="pk_live_..." data-touch="/api/sentby/touch" defer></script>
On each page the script:
- Reads
sbidfrom the address. If the server has not saved it yet, it calls your touch route. - Confirms the landing to
https://api.sentby.co.za/v1/landingwith your publishable key. This only confirms a click; it never creates one. - Removes only
sbidfrom the address bar, after your analytics have read the page. UTM tags stay. Inside in-app browsers it leavessbidin place, so “Open in browser” carries it.
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.