docs: add Shopify integration guide for the web SDK - #190
Open
samiksha-shreya wants to merge 5 commits into
Open
docs: add Shopify integration guide for the web SDK#190samiksha-shreya wants to merge 5 commits into
samiksha-shreya wants to merge 5 commits into
Conversation
Shopify needs the web SDK installed in two places, because scripts are not allowed on the checkout and thank-you pages. The storefront gets a script tag; checkout gets a custom pixel that reads the SDK's stored values through Shopify's sandboxed browser API and posts the purchase itself. Adds sdk/shopify.mdx with prerequisites, four install steps, annotated screenshots of the Shopify admin, a limitations section, and troubleshooting. Links it from sdk/web.mdx and registers it in the sidebar. Notable content decisions: - Customer email and phone are commented out in the pixel by default. They are only needed for person-level audience exports, and sending shopper PII should be the merchant's informed choice. - The Shop Pay caveat is called out: those checkouts run on shop.app, a different origin, so the cart-attribute step is required rather than optional. - The customer privacy Permission and Data sale settings are documented with what to do, since the defaults are already correct and the failure mode (pixel silently never fires) is otherwise hard to diagnose. Verified end to end against a real Shopify checkout before publishing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Person-level audiences are a core part of what the web SDK offers, and they depend on these two fields: the cohort export reads them as identity traits. Shipping them commented out meant every Shopify merchant silently lost that capability unless they noticed and edited the snippet. Keeps the warning, reframed around opting out rather than opting in, so the privacy notice and DPA obligation is still stated plainly and a merchant who does not want to send contact details knows exactly which two lines to remove and what it costs them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…e path Sends merchants straight to Settings -> Whitelist SDKs and to Web Events rather than making them navigate there. Also fixes the domain: the rest of the docs use dashboard.linkrunner.io, this page had linkrunner.io/dashboard. Keeps a step telling them to confirm the right project is selected, since a deep link does not choose one and the token is per project. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The Shopify admin sidebar shows the organisation name and the store row on every settings screen, and the themes page shows the store name inside both theme previews. None of that belongs in a public docs page. Re-rendered from the original captures with the extra regions blurred, so the annotations and framing are unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Reframes the version note around what to do rather than what older builds lacked. The CDN URL in Step 1 always serves the current version, so for anyone following the guide there is nothing to do at all. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Why
A Shopify store cannot install the web SDK the normal way. Shopify blocks scripts on the checkout and thank-you pages,
checkout.liquidis gone, and the only supported route is a custom pixel that runs sandboxed. Without a guide, merchants get page views but no purchases, or a purchase that never links to the visitor who made it.What
sdk/shopify.mdx: prerequisites, four install steps, annotated screenshots of the Shopify admin, a limitations section, and troubleshooting. Linked fromsdk/web.mdxand added to the sidebar.The two-part install:
theme.liquidfor the storefrontbrowserAPI and posts the purchase itselfPlus a cart-attribute snippet that carries the visitor ID into the order.
Content decisions worth reviewing
Customer email and phone are commented out by default. They are only needed for person-level audience exports. Sending shopper PII to Linkrunner should be a merchant's informed choice, covered by their privacy notice and DPA, not something they enable by pasting a snippet they did not read. Attribution and revenue work without them.
Shop Pay is called out as requiring the cart-attribute step. Those checkouts render on
shop.app, a different origin, so the pixel's storage read returns nothing. The cart attribute is the only thing that links those purchases back to the browsing session. This is why that step is documented as required rather than optional.The customer privacy settings are documented with what to do, not just pointed at. The defaults are already correct, so the instruction is to confirm them, with a warning that switching to
Not requiredis a legal decision about the merchant's markets rather than a technical one. Worth documenting because the failure mode is silent: a consent-gated pixel simply never fires.The empty
catchin the pixel is deliberate and explained in the page. A pixel that throws can interrupt checkout.Verification
Tested end to end against a real Shopify checkout on a development store, not just written. A shopper arrived from a Meta ad, browsed, and bought; the purchase joined to the browsing session and rolled up as:
The pixel code in the page is the exact code that was tested. I extracted it back out of the published page and re-ran it to confirm no PII is sent by default.
Known gap
The guide states it needs
@linkrunner/web>= 0.1.13, which is not published yet (linkrunner-labs/web-sdk#7). Until thenlr_ts_*is absent and the pixel falls back to first-touch, which is correct for single-session buyers and wrong for a visitor who arrives via an ad and returns later. Worth landing that PR before this page goes live.Not included
sdk/web.mdxdocuments a different, older SDK: wrong package (@linkrunner/web-sdk), wrong CDN (sdk.linkrunner.io), wrong attribute (token=instead ofdata-token=), and a dashboard path that no longer exists (it says "Web SDK", the menu item is "Whitelist SDKs"). I only added the cross-link here and left the rest alone, since it is live in production and out of scope. Worth a separate ticket, because a merchant following that page and then this one would install two different SDKs.🤖 Generated with Claude Code
LIN-2495