From 019716e9b5defa67afb6a5f47b3566864c609754 Mon Sep 17 00:00:00 2001 From: "posthog[bot]" <206114724+posthog[bot]@users.noreply.github.com> Date: Fri, 11 Sep 2026 12:37:05 +0000 Subject: [PATCH 1/2] docs: add a troubleshooting path to the Shopify guide The Shopify guide told readers to verify the install in the activity tab and stopped there. It linked to no troubleshooting page, so a reader with an empty activity tab had no next step. Add a short "If your events do not appear" section next to the verification step. It names the two causes the guide missed - a token that is for a different project, and a third-party Shopify app that controls what it sends - then links to the product analytics troubleshooting page for everything else. Also add the wrong-project token cause to the product analytics troubleshooting page, because it applies to every library, not just Shopify. Generated-By: PostHog Desktop Task-Id: 5f57a033-1996-4724-a563-7dd21af4d396 --- contents/docs/libraries/shopify.mdx | 9 +++++++++ contents/docs/product-analytics/troubleshooting.mdx | 12 ++++++++---- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/contents/docs/libraries/shopify.mdx b/contents/docs/libraries/shopify.mdx index f471b173267e..96d6055c6c36 100644 --- a/contents/docs/libraries/shopify.mdx +++ b/contents/docs/libraries/shopify.mdx @@ -28,6 +28,15 @@ This guide walks you through integrating PostHog into your Shopify store using a > To confirm PostHog is configured correctly, visit your store and then check if the events from your session appear in the [PostHog activity tab](https://us.posthog.com/events). This may take a few minutes. +### If your events do not appear + +If your session does not appear in the activity tab, check these two causes first: + +- **The token is for a different project.** The capture endpoint accepts any valid project token. If you use the token of another project, your requests succeed, but the events go to that project. Compare the token in `theme.liquid` with the token in the ["Project variables" section of your project settings](https://us.posthog.com/settings/project#variables). +- **A third-party app sends the events.** If you use an unofficial Shopify app instead of the snippet, that app controls which events it sends and which token it sends them with. We cannot support these apps. Install the snippet manually with the steps above, then test again. + +For all other causes, such as ad blockers or a misconfigured library, see [Product analytics troubleshooting](/docs/product-analytics/troubleshooting#why-are-events-not-appearing-in-my-project). + ### Enabling heatmap The heatmap won't work on Shopify out of the box because Shopify has very strict CSP headers, particularly `frame-ancestors`. diff --git a/contents/docs/product-analytics/troubleshooting.mdx b/contents/docs/product-analytics/troubleshooting.mdx index 199435db4133..3272a45b43df 100644 --- a/contents/docs/product-analytics/troubleshooting.mdx +++ b/contents/docs/product-analytics/troubleshooting.mdx @@ -72,13 +72,17 @@ If events are visible in webhook.site, it means that you have configured PostHog ![Events visible on webhook.site](https://res.cloudinary.com/dmukukwp6/image/upload/v1710055416/posthog.com/contents/images/docs/product-analytics/events-in-webhook.site.png) -**2. PostHog is adblocked** +**2. Your events go to a different project** + +The capture endpoint accepts any valid project token and returns a success response. If you use the token of another project, PostHog ingests your events into that project. If your requests succeed but your project stays empty, compare the token in your [initialization code](/docs/product-analytics/installation) with the token in the ["Project variables" section of your project settings](https://us.posthog.com/settings/project#variables). + +**3. PostHog is adblocked** PostHog can be adblocked, even locally. This prevents requests from being sent from your app to PostHog. If you're just testing your setup in development, disable your browser ad blocker and make sure you can see PostHog requests succeeding in the network tab of your browser's developer tools. For production, the best way to limit the impact of ad blockers is to [set up a reverse proxy](/docs/advanced/proxy). -**3. An app has been configured incorrectly** +**4. An app has been configured incorrectly** Another common reason for missing events is that an app has been configured to drop certain or all events. To debug if this is the case, follow these steps in order: @@ -86,7 +90,7 @@ Another common reason for missing events is that an app has been configured to d 2. Try to temporarily disable the Filter Out plugin. 3. Try to temporarily disable all other enabled plugins. -**4. There is a bug in the PostHog library** +**5. There is a bug in the PostHog library** Sometimes, bugs in the PostHog library may be the cause of missing events. However, this is quite rare. @@ -101,7 +105,7 @@ If you're using the [JavaScript web](/docs/libraries/js) library, you can identi ![network request being sent to posthog](https://res.cloudinary.com/dmukukwp6/image/upload/v1710055416/posthog.com/contents/images/docs/product-analytics/network-request-to-posthog.png) -**5. Events are not ingested after being received by PostHog** +**6. Events are not ingested after being received by PostHog** If your library is configured correctly and successfully sending events to PostHog, events may get lost in the [ingestion pipeline](/docs/how-posthog-works/ingestion-pipeline) – e.g. if there is an ongoing outage. From 5fc5fa5936aaa1d68844f189e91a9e0ff0964391 Mon Sep 17 00:00:00 2001 From: "posthog[bot]" <206114724+posthog[bot]@users.noreply.github.com> Date: Fri, 11 Sep 2026 12:46:45 +0000 Subject: [PATCH 2/2] docs: use the region-aware app URL for the new project settings links The two project settings links this PR added pointed at us.posthog.com, which forces every reader into the US app. The docs style guide requires https://app.posthog.com/ for in-app links, because that host redirects each user to their own US or EU subdomain, and it gives the us.posthog.com form as an explicit "Don't". This matters more here than in a general link: both new lines ask the reader to compare the token in their code against the token on the linked page. An EU Cloud reader who also holds a US account would land on a US project, read a token that belongs to a different project, and "correct" their code to the wrong token - the exact failure this new cause exists to diagnose. Pre-existing us.posthog.com links elsewhere in these two files are left alone as out of scope. Generated-By: PostHog Desktop Task-Id: ec8c838d-e425-47ec-8bb6-365e6ede1869 --- contents/docs/libraries/shopify.mdx | 2 +- contents/docs/product-analytics/troubleshooting.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/contents/docs/libraries/shopify.mdx b/contents/docs/libraries/shopify.mdx index 96d6055c6c36..0666272c4ac7 100644 --- a/contents/docs/libraries/shopify.mdx +++ b/contents/docs/libraries/shopify.mdx @@ -32,7 +32,7 @@ This guide walks you through integrating PostHog into your Shopify store using a If your session does not appear in the activity tab, check these two causes first: -- **The token is for a different project.** The capture endpoint accepts any valid project token. If you use the token of another project, your requests succeed, but the events go to that project. Compare the token in `theme.liquid` with the token in the ["Project variables" section of your project settings](https://us.posthog.com/settings/project#variables). +- **The token is for a different project.** The capture endpoint accepts any valid project token. If you use the token of another project, your requests succeed, but the events go to that project. Compare the token in `theme.liquid` with the token in the ["Project variables" section of your project settings](https://app.posthog.com/settings/project#variables). - **A third-party app sends the events.** If you use an unofficial Shopify app instead of the snippet, that app controls which events it sends and which token it sends them with. We cannot support these apps. Install the snippet manually with the steps above, then test again. For all other causes, such as ad blockers or a misconfigured library, see [Product analytics troubleshooting](/docs/product-analytics/troubleshooting#why-are-events-not-appearing-in-my-project). diff --git a/contents/docs/product-analytics/troubleshooting.mdx b/contents/docs/product-analytics/troubleshooting.mdx index 3272a45b43df..b6d12bcecaba 100644 --- a/contents/docs/product-analytics/troubleshooting.mdx +++ b/contents/docs/product-analytics/troubleshooting.mdx @@ -74,7 +74,7 @@ If events are visible in webhook.site, it means that you have configured PostHog **2. Your events go to a different project** -The capture endpoint accepts any valid project token and returns a success response. If you use the token of another project, PostHog ingests your events into that project. If your requests succeed but your project stays empty, compare the token in your [initialization code](/docs/product-analytics/installation) with the token in the ["Project variables" section of your project settings](https://us.posthog.com/settings/project#variables). +The capture endpoint accepts any valid project token and returns a success response. If you use the token of another project, PostHog ingests your events into that project. If your requests succeed but your project stays empty, compare the token in your [initialization code](/docs/product-analytics/installation) with the token in the ["Project variables" section of your project settings](https://app.posthog.com/settings/project#variables). **3. PostHog is adblocked**