Cookie extractor enrichment

This enrichment extracts name-value pairs from cookies set on the Collector domain, attaching them to the event as derived entities. It uses the Cookie HTTP header.

When using a custom Collector domain, it's possible to capture values in first-party cookies set by other services such as ad servers or content management software (CMS). By capturing these cookie fields and attaching them to the event, you can use the data to better identify users of your website.

This table shows how the cookie and Collector domains interact, indicating whether or not the cookies can be accessed with this enrichment.

Collector domain	Cookie domain	Cookies extracted
c.snowplow.io	acme.com	❌
t.acme.com	c.acme.com	❌
t.acme.com	acme.com	✅
sp.track.acme.com	acme.com	✅

Configuration

The enrichment takes one parameter:

Parameter	Required	Description
cookies	✅	List of cookie keys for which to extract the value.

Console

Configure the parameters in the Console enrichment editor. For example:

json

{
  "cookies": ["sp"]
}

Self-Hosted

For Self-Hosted, provide a complete JSON. For example:

json

{
  "schema": "iglu:com.snowplowanalytics.snowplow/cookie_extractor_config/jsonschema/1-0-0",
  "data": {
    "name": "cookie_extractor_config",
    "vendor": "com.snowplowanalytics.snowplow",
    "enabled": true,
    "parameters": {
      "cookies": ["sp"]
    }
  }
}

The example configuration captures the Collector's own sp cookie value. In practice, you would probably want to extract other more valuable cookies available on the company domain.

Testing with Micro

Unsure if your enrichment configuration is correct or works as expected? You can easily test it using Snowplow Micro, either through Console or on your machine.

To test first-party cookies, you'll need to run Micro locally and configure a custom DNS resolution rule.

Output

For each key listed in the configuration, an http_cookie entity is added to the enriched event. Each entity contains only one key/value pair.

http_cookie

Entity

Schema for a single HTTP cookie, as defined in RFC 6265

Schema URIiglu:org.ietf/http_cookie/jsonschema/1-0-0

Example data

json

{
  "name": "sp",
  "value": "5e684087-4ccd-450c-9057-ac06e8a58078"
}

Properties and schema

Table

Property	Description
name string	Required.
value string	Required.

Complete JSON schema

json

{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "description": "Schema for a single HTTP cookie, as defined in RFC 6265",
  "self": {
    "vendor": "org.ietf",
    "name": "http_cookie",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 4096
    },
    "value": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 4096
    }
  },
  "required": [
    "name",
    "value"
  ],
  "additionalProperties": false
}