Merge pull request #729 from plausible/utm-explanation

utm

Author: metmarkosaric

docs/guided-tour.md

@@ -84,7 +84,7 @@ See all the acquisition channels and sources of traffic ranked by the number of
 You can use the **Campaigns** tab to view your campaigns separately from other traffic sources. These are visitors coming from UTM tagged links such as those in your emails, social media or in your paid advertising campaigns. Click on **Medium**, **Source**, **Campaign**, **Term** and **Content** to explore these.
 
 :::tip Referral sources are counted per session
-UTM parameters and other referral sources are only recorded when they start a new session. [Read more about how sources are counted](top-referrers.md).
+UTM parameters and other referral sources are only recorded when they start a new session. [Read more about how sources are counted](top-referrers.md). If your UTM link returns a 202 response but nothing appears in the **Campaigns** tab, see [UTM parameters not appearing in Campaigns](troubleshoot-integration.md#utm-parameters-are-in-the-url-but-not-showing-in-the-campaigns-tab).
 :::
 
 [Read more here](top-referrers.md).

docs/top-referrers.md

@@ -59,6 +59,8 @@ With Plausible, there's no need for you to manually exclude unwanted referral so
 
 Referral sources are counted only when they start a new session on your site. This prevents external domains such as payment gateways showing up in the list of sources when for instance visitors briefly leave your site to make a payment before returning back. The source that brought the visitor to your site in the first place will be the one attributed for that conversion.
 
+If you expect UTM attribution but nothing appears in the **Campaigns** tab, see [UTM parameters not appearing in Campaigns](troubleshoot-integration.md#utm-parameters-are-in-the-url-but-not-showing-in-the-campaigns-tab).
+
 ### Consolidation of duplicate sources
 
 UTM tags are case-sensitive, which may lead to duplicated or miscategorized traffic sources all depending on how the different links are tagged. To mitigate this issue, the **Sources** tab consolidates each source into a single entry, disregarding capitalization or naming differences in UTM tags.

docs/troubleshoot-integration.md

@@ -145,6 +145,18 @@ All referral sources are counted only when they start a new session on your site
 
 This same mechanism is what keeps payment gateways and other external domains out of your referral sources. [Learn more about how referral attribution works](top-referrers.md).
 
+## UTM parameters are in the URL but not showing in the Campaigns tab
+
+UTM parameters are only attributed to the first pageview of a new session. If a visitor already has an active session on your site, pageviews with UTM parameters will not update the attribution for that session. A session stays active for 30 minutes after the last pageview.
+
+Common reasons this happens during testing:
+
+- You visited the site earlier in the same browser, even without UTM parameters
+- Another device on the same network visited the site recently, sharing your IP address
+- You tested multiple UTM links without waiting 30 minutes between each
+
+To reliably test UTM attribution, use a network and device combination that has not visited your site in the past 30 minutes. Mobile data on a phone that has not visited the site recently is the most reliable option. Check the **Campaigns** tab after the visit to confirm attribution.
+
 <details>
 
 <summary>