diff --git a/docs/pipeline/enrichments/available-enrichments/referrer-parser-enrichment/index.md b/docs/pipeline/enrichments/available-enrichments/referrer-parser-enrichment/index.md index 4e1b5c327..e951b1bbc 100644 --- a/docs/pipeline/enrichments/available-enrichments/referrer-parser-enrichment/index.md +++ b/docs/pipeline/enrichments/available-enrichments/referrer-parser-enrichment/index.md @@ -2,17 +2,20 @@ title: "Referrer parser enrichment" sidebar_position: 3 sidebar_label: Referrer parser -description: "Extract attribution data from referrer URLs to identify traffic sources, search terms, and marketing channels." -keywords: ["referrer parser", "traffic source", "attribution", "referer"] +description: "Extract attribution data from referrer URLs and utm_source parameters to identify traffic sources, search terms, and marketing channels." +keywords: ["referrer parser", "traffic source", "attribution", "referer", "utm_source", "chatbot"] --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import SchemaProperties from "@site/docs/reusable/schema-properties/_index.md" This enrichment uses the [Snowplow referer-parser](https://github.com/snowplow/referer-parser) library to extract attribution data from referrer URLs. This is particularly useful when looking for traffic from specific search engine providers or social networks. +Since version 6.13.0 of Enrich, it also classifies traffic sources that identify themselves through a [`utm_source` query parameter](#identifying-referrers-from-utm_source) rather than (or in addition to) a `Referer` header. An example would be ChatGPT setting `utm_source=chatgpt.com`. + ## Configuration The enrichment takes these parameters: @@ -48,6 +51,12 @@ Configure the parameters in the Console enrichment editor. Keep the Console defa "Social website": { "domains": ["social.acme.com"] } + }, + "chatbot": { + "Acme Assistant": { + "domains": ["assistant.acme.com"], + "utm_sources": ["assistant.acme.com"] + } } } } @@ -60,7 +69,7 @@ For Self-Hosted, [provide a complete JSON](/docs/pipeline/enrichments/managing-e ```json { - "schema": "iglu:com.snowplowanalytics.snowplow/referer_parser/jsonschema/2-0-1", + "schema": "iglu:com.snowplowanalytics.snowplow/referer_parser/jsonschema/2-0-2", "data": { "name": "referer_parser", "vendor": "com.snowplowanalytics.snowplow", @@ -83,6 +92,12 @@ For Self-Hosted, [provide a complete JSON](/docs/pipeline/enrichments/managing-e "Social website": { "domains": ["social.acme.com"] } + }, + "chatbot": { + "Acme Assistant": { + "domains": ["assistant.acme.com"], + "utm_sources": ["assistant.acme.com"] + } } } } @@ -90,6 +105,12 @@ For Self-Hosted, [provide a complete JSON](/docs/pipeline/enrichments/managing-e } ``` +:::note + +The `utm_sources` field requires configuration schema version `2-0-2`, available since version 6.13.0 of Enrich. Earlier schema versions (`2-0-0`, `2-0-1`) remain valid, but reject `utm_sources`. + +::: + @@ -143,7 +164,8 @@ The `referrers` parameter is a nested object structured like this: "": { "": { "domains": ["", ""], - "parameters": [""] + "parameters": [""], + "utm_sources": [""] } } } @@ -155,6 +177,7 @@ The `referrers` parameter is a nested object structured like this: | `` | A human-readable name for the source e.g., `"Google"`, `"Internal Search"`. This value populates `refr_source`. | | `domains` | An array of hostnames to match against the referrer URL. At least one domain is required. | | `parameters` | An optional array of URL query parameter names to extract search terms from. Matched values populate `refr_term`. | +| `utm_sources` | An optional array of `utm_source` values identifying this source. See [Identifying referrers from `utm_source`](#identifying-referrers-from-utm_source). Available since version 6.13.0 of Enrich. | For example, to classify a custom search engine and a social network: @@ -188,6 +211,48 @@ You can use custom referrer mappings to immediately test new categorizations in ::: +## Identifying referrers from `utm_source` + +:::note[Availability] +This feature is available since version 6.13.0 of Enrich. +::: + +The `Referer` header is not set when users share or copy and paste the link, rather than click it directly. To circumvent this limitation and make attribution more reliable, some sites also append a `utm_source` query parameter. For example: + +``` +https://www.example.com/product?utm_source=chatgpt.com +``` + +Note that an event might contain both a `Referer` header value *and* a `utm_source` value. These values might not match. For example, if person A shared the above link with person B via Instagram messages, and person B clicked the link, `Referer` would be `instagram.com`. In these cases, you should rely on the `utm_source` value for first-touch attribution. + +The hosted database includes `utm_sources` entries for the major chatbot providers — ChatGPT, Claude.ai, Google Gemini, Microsoft Copilot, META.ai, Mistral.ai, Perplexity.ai, Character.AI and Poe — so this works out of the box, as long as you use the actively-maintained database file (`referers-5.3`). You can recognize additional sources by adding `utm_sources` to your [custom referrer mappings](#custom-referrer-mappings). + +### Output entity + +On a match, the enrichment attaches a `utm_referrer` entity to `derived_contexts`. + + + +Currently, the `term` field is always absent for `utm_source` matches, as there's no referrer URL to extract a search term from. + +### How it relates to referrer URL parsing + +The `utm_source` classification is deliberately kept separate from the `Referer` header parsing described above: + +* It **doesn't populate** `refr_medium`, `refr_source`, or `refr_term`. Those fields continue to reflect the referrer URL only, so existing data models and queries are unaffected. +* It's **additive**. If an event has both a recognized referrer URL and a recognized `utm_source`, you get the `refr_*` fields *and* the `utm_referrer` entity. +* It's **independent of the [campaign attribution enrichment](/docs/pipeline/enrichments/available-enrichments/campaign-attribution-enrichment/index.md)**, which copies `utm_source` into `mkt_source` verbatim. The referrer parser instead resolves the value to a known source and medium. Both can run on the same event. + +Matching is an exact, case-sensitive comparison of the full `utm_source` value against the `utm_sources` entries, and only the page URL's query string is inspected. Values from your own `referrers` configuration take precedence over the database. + ## Output This enrichment populates the `refr_medium`, `refr_source`, and `refr_term` [atomic event fields](/docs/fundamentals/canonical-event/index.md#page-fields). + +Since version 6.13.0 of Enrich, it can additionally attach a [`utm_referrer` entity](#output-entity) to `derived_contexts`. diff --git a/src/componentVersions.js b/src/componentVersions.js index abdc53917..7de8b4bc8 100644 --- a/src/componentVersions.js +++ b/src/componentVersions.js @@ -22,7 +22,7 @@ export const versions = { // Core pipeline collector: '3.7.0', - enrich: '6.12.0', + enrich: '6.13.0', sqs2kinesis: '1.0.4', dataflowRunner: '0.7.8', snowbridge: '5.2.0',