Campaign Tracking

Campaign Fields

Use exact lowercase URL keys. API requests use the numeric SignalValueType identifiers in the shared Values envelope. Compact keys are parameter-transport representations, not an additional explicit API override.

TCM means CampaignName; TCN means Content. TrackingContext and compact TCX are exclusively internal and have no external mapping. TrackingID is an operation/correlation identifier, distinct from TrackingCampaignID.

Authoring Campaign Links

• For new manually authored campaign links, supply Source, Medium, and CampaignName. Centrally managed campaigns also need a stable CampaignID; document a partner exception when no ID is available. Intelligent TV has its own optional flight and QR rules below.
• Use lowercase, hyphen-separated company-authored labels; preserve exact controlled medium codes, including underscores. Preserve externally assigned identifier case and historical meaning unless an approved mapping exists.
• Keep channel and response mechanism separate: television is the medium; QR scanning is the response mechanism. Do not use Station or Flight as Medium, or an audience segment as Term.
• Supply Content when distinguishing creatives or links. Supply SourcePlatform, CreativeFormat, and MarketingTactic only when known; omit inapplicable fields rather than inventing values.
• Keep secrets, recipient identities, email addresses, phone numbers, MAC addresses, and device IDs out of campaign labels. Provider click IDs remain separate opaque evidence.

https://brand.example/offer/?utm_source=publisher-a&utm_medium=display&utm_campaign=fall-2026&utm_id=campaign-1042&utm_content=banner-v2

These are link-authoring requirements. Ordinary business actions and partial API actions without campaign tags remain valid; missing optional tracking must not stop the action.

Input Resolution and Limits

1. Prefer valid explicit API evidence, then URL evidence, then request-context fallback. Parse the supplied origination URL, or the current page URL when none is supplied, and use that same URL for LandingURL.
2. Decode once using UTF-8. Preserve submitted case and pair order. Within each input, trim outer whitespace, skip missing, blank, or invalid candidates, and take the first valid nonblank duplicate. Differently cased or unknown URL keys are not recognized fields.
3. Where exact compact and UTM keys both occur, valid compact evidence wins within that input. Compact Base64 transport must encode UTF-8 bytes; do not directly apply btoa to arbitrary Unicode.
4. Resolve full campaign identity before truncation. Limit each effective external field to 128 Unicode characters, retaining leading characters without splitting a code point. Apply the same bounded representation before all supported projections. Never use a truncated ID as a new lookup key.
5. Preserve the submitted URL and raw evidence under existing retention controls. Do not rewrite original or signed URLs, or strip arbitrary utm_* parameters as part of resolution.

Keep Campaign ID and Name Together

The highest-priority input containing either campaign member establishes the pair. Use a lookup only in the configured tenant/partner scope; there is no assumed global campaign registry.

Do not borrow a missing ID or name from a lower-priority input unless a scoped lookup confirms the same identity. Matching names alone do not prove matching IDs. If explicit API evidence changes the campaign, omit URL-derived Content, Term, SourcePlatform, CreativeFormat, and MarketingTactic unless their association with the selected campaign is confirmed. Keep explicit API details; Source and Medium can still describe the incoming channel.

Intelligent TV QR Parameters

Only the Intelligent TV landing page translates sr to Source (408), fr to CampaignName (407), and composes CreativeRef/AiringRef into Content (410). Shared SDK/server processing does not interpret these product keys or infer behavior from hostnames or ActionTypes. Source and Flight retain valid short-alias-first, UTM-second precedence.

TrackingContent Composition

Trim and validate each decoded reference independently, using the first valid nonblank duplicate. Reserve ~ as the separator; it is not allowed inside either reference, even when percent-encoded. If one reference is invalid, use the other valid reference, then UTM fallback. Invalid nonblank values qualify for existing once-per-operation adjustment accounting; absent or blank values alone do not.

The composed or singleton candidate precedes utm_content within page evidence. Valid explicit API Content still takes precedence. Keep fallback and invalid evidence for generic conflict accounting. Compose from full valid references before applying the 128-Unicode-character effective field limit. Do not truncate each component first or use a truncated composite as a lookup key.

For example, cr=product-30s-v2&ar=air-847291 produces product-30s-v2~air-847291. Preserve the original supplied cr and ar separately in the immutable landing/handoff snapshot and preserve the unmodified landing URL as LandingURL (419). Never recover originals by splitting effective Content, which may be truncated, a singleton, or UTM fallback. Structured snapshot collection and persistence still require integration verification.

See the approved four-parameter QR URL contract for requiredness, examples, and the distinction between station, flight, creative, and airing.

Silent Adjustments and Internal Accounting

Continue the business action after a tracking adjustment. The target internal mechanism records CampaignTrackingConflict = 222 once per logical operation for qualifying disagreement, conflicting duplicates, invalid nonblank candidates, truncation, campaign mismatch reconciliation, or attempts to set external TrackingContext. Caller-supplied UsageIDs cannot authorize or suppress this internal signal.

Missing or blank optional values, identical duplicates, ordinary trimming/decoding, and ordinary registered-name enrichment do not trigger it by themselves. Do not add per-field warnings, TrackingFindings, external diagnostic payloads, or per-rule UsageIDs. Async processing and retries of the same logical operation must not inflate the count. This count describes affected operations, not field counts, conversion attribution, or downstream delivery.

API Example and Verification

This fragment illustrates tracking signals inside Values; use your provisioned keys and include the other inputs required by your ActionType.

{
  "ActionKeyToken": "<provisioned-action-key>",
  "Values": [
    { "SignalValueType": 406, "DataType": 0, "UnitType": 0, "Value": "campaign-1042", "OptionIDs": {} },
    { "SignalValueType": 407, "DataType": 0, "UnitType": 0, "Value": "fall-2026", "OptionIDs": {} },
    { "SignalValueType": 408, "DataType": 0, "UnitType": 0, "Value": "publisher-a", "OptionIDs": {} },
    { "SignalValueType": 409, "DataType": 0, "UnitType": 0, "Value": "display", "OptionIDs": {} },
    { "SignalValueType": 410, "DataType": 0, "UnitType": 0, "Value": "banner-v2", "OptionIDs": {} }
  ]
}

For equivalent URL and API evidence, verify equivalent effective fields through context, persistence, supported reports, and exports. Test conflicting duplicates, invalid values, Unicode limits, campaign-pair reconciliation, external TrackingContext exclusion, and once-only adjustment accounting. Enum or column presence alone does not prove support.

Related Documentation

• User Action API
• Action Fields
• Intelligent TV
• API Results and Errors