---
name: set-up-custom-variables
description: >-
  Adds business-specific dimensions (lead score, service type, plan tier, booking details) to Google
  Ads conversions via conversion custom variables, so campaign reports can be segmented by the
  dimensions that actually matter to the business instead of only campaign/device/geo. Use it when a
  client asks "which campaigns bring high-score leads" or similar quality questions the standard
  segments cannot answer. Implementation rides on gtag parameters or offline-upload columns, GTM's
  conversion tag cannot carry them, so the tagging edit is human; VigilDog verifies registration and
  value distribution and can carry the variables on offline uploads. Not for correcting values after
  the fact (configure-conversion-adjustments), not for the base tag
  (set-up-google-ads-conversion-tracking), and not for importing CRM outcomes as separate
  conversions (set-up-offline-conversion-tracking).
---
# Conversion Custom Variables Setup

## Purpose
Attach business dimensions to each conversion, lead score, deal band, product line, booking type, so conversion reports can be sliced by conversion quality, not just by Google's built-in segments.
The variables are reporting-only: they do not feed Smart Bidding directly, but they tell you where
quality is coming from so you can adjust structure and targets deliberately.

## When to run
- Standard segments cannot answer the question the stakeholder is asking (e.g. "which keywords
  drive enterprise-size deals?").
- Lead quality varies and the account needs a quality lens on top of conversion counts.
- The account already imports offline conversions and wants richer columns on those uploads.
- A vertical has natural business dimensions (property name, plan tier, service line) worth
  reporting on.

## When NOT to run
- No conversion action exists yet, set-up-google-ads-conversion-tracking first.
- You want to change a conversion's value or retract it after the fact, that is
  configure-conversion-adjustments (custom variable values can never be edited retroactively).
- You want downstream funnel stages as their own conversions with values, that is
  set-up-offline-conversion-tracking, not a segmentation variable.
- The goal is bidding optimization: custom variables do not influence Smart Bidding; consider
  set-up-value-based-bidding if value signals should drive bids.

## Prerequisites
- Active conversion action(s) in Google Ads.
- Either gtag on the conversion pages (with developer access) or an existing offline-upload
  pipeline that VigilDog can extend.
- A backend/CRM source for each dimension's value at conversion time.
- Awareness of the platform cap: only a handful of custom variables (five) can be active per
  conversion action, so dimensions must be prioritized.

## Procedure
1. Design the variable set with the user. Pick at most five dimensions that would actually change
   a bidding or structure decision if visible in reports; drop vanity dimensions. For each: a
   lowercase, underscore-separated name, the expected value set, and the source system. Prefer a
   small enumerated value space (e.g. tiers) over free text, high-cardinality values make reports
   unreadable.
2. Check what already exists. Run `gads_run_gaql_query` on the conversion custom variable resource
   to list variables already registered in the account (name, id, status). Reconcile with the plan
   so you do not burn slots on duplicates.
3. HUMAN STEP (outside VigilDog): register each planned variable in the Google Ads UI (Conversions >
   Custom Variables), there is no VigilDog tool for creating them. The registered name must match
   the parameter name that will be sent, minus the prefix.
4. Choose the transport:
   - Web path, HUMAN STEP (outside VigilDog): the developer adds prefixed custom parameters (the
     `cv.`-style parameters) to the gtag conversion event, populated dynamically at render time.
     Every value must be sent as a string; when a value is unknown for a given conversion, the
     parameter must be omitted entirely, never sent as an empty string. Note this cannot be done
     through GTM's Google Ads conversion tag.
   - Offline path, when the account uploads conversions through VigilDog, include the custom
     variable columns on `gads_upload_click_conversions` calls. As with any write: preview first
     (validate_only=true default), show the user the rows and variable payload, commit only after
     explicit approval. Consult `gads_policy_guardrail` before the session's first Google Ads
     write.
5. HUMAN STEP (outside VigilDog) for the web path: verify in the browser network panel that a test
   conversion request carries the custom parameters.
6. After 24-48 hours, validate with `gads_run_gaql_query`: segment conversions by each custom
   variable and inspect the value distribution. Healthy = multiple distinct values in plausible
   proportions. Suspicious = everything under a single value or everything unset.
7. Cross-check a 7-day sample against backend records (user supplies the backend export): the
   distribution of, say, lead-score bands in Google Ads should roughly match the CRM's
   distribution for the same period. Report discrepancies with the specific variable named.
8. Publish a short usage note to the user: which reports now support the new segments and which
   two or three questions they can now answer.

## Decision rules
- All conversions reporting an unset value → parameters are not arriving; if web path, back to
  step 5; if offline path, check the column naming on the upload.
- Name mismatch between registered variable and sent parameter (including case) is the #1 cause of
  unset values, verify by exact string comparison, never by eye.
- More than five candidate dimensions → force-rank by "would this change a decision?"; retire an
  existing variable before adding a new one.
- Numeric dimensions (scores, rates) → bucket them into named bands before sending; raw numerics
  sent as strings segment poorly.
- Values must be strings; a developer sending raw numbers or booleans will produce inconsistent
  segmentation.
- Custom variables cannot be backfilled: data exists only from the moment the parameters start
  flowing. Set that expectation with the user up front.

## Common failure modes
- Empty strings sent for missing values, flooding reports with a meaningless blank segment, omit
  the parameter instead.
- Registering the variable but never shipping the tag edit (or vice versa); always verify both
  halves before waiting on data.
- Free-text values (raw hotel names with typos, arbitrary campaign notes) creating hundreds of
  one-row segments.
- Expecting Smart Bidding changes from this work, the variables are reporting-only, and the user
  should hear that before they invest.
- Using a custom variable where a conversion adjustment was needed: quality discovered after the
  conversion belongs in configure-conversion-adjustments.
- Two teams sending different value vocabularies for the same variable (web sends "ENT", offline
  uploads send "enterprise"), splitting one segment into two, publish the value dictionary to
  every producer.
- Registering a variable, seeing no data for a day, and re-registering under a new name, burning scarce slots on duplicates; wait the full 48 hours and verify the parameter path
  instead.
- Reporting built on a variable that only one conversion action sends, then generalized to the
  whole account, always note which actions carry which variables in the usage note (step 8).

## Related skills
- Run before: set-up-google-ads-conversion-tracking, implement-transaction-id-deduplication.
- Run after: set-up-offline-conversion-tracking (carry variables on imports),
  configure-conversion-adjustments (value corrections), run-a-monthly-performance-review (use the
  new segments in the tracking-health phase).