docs: document the web SDK first-party collection domain - #195
Open
tashviks wants to merge 3 commits into
Open
Conversation
Adds the data-domain section to /sdk/web: register the subdomain, CNAME it, name it in the script tag, verify. Ad blockers match a request by its domain, so events sent to api.linkrunner.io are dropped in the browser for roughly a quarter of desktop visitors. Collecting from a subdomain of the customer's own site is what survives that, and until now the only way to set one up was for us to ship a mapping inside the bundle. Covers the hostname-not-a-URL rule (the collection path can change, and naming only the host means their page follows it), the OPTIONS preflight check so they can confirm the subdomain actually serves the collector before relying on it, and the two-requests-per-event symptom with what it means. Companion to linkrunner-labs/web-sdk#10. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Integrators had no way to know what is validated before an event is accepted, which is the thing that tells them where each event belongs. A token is required (400 without one, 401 if unknown), an event_type or event_name is required, requests over 64 KB are rejected, and string fields truncate at 2048 characters. The part worth spelling out is that the token is public by design. It is in the page source of every site running the SDK, so it identifies a project rather than authenticating a sender, and a 401 says a token is unknown rather than saying who sent the request. Without that stated, the 401 reads as an access control and browser events look more trustworthy than they are. Ends with the practical rule: behavioral analytics from the browser, anything that grants access or moves money from the backend. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This reverts commit 2d4af7c.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to linkrunner-labs/web-sdk#10, which adds the
data-domainattribute.What
A new First-party collection domain (recommended) section on
/sdk/web, under Configuration. Four steps: register the subdomain in Settings → Manage Domains, CNAME it toapi.linkrunner.io, adddata-domainto the script tag, verify.Shown for all three surfaces the SDK supports: the script tag,
<LinkrunnerScript domain="…" />, andwindow.LinkrunnerConfig.Why
Ad blockers match a request by its domain, so events sent to
api.linkrunner.ioare dropped in the browser for roughly a quarter of desktop visitors. Collecting from a subdomain of the customer's own site is what survives that, and until now the only way to set one up was for us to ship a mapping inside the bundle, keyed to their token. This documents the self-serve path.Details worth a look in review
<Note>, because the collection path belongs to us and can change; naming only the host means their page keeps working without an edit.curl -i -X OPTIONSpreflight check, expecting204withaccess-control-allow-origin. A CNAME and a certificate alone are not enough, and anything they put in front of the subdomain (WAF, bot filter, auth proxy) sits in the path too.<Warning>with what it means and what to check.Follows the repo writing rules: no em-dashes, second person,
<Steps>/<Note>/<Warning>components, bold for UI labels and backticks for code identifiers.Not addressed here
The rest of
sdk/web.mdxis stale against the shipped SDK — it documentssdk.linkrunner.io/latest/linkrunner-sdk.min.js, a baretoken=attribute, and@linkrunner/web-sdk/useLinkrunner, where the package is@linkrunner/webserved fromcdn.linkrunner.io/web/v1/lr.jswithdata-token. My section uses the real names, so it now sits beside snippets that contradict it. Left out of this PR to keep the diff reviewable; happy to bring the page in line in a follow-up if you want it.No screenshots: every step here is a DNS record, a script tag, or a terminal command. The Settings → Manage Domains step is the only UI touch and could take one if you'd prefer.
🤖 Generated with Claude Code