API Reference

Configuration

The CampaignCollector constructor accepts a single configuration object. This object is recursively merged with the default configuration (which can be seen below).

  1{
  2  consent: {
  3    ad_personalization: {
  4      status: null,
  5      redacts: []
  6    },
  7    ad_storage: {
  8      status: null,
  9      redacts: []
 10    },
 11    ad_user_data: {
 12      status: null,
 13      redacts: []
 14    },
 15    analytics_storage: {
 16      status: null,
 17      redacts: []
 18    },
 19  },
 20  debug: false,
 21  crossDomain: {
 22    hostnames: [],
 23    cookies: null,
 24  },
 25  enableSpaSupport: false,
 26  fieldMap: {
 27    anonymous_id: '$ns_anonymous_id',
 28    attribution: '$ns_attribution_json',
 29    consent: '$ns_consent_json',
 30    first: {
 31      utm: null,
 32      $ns: null,
 33    },
 34    last: {
 35      utm: null,
 36      $ns: null,
 37    },
 38    cookies: {},
 39    globals: {},
 40  },
 41  fieldTargetMethod: ['name'],
 42  fieldDataAttribute: 'data-campaign-collector',
 43  fillOnLoad: true,
 44  filters: {},
 45  firstPartyLeadEndpoint: null,
 46  firstPartyCookieEndpoint: null,
 47  namespace: 'lvl',
 48  nullValue: '-',
 49  paramMap: null,
 50  parseRules: {
 51    organic: {
 52      google: '^www\.(google)\.[a-z]{2,3}(?:\.[a-z]{2})?$',
 53      bing: '^www\.(bing)\.com$',
 54      duckduckgo: '^(duckduckgo)\.com$',
 55      yahoo: '^(?:www|m)?\.?(yahoo)\.(?:com|cn)$',
 56      ecosia: '^www\.(ecosia)\.org$',
 57      ask: '^www\.(ask)\.com$',
 58      aol: '^(?:search\.)?(aol)\.com$',
 59      baidu: '^www\.(baidu)\.com$',
 60      xfinity: '^my|search\.(xfinity)\.com',
 61      yandex: '^(?:www\.)?(yandex)\.com|ru$',
 62      lycos: '^(?:www|search)?\.?(lycos).[a-z]{2,3}(?:\.[a-z]{2})?$'
 63    },
 64    ai: {
 65      /**
 66       * Note -- Grok, DeepSeek, and Nova do not pass a referrer as of 2025-05-20
 67       */
 68      chatgpt: '(chatgpt)\.com$',
 69      gemini: '^(gemini)\.google\.com$',
 70      claude: '\.(claude)\.ai$',
 71      perplexity: '\.(perplexity)\.ai$',
 72      mistral: '\.(mistral)\.ai$',
 73      copilot: '^(copilot)\.microsoft\.com$',
 74    },
 75    social: {
 76      facebook: '^www\.(facebook)\.com$',
 77      instagram: '(instagram)\.com$',
 78      linkedin: '^www\.(linkedin)\.com$',
 79      tiktok: '^www\.(tiktok)\.com$',
 80      snapchat: '^www\.(snapchat)\.com$',
 81      x: '^t\.co|x\.com$',
 82      pinterest: '^www\.(pinterest)\.com$',
 83      reddit: '^www\.(reddit)\.com$',
 84      quora: '^www\.(quora)\.com$',
 85    }
 86  },
 87  sdk: null,
 88  sessionTimeout: null,
 89  storageDomain: null,
 90  storageMethod: 'cookie', // anything other than 'cookie' will default to 'local'
 91  storageNamespace: 'cc',
 92  storeAsBase64: true,
 93  stripUtmsFromInternalLinks: false,
 94  userDataHash: {
 95    // Allows for graceful overrides of the default user data hashing behavior.
 96    // However, the following keys will ALWAYS be hashed: first_name, last_name, email, phone, gender, date_of_birth
 97    // The following user location values are sometimes used as reporting dimensions so these are "opt-in", for hashing.
 98    // This setting only matters if you have the tag configured to send data to a 1st party endpoint.
 99    city: false,
100    region: false,
101    postal_code: false,
102    country: false,
103  }
104}

