Linked domains
Keep visitor tracking when people click from your site to your app or checkout on another domain.
Site analytics follow a visitor with a first-party cookie on your site's domain. When someone clicks through to a different domain, such as app.example.com or a checkout, that cookie does not go with them. Linked domains hand the visit over on the link itself.
Set it up
Open Settings → Tracking → Linked Domains and add up to 10 domains, such as app.example.com. A bare hostname becomes https://app.example.com. Only https origins are allowed, and each subdomain is listed separately.
Changes go live on the next publish.
To track visits on a site you host elsewhere and hand them over the same way, see External sites.
Your workspace's community checkout is always linked; you don't need to add it. The community keeps the first visit it sees in a __Host-pw_visit cookie for 30 days, so product, checkout, and join pages still credit the site when the buyer opens them later without pw_site and pw_vid, from a new tab, a bookmark, or a cleaned-up link.
What the link carries
When a visitor clicks a link to a linked domain, Planeward adds two query parameters at click time:
| Parameter | Value |
|---|---|
pw_site | The site's id |
pw_vid | The visitor's anonymous id, a UUID from the pw_vid cookie |
https://app.example.com/signup?plan=pro&pw_site=cm3k9x2ab0001&pw_vid=3f1c2a9e-7b4d-4e8a-9c21-5d6e7f8a9b0cLinks that already have either parameter are left alone. Links to other domains never get them.
Read them in your app
Your app reads the parameters on landing, keeps them until the visitor buys, and sends them back with the purchase. A typical flow:
- On the first page load, read
pw_siteandpw_vidfrom the URL. - Check
pw_vidis a UUID andpw_siteis a short id (64 characters or fewer). Ignore anything else. - Store them in a first-party cookie or
localStorageon your domain. Keep the first pair you see, and don't overwrite it on later visits. - Remove them from the address bar so they aren't shared when someone copies the URL.
- On signup, save them on the user record.
- When that user pays, send them as
siteVisitwhen you record the purchase.
const UUID =
/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
export function captureSiteVisit() {
const url = new URL(window.location.href);
const siteId = url.searchParams.get("pw_site")?.trim() ?? "";
const visitorId = url.searchParams.get("pw_vid")?.trim() ?? "";
if (siteId && siteId.length <= 64 && UUID.test(visitorId)) {
if (!localStorage.getItem("pw_visit")) {
localStorage.setItem("pw_visit", JSON.stringify({ siteId, visitorId }));
}
url.searchParams.delete("pw_site");
url.searchParams.delete("pw_vid");
history.replaceState(null, "", url);
}
}
export function storedSiteVisit(): {
siteId: string;
visitorId: string;
} | null {
try {
return JSON.parse(localStorage.getItem("pw_visit") ?? "null");
} catch {
return null;
}
}Send storedSiteVisit() with your signup request and store it on the user.
Send it with the purchase
Record the sale with POST /purchases or the MCP tool planeward-purchase-record, and pass the stored pair as siteVisit:
{
"externalRef": "order_1042",
"amount": 4900,
"currency": "USD",
"buyer": { "email": "[email protected]" },
"siteVisit": {
"siteId": "cm3k9x2ab0001",
"visitorId": "3f1c2a9e-7b4d-4e8a-9c21-5d6e7f8a9b0c"
}
}Planeward checks that this visitor has a pageview on that site in your workspace. If so, the sale is credited to the visit: it shows up in the site's Analytics under the channel and campaign that brought the visitor, and the contact gets those first-touch UTMs if it had none. The response says what happened:
siteVisit in the response | Meaning |
|---|---|
{ "credited": true, "siteId": "…" } | Verified and credited |
{ "credited": false, "reason": "invalid" } | The ids are malformed |
{ "credited": false, "reason": "not_found" } | No pageview from that visitor on that site |
An unverifiable visit never fails the purchase; the sale is still recorded. Recording is idempotent on externalRef, so a retry does not credit twice. A tampered link can't credit the wrong site or campaign.
Privacy
pw_vid is an anonymous id. It names no person until your app links it to an account. Treat it like any other analytics id: mention it in your privacy notice, and do not pass it on to other services.
Planeward Docs