Custom campaign tracking

Custom campaign tracking lets you add extra details to track events across all your campaign statuses. You can categorize, tag, or add any data you need to make analytics easier. This helps you connect data across different tools and keep everything consistent.

How it works

You define custom attribute names and values that get added to every campaign event from that campaign. This includes everything from enqueued messages to click events. You set this up in your campaign or action node settings.

Most channels that create campaign events support custom campaign tracking:

• SMS
• MMS
• Mobile and push notifications
• Webhooks
• Emails (including transactional emails)

Data type support

Custom attributes only support string and number data types. Lists and other complex data types aren't supported. If you enter a list format into an attribute field, it will be converted to a string value.

📘

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.

Set up custom tracking

You can configure custom campaign tracking on 2 levels:

• Project level: Set default custom campaign tracking through Project settings with various configurations.
• Campaign level: Configure individual campaign settings or action node settings.

Most custom campaign tracking attributes support Jinja, with some limitations.

Project level settings

To access Project Level settings, go to Campaigns > General > General Campaign settings > Custom campaign tracking.

The default custom tracking configuration you set here will automatically fill in when you create new campaigns.

Each custom tracking attribute has the below settings.

Custom attribute name

This is what you'll call your attribute (like "Campaign type"). The system will normalize it in events by making it lowercase, replacing spaces with underscores, and adding a "c_" prefix to avoid conflicts with system attributes. For example, "Campaign type" becomes "c_campaign_type."

Attribute value type

This defines what kind of input field appears in campaign settings:

• Custom values: Creates a text input where you can type any attribute value on the campaign level.
• Predefined values: Creates a dropdown menu with predefined custom values you define in the project settings "Values" field (like "Newsletter," "Welcome series," "Loyalty program," "Sale").

Default value

This prefills the attribute for new campaigns. You can enter any text or choose from predefined values, depending on your attribute value type.

Apply to

Choose which channels should use this default attribute - specific channels or all of them.

Required field

Mark attributes as required if they must be filled in before starting a campaign. You can't change the attribute name once it's marked as required.

Editable

Attributes marked as "not editable" can't be changed at the campaign level - both the name and value are fixed. You must provide a default value for non-editable attributes. Attributes are editable by default.

Campaign level settings

To adjust custom campaign tracking for individual campaigns: go to the Settings tab in your campaign or action node..

The system pre-fills custom tracking settings when you create campaigns based on your current project-level settings. You can add extra custom attributes just for that specific campaign by providing the attribute name and value. Attribute names get normalized the same way (lowercase, underscores, c_ prefix).

For pre-filled attributes from project settings:

• You might be able to edit the attribute name (depends on project settings).
• Fill in values through text input or dropdown menu (depends on configuration).
• Required attributes must have values before you can save the campaign.
• Required attribute names can't be changed after that.
• Non-editable attributes can't be changed at all.

Update from project settings

Changes to project-level settings don't automatically update existing campaigns. They only apply when you create new campaigns, or you can apply them manually using the Update from project settings button.

This update follows these 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 (for example, 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 predefined values, it will update the list of predefined values that 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”.

🚧

Conflict handling

If you create a campaign-level attribute with the same name as a new project-level attribute, the project settings will overwrite the campaign attribute (especially if they're different types).

Use custom tracking in email templates and transactional emails

For email templates, define custom tracking attributes in the template's Settings tab. You need to allow template settings to use custom attributes. Once enabled, you can define custom attributes (or update them from project settings) and custom headers.

Transactional emails support custom campaign tracking in 2 ways:

• Configure them in the email template settings.
• Send them through the API.

If you specify settings in both places, API request settings take priority and override template settings.

Limitations

Data type limitations

• Custom attributes only support string and number data types.
• Lists and other complex data types aren't supported.
• If you enter a list format (like ["value1", "value2"]) into an attribute field, it automatically converts to a string value.

Quantity limitations

• Maximum 20 custom attributes in project settings.
• Maximum 20 custom attributes per campaign in campaign settings.
• Maximum 100 distinct predefined values per custom attribute.
• Maximum 256 or 1,024 customer attributes per event (depends on your contract).

Length limitations

• Attribute values can be up to 1,000 characters (including rendered Jinja). Values that exceed this limit get cut off with "..." added.
• Attribute names can be up to 100 characters.

Other considerations

Adding custom attributes to emails with Jinja personalization can make open and click tracking links longer.

Jinja support

Jinja is supported for most of the campaign event types, but there are some exceptions where Jinja won't 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