Custom Campaign Tracking allows you to add custom event attributes to be tracked in the campaign events for all statuses of the campaigns. It helps you categorize, tag, or add any needed data to your campaign events to do analytics more efficiently, enabling cross-tool data stitching and consistency.

How does it work

You can define custom attribute names and values that will be added to every campaign event generated by that particular campaign from enqueued to click events in the campaign or action node Settings. Custom campaign tracking is supported for most of the channels that generate campaign events, such as SMS, MMS, Mobile and Push Notifications, Webhooks, and Emails (Transactional emails as well).

📘

Mobile push notifications support

The following (or higher) SDKs versions are needed for this feature to work for all mobile push notifications events: Android v2.9.5, iOS v2.11.1, React Native v0.5.2.

Configuration

You can configure custom campaign tracking on two levels:

• On the project level, where the project default custom campaign tracking is done through Project Settings with various configurations,
• On the campaign level where you configure each individual campaign settings or action node settings.

Except for a few cases, Jinja is supported as a value of a custom campaign tracking attribute. See below for limitations.

Project Level Settings

To access Project Level settings, go to Campaigns > General > General Campaign settings > Custom campaign tracking. The configuration of default custom tracking on the project-wide level will be prefilled upon campaign creation in the campaign settings.

The settings available per each custom tracking attribute on the project level are Custom attribute name, Attribute value type, Default value, Apply to, Required field, and Editable.

Custom attribute name
It is the name of the attribute, e.g., "Campaigns type". It will be used in the event in a normalized form (lowercase, underscore instead of space) and with an added prefix c_ to avoid conflicts with the system-defined attributes. For example, the "Campaign type" will be tracked as c_campaign_type.

Attribute value type
It defines the type of field that the attribute will create in the campaign settings. There are two value types, Custom values and Predefined values. Custom value creates a standard text input to define any attribute value on the campaign level. Predefined values create a selected box of the list with the predefined values on the campaign level that you can select from. Those predefined values can be any custom values defined by you in the project setting field Values. Examples of the values are "Newsletter", "Welcome series", "Loyalty program", "Sale," etc.

Here is a visualization of settings for the Attribute value type through the Predefined values on the project level. After saving the setting, those same Attribute values are also available on the campaign level.

Default value
The default value will be used to prefill the attribute for new campaigns in the campaign settings. It is based on the attribute value type, which allows you to input any text value or select one of the predefined values as default.

Apply to
This setting defines which channels should the default attribute be applied to, either for selected specific channels or all of them.

Required field
Attributes marked as required must be filled in on the campaign level in order to start the campaign. The attribute name cannot be changed.

Editable
The name and value of attributes marked as not editable cannot be changed and are fixed on the campaign level. The default value must be provided for attributes marked as not editable. The attributes are marked as editable by default.

Campaign Level Settings

To adjust custom campaign tracking on the campaign level, go to the Settings tab in the campaign or action node.

The custom tracking setting is pre-populated upon campaign creation based on the current project-level settings. You can add additional local custom attributes just for the particular campaign providing the attribute name and value. Attribute names will be normalized, such as lowercase, underscore used instead of space, and c_ prefix.

In the case of the pre-populated attributes based on the project settings, depending on the project settings configuration, you can edit the attribute name and fill in the value either as a text input or select a predefined value from a dropdown menu. Values for attributes marked as required must be provided before saving the campaign, and their attribute name cannot be changed after that. If attributes are marked as not editable, both attribute name and value cannot be changed.

Update from project settings

Changes made to project-level settings are not reflected in already existing campaigns. They are only used when a new campaign is created or can be applied on demand using the Update from project settings button. Using this option will apply the current project-level default attributes to the existing campaign using the following rules:

• Existing attributes are updated and not reset. You should keep the filled-in value if possible.
• Based on the change type of the project setting, the following will happen:
  • If you add new attributes, those attributes will be added to the campaign.
  • If you remove an attribute, the attribute will stay in the campaign settings. However, all previous settings, such as Required or Editable, will be removed.
  • If you change the attribute name, a new attribute will be created.
  • If you change a configuration (e.g., required, editable, apply to…), the new configuration will be applied.
  • If you change the default state of the settings, it will keep the existing value.
  • If you change the type custom/predefined, it will also reset the type and default.
  • If you update the list of the predefined values, it will update the list of predefined values which are offered to be selected from in the settings.
  • If the initially selected value is removed from the list, the select box is set to a default value or “not set”.

🚧

If there is a conflict in the names of attributes, meaning the attribute was defined only on the campaign level and now the same attribute name was defined in the project settings, the global attribute configuration from project settings will overwrite the local campaign attribute, e.g., as it is of a different type.

Custom tracking in Email templates & Transactional emails

Custom tracking attributes in email templates are defined in the Settings tab of the template. This means that in order to use custom attributes, Template settings have to be allowed. Once allowed, you can define your custom attributes (update them from project settings) and custom headers.

Custom campaign tracking is supported for transactional emails in two ways:

• configuring them within the Settings of the used Email Template
• sending them as part of the API

This means you can specify email settings in email templates and also in transactional requests. Possible discrepancies are handled in the following way: Request settings have a higher priority and will override the template settings.

Limitations

• Max. 20 custom attributes defined in project settings
• Max. 20 custom attributes defined per campaign in campaign settings
• Length of the attribute values (per item in a list) is max. 1000 characters, including rendered Jinja. If the limit is exceeded, the value is cut, and ‘...’ are added
• Length of the attribute name is max. 100 characters
• Max. 100 distinct predefined values per one custom attribute
• The overall 256 limit on the attributes per event needs to be kept in mind
• Adding custom attributes to emails with personalization via Jinja can enlarge the links for open and click tracking

Jinja support

Jinja is supported for most of the campaign event types, but there are some exceptions where Jinja will not be rendered due to technical limitations.

Jinja with the following accessors will not be rendered (present in the events) for events of status “suppressed” or ”enqueue_failed” caused by frequency policy, cumulative bounce, and list hygiene filter:

• customer, customer_ids, aggregates, segmentations, expressions, predictions, recommendations, metrics, snippet, reports, report_value_by_key, vouchers