Properties

cookieDomain

Default: null

The domain to set 1st party cookies on. If null, the cookies will be set on the current root domain (detected automatically). If a string, the cookie will be set on the specified domain.

decorateHostnames

Default: []

An array of hostnames to decorate with stored campaign data to support cross-domain navigation and persistence. When set, clicks on links will automatically be decorated.

enableSpaSupport

Default: false

When set to true, the library will monkeyPatch the history.pushState method to ensure that stored campaign data is hydrated to extend the session on SPA navigation.

fieldMap

An object that defines field mappings for each storage group and its individual parameters. This fieldMap object is used for filling data into form inputs, as well as defining what cookies and globals to pull into the stored campaign data when running the fill() or grab() methods.

There are 4 supported storage groups: first, last, cookies, and globals. The first and last groups store the campaign data from URL parameters. These two groups have utm and $ns objects inside them - $ns being a reference to the defined namespace config option.

By default, the library will automatically generate a fieldMap for the first and last storage groups using sensible defaults. last will assume a field selector that exactly matches the parameter name (e.g. utm_source) -- while first will assume a field selector that matches the parameter name with a suffix of _1st (e.g. utm_source_1st).

A few important notes about the fieldMap object:

• Custom fieldMap objects are merged with the default fieldMap object. This means you only need to configure the fields you want to override.
• The structure is storageKey: fieldSelector pairs. Where fieldSelector is a string that will be used to create a CSS selector using whatever means you defined in the fieldTargetMethod configuration option.

Example fieldMap Object:

 1{
 2  "anonymous_id": "my_anon_id",
 3  "attribution": "my_attribution_json",
 4  "consent": "my_consent_json",
 5  "last": {
 6    "utm": {
 7      "source": "utm_source__c",
 8    },
 9    "$ns": {
10      "matchtype": "matchtype__c",
11    }
12  },
13  "cookies": {
14    "_fbp": "meta__fbp",
15    "_fbc": "meta__fbc",
16  },
17  "globals": {
18    "location.href": "conversion_url",
19  }
20}

The above example defines a custom fieldMap for to take the last touch utm_source, and lvl_matchtype and map it to a field with a name attributes of utm_source__c, and matchtype__c. It instructs the library to grab the _fbp and _fbc cookies and map them to fields with name attributes of meta__fbp and meta__fbc respectively. Lastly, the globals object defines values to grab from the window object and map to fields with a name attribute of conversion_url.

anonymous_id, attribution, and consent are special keys that are simple key:value pairs. anonymous_id is a string that represents the key to use for the anonymous ID cookie. attribution and consent are strings that represent the keys to use for the attribution and consent JSON string values sent into separate fields if desired.

fieldTargetMethod

An array of strings that define the method used to target form fields. This allows for flexibility for form field markup variety. Valid values are: name, class, parentClass, and dataAttribute. Default: ['name'].

Example Field Targeting Markup:

 1<!-- "name" -->
 2<input type="hidden" name="">
 3 
 4<!-- "class" -->
 5<input type="hidden" class="">
 6 
 7<!-- "parentClass" -->
 8<div class="">
 9  <input type="hidden">
10</div>
11 
12<!-- "dataAttribute" -->
13<input type="hidden" data-campaign-collector="">

filters

An object that defines filters to apply values for cookies and globals objects. This is useful for transforming data before it is filled into form fields. The object is structured as storageKey: function pairs. The function should accept a single argument (the value to be transformed) and return the transformed value.

Public API

fill()

Use .fill() to manually set form field values from stored campaign data. Accepts an options object with the following properties:

grab()

Use .grab() to retrieve a JSON object of all stored campaign data. Accepts a single options object argument with the following properties:

• without (array) - An array of keys to exclude from the returned object. Allowed values:
  • first - Excludes last/current session data.
  • last - Excludes first/original session data.
  • cookies - Excludes 1st party cookies
  • globals - Excludes global variables
• applyFilters (boolean) - If true, will apply any defined filters to the returned cookies and globals objects. Default: false.
• dereference (boolean) - If true, any _ref properties in the first and last session touchpoints will be expanded. Default: false.
• asJson (boolean) - If true, returned data will be a JSON string and not an object literal.