Setup Guide

Campaign Collector (in most situations) does not require intricate configuration. It can be configured by a few people in an organization depending on their roles/responsibilities and what systems they manage. This guide tackles setup/configuration responsibilities by organizational role.

Marketing Operations

Everything starts here, without a place to "store" the data, every other part of the setup is a futile activity.

The primary setup role of CRM/Marketing Operations is creating the various fields and defining the object mapping(s) inside the any applicable systems.

Ultimately, the "goal" is to ensure that any campaign metadata for a captured lead is carried through its lifecycle to enable down-funnel reporting requirements.

The fields to store this campaign metadata should be created inside every applicable "object" and mapped accordingly. The most typical example of this is Salesforce's default "Lead" and "Opportunity" objects. When a Lead is converted into an Opportunity - it should "copy" the above data into the new record.

Field Types & Lengths

Bare minimum every implementation should contain fields for the following campaign/attribution data.

It is important to note that the underlying field names/keys do not matter - but the field type/length does matter.

Field (Default Key)	Type (Length)
`utm_source`	Text (255)
`utm_medium`	Text (255)
`utm_campaign`	Text (255)
`utm_term`	Text (255)
`utm_content`	Text (255)
`gclid`	Text (255)
`wbraid`	Text (255)
`gbraid`	Text (255)
`cc_anonymous_id`	Text (255)
`cc_attribution_json`	Long-Text (4k+)
`cc_consent_json`	Long-Text (4k+)

Web/App Developers

Script Configuration

In most cases, a web developer will not be needed to implement the script into the website(s). This can easily be done by non-developers using our Google Tag Manager (GTM) template which requires no working knowledge of Javascript to configure.

However, there may be circumstances where GTM is either not an option, or greater control is needed by a developer. In these situations, please reference both the Installation Options, and API Reference.

Form Integration

Once CRM fields are in place to store the necessary data, a web developer may be needed to append the data to the lead form submission(s).

There are two ways to approach this:

Hidden Fields

This is the most common method, and typically the "easiest". By appending hidden fields, the Campaign Collector library can "fill" they automatically with the data from storage.

In order to use this method, the hidden <input> nodes need to have some consistent HTML attributes (form-to-form, and page-to-page). The most common/semantic way is to use the fields native name attribute:

1<input type="hidden" name="utm_source">

However, every website is different. As such, a web developer may need to implement the fields with different attributes due to underlying technology barriers or constraints. Campaign Collector can work with almost any hidden field markup.

 1<!-- Using a specific "name" attribute -->
 2<input type="hidden" name="utm_source">
 3<!-- Using a specific "class" attribute -->
 4<input type="hidden" class="utm_source">
 5<!-- Using a custom "data" attribute -->
 6<input type="hidden" data-field-key="utm_source">
 7<!-- Using a parent "class" attribute -->
 8<div class="utm_source">
 9  <input type="hidden">
10</div>

Using the `.grab()` API

Some situations may dictate directly accessing the stored metadata to ingrate properly. The Campaign Collector library offers a convenient .grab() method that will return any applicable session/cookie/global data as either a javascript object - or as a JSON string.

See our API reference on how to utilize this method.

Iframes

Ideally, forms are directly accessible in the existing frame, and are not implemented via <iframe> elements. This kind of behavior is more common with 3rd party form providers such as Pardot, and HubSpot.

Iframes introduce a lot of complexity due to cross-origin restrictions in the browser. You should do everything in your power to avoid embedding forms via an <iframe> (especially ones hosted on different root domains).

The Campaign Collector library cannot access DOM elements inside of an <iframe> to properly fill the hidden field values. If an <iframe> is being used, it may require special or custom configuration to ensure that the fields inside the frame are filled appropriately. This is typically done via native APIs provided by the form provider (e.g. HubSpot), and will require a developer to manually access the stored campaign data and pass it into the <iframe> as documented by the provider.

Media Managers

The library works best whenever paid Media managers take advantage of each advertising platforms various campaign variables that can be appended to a destination/click URL. These are often referred to as "Value Track" parameters (Google flavor) or "URL Macros".

These parameters can be easily added/collected via the use of custom lvl_* parameters appended to a typical campaign tracking template query string containing normal utm_* conventions.

It is suggested to use our Tracking Template Generator Tool to easily & properly configure your tracking templates. This tool will automatically map known advertising platform template macros to their appropriate lvl_* parameters.

Why `lvl_` and not `utm_`?

It's not advised to use the utm_ prefix for custom campaign variables. Using a custom namespace/prefix allows the end advertiser to ensure that:

The custom parameters do not collide with assumptions made by other vendors or systems using the utm_* namespace.
Allows for easy URL cleaning (if needed) by removing any lvl_* parameters from a url to reduce the overall unique values (cardinality) of a given page url dimension.