Custom Rules Engine

AttributionHub includes a powerful rules engine that lets you define custom channel classification logic without writing code. Use it to handle business-specific attribution scenarios that the default detection doesn’t cover.

Overview

Custom rules let you override or extend the default channel detection. You define conditions based on URL parameters, referrer, landing page, and other signals, and specify the attribution fields to set when conditions match.

Configuration

Define rules in your settings:


<script>
  window.attrhub = {
    settings: {
      fieldRules: {
        mode: "prepend", // 'prepend' | 'append' | 'replace'
        rules: [
          {
            name: "Internal newsletter",
            enabled: true,
            priority: 10,
            conditions: {
              operator: "AND",
              conditions: [
                {
                  field: "utm_source",
                  operator: "equals",
                  value: "internal_newsletter",
                },
                { field: "utm_medium", operator: "equals", value: "email" },
              ],
            },
            output: {
              channel: "Email",
              source: "Internal Newsletter",
              medium: "email",
              sourcePlatform: "Internal",
              isPaid: false,
            },
            stopProcessing: true,
          },
        ],
      },
    },
  };
</script>

Rule Modes

Mode	Description
`prepend` (default)	Custom rules are evaluated before default detection. If a custom rule matches, it wins. Otherwise, default detection runs as a fallback.
`append`	Default detection runs first. Custom rules can override or enhance the result.
`replace`	Only custom rules are used. Default detection is completely disabled.

Rule Structure

Each rule has the following properties:

Property	Type	Required	Description
`name`	string	Yes	A descriptive name for the rule
`enabled`	boolean	No	Whether the rule is active (default: `true`)
`priority`	number	No	Evaluation order (lower = first). Rules with equal priority are evaluated in array order.
`conditions`	object	Yes	The conditions that must match
`output`	object	Yes	Attribution fields to set when matched
`stopProcessing`	boolean	No	If `true`, stop evaluating further rules after this match

Conditions

Simple Conditions


{ field: 'utm_source', operator: 'equals', value: 'partner_abc' }

Available Operators

Operator	Description	Example
`equals`	Exact match (case-insensitive)	`{ field: 'utm_source', operator: 'equals', value: 'google' }`
`not_equals`	Does not match	`{ field: 'utm_medium', operator: 'not_equals', value: 'organic' }`
`contains`	Contains substring	`{ field: 'utm_campaign', operator: 'contains', value: 'black_friday' }`
`not_contains`	Does not contain	`{ field: 'referrer', operator: 'not_contains', value: 'internal' }`
`starts_with`	Starts with prefix	`{ field: 'utm_medium', operator: 'starts_with', value: 'paid' }`
`ends_with`	Ends with suffix	`{ field: 'utm_medium', operator: 'ends_with', value: '_social' }`
`matches`	Regex match	`{ field: 'utm_campaign', operator: 'matches', value: '^q[1-4]_.*' }`
`in`	Value in list	`{ field: 'utm_source', operator: 'in', value: ['partner_a', 'partner_b'] }`
`not_in`	Value not in list	`{ field: 'utm_source', operator: 'not_in', value: ['internal', 'test'] }`
`exists`	Field has a value	`{ field: 'gclid', operator: 'exists' }`
`not_exists`	Field has no value	`{ field: 'utm_source', operator: 'not_exists' }`
`gt`	Greater than (numeric)	`{ field: 'custom_score', operator: 'gt', value: '50' }`
`lt`	Less than (numeric)	`{ field: 'custom_score', operator: 'lt', value: '100' }`
`between`	Between two values	`{ field: 'custom_score', operator: 'between', value: ['10', '90'] }`

Available Fields for Conditions

utm_source, utm_medium, utm_campaign, utm_content, utm_term
referrer, referrer_domain
landing_url, landing_path
gclid, msclkid, fbclid, ttclid, li_fat_id (and other click IDs)
Any custom field name defined in settings.customFields

Logical Groups

Combine conditions with AND/OR/NOT logic:


// AND -- all conditions must match
{
  operator: 'AND',
  conditions: [
    { field: 'utm_source', operator: 'equals', value: 'partner_abc' },
    { field: 'utm_medium', operator: 'equals', value: 'affiliate' }
  ]
}
 
// OR -- any condition can match
{
  operator: 'OR',
  conditions: [
    { field: 'utm_source', operator: 'equals', value: 'partner_abc' },
    { field: 'utm_source', operator: 'equals', value: 'partner_xyz' }
  ]
}
 
// NOT -- inverts the result
{
  operator: 'NOT',
  conditions: [
    { field: 'utm_source', operator: 'equals', value: 'internal' }
  ]
}

Groups can be nested for complex logic.

Output Fields

When a rule matches, you can set any of these attribution fields:

Field	Description
`channel`	Channel group (e.g., `Paid Search`, `Email`)
`source`	Source name (e.g., `Google`, `Newsletter`)
`medium`	Medium (e.g., `cpc`, `email`, `social`)
`sourcePlatform`	Platform label (e.g., `Google Ads`)
`isPaid`	Whether the traffic is paid (`true`/`false`)
`drillDown1`	Drill-down level 1
`drillDown2`	Drill-down level 2
`drillDown3`	Drill-down level 3
`customFields`	Object with custom field overrides

Example Rules

Classify internal traffic


{
  name: 'Internal traffic',
  priority: 1,
  conditions: {
    operator: 'OR',
    conditions: [
      { field: 'utm_source', operator: 'equals', value: 'internal' },
      { field: 'utm_medium', operator: 'equals', value: 'internal' },
      { field: 'referrer_domain', operator: 'contains', value: 'staging.yoursite.com' }
    ]
  },
  output: {
    channel: 'Internal',
    source: 'Internal',
    medium: 'internal',
    isPaid: false
  },
  stopProcessing: true
}

Custom partner attribution


{
  name: 'Strategic partner',
  priority: 5,
  conditions: {
    operator: 'AND',
    conditions: [
      { field: 'utm_source', operator: 'in', value: ['partner_acme', 'partner_globex'] },
      { field: 'utm_medium', operator: 'equals', value: 'partnership' }
    ]
  },
  output: {
    channel: 'Affiliate',
    source: 'Strategic Partner',
    sourcePlatform: 'Partner Program',
    isPaid: false,
    drillDown1: 'Partner Program'
  }
}

Influencer campaign tracking


{
  name: 'Influencer campaigns',
  priority: 10,
  conditions: {
    field: 'utm_medium', operator: 'contains', value: 'influencer'
  },
  output: {
    channel: 'Paid Social',
    medium: 'influencer',
    sourcePlatform: 'Influencer',
    isPaid: true
  }
}