Register the custom parameters your ad tags send

Ad tags carry custom parameters — cp.genre=rock, cp.section=sport — that targeting rules read and macros pass on (see Target on custom parameters). Admin → Targeting presets → Custom parameters is where the network writes down which parameters its tags send and what they carry: a name and a human label, so a targeting editor picks genre · Content genre from a list instead of typing a name that may be misspelt; the values it may take, when they are a known set; whether one request carries several values and what separates them; and whether it is recorded in analytics. Registering a parameter never stops a tag from sending anything: an unregistered cp. parameter still reaches targeting and macros exactly as before, and reaches reports unless you choose otherwise under What reaches analytics.

Example. Sports Daily’s pages send cp.genre=1,3,5 — every section the article belongs to, numbered 1 to 5. Until genre is registered, a campaign rule genre is one of 3 compares the whole value 1,3,5 with 3 and never matches. Register genre with The request can carry several values and the Comma separator, and within a minute the same rule matches on any page whose list holds 3, with no rule re-saved. Give the five numbers labels (3=Football) and the targeting editor offers Football to pick instead of a bare 3.

Typical scenarios

You want	Register	Result
Rules on section picked from a list, not typed	section, Label Site section, Values From a list: sport, news, finance	The targeting editor offers the three values; a typo such as sprot can no longer be saved from the list
Match one of several values a page sends (cp.genre=1,3,5)	genre with The request can carry several values, Separator Comma	genre is one of 3 matches 1,3,5; genre has all of 1, 3 needs both
A loyalty tier with a closed set and a report on the rest	loyalty, From a list gold, silver, bronze, Accept values that are not in the list off, Record in analytics on	Anything else the tag sends reports as Other (not in list)
A cache buster out of the logs	cb with Record in analytics off	Targeting and macros still read it; the analytics and conversion parameter logs leave it out
Only the parameters you know of in reports	Unregistered parameters = Not recorded	Only registered parameters with Record in analytics on are logged; a stray utm_x nobody registered is not

Step by step

1. Open Admin → Targeting presets → Custom parameters. The list shows every registered parameter; a note above it names parameters that targeting rules read but nobody registered, each with a Register link.

   

2. Click Add and type the Name — the part after cp.. The line under the field shows what the tag sends, Sent as cp.genre= in the ad tag. Optionally give it a Label (what pickers show next to the name) and a Description (where the value comes from and who sends it).

3. Under Values, keep Any value, or choose From a list and list the values the tags send — Add value one at a time, or Paste many… one per line as value or value=label. Switch off Accept values that are not in the list when the list is complete.

   

4. If one request can carry several values, switch on The request can carry several values and pick the Separator: Comma, Pipe, Semicolon or Space. Type a sample into Try a value to see how it splits — on Comma, rock, pop,,jazz reads as three values (the example in the box uses the separator you picked), and an item that is not in a fixed list is marked Not in the list.

5. Under Analytics, keep Record in analytics on to filter and group by the parameter in the Advanced report, or switch it off for one that only bloats the logs, such as a cache buster.

   

6. Click Save. Ad serving reads the change within a minute. When editing, Used by under the form lists every targeting rule that reads the parameter.

7. Back on the list, decide what happens to parameters nobody registered with Unregistered parameters above it — Recorded (the default) or Not recorded; switching to Not recorded asks first and says how many parameters stay recorded. See What reaches analytics.

   

Caveats and exceptions

• Who can do this. Network administrators whose role has the Custom Parameters admin permission. It is granted with the release to every role and user that already had Analytics Configuration. Everyone signed in can read the list — the targeting editor needs it — but only this permission changes it, and only this permission shows the targeting rules that read a parameter (they name other clients’ campaigns, sites and targeting values) and its Description, which is the admins’ own note.
• Ad serving never asks the database. Each server keeps the registered parameters in memory and reloads them every minute; the server you saved on reloads at once. A server that starts while the database is unreachable uses the copy it saved on disk.
• A rule is never changed by a change here. The separator is read when a request is matched, so turning the list on or off — or deleting the parameter — changes how existing One of rules match from the next minute, without anyone re-saving them. A value without the separator is a one-item list, so only requests whose value holds the separator can be affected. Deleting a list parameter does not touch the rules that read it either: from the next minute they compare the request value whole again, which is how they matched before the parameter was registered.
• Only One of and the Advanced report’s filter split. Value, Substring and Expression rules and the $$CUSTOM_PARAM()$$ macro keep the whole value. The Advanced report’s custom-parameter filter, on a parameter registered as a list, counts a request when any item is a filtered value: 18+ finds news,18+ (recorded as ~other,18+ under a closed list), and so does Other (not in list). Grouping by Custom parameter still shows the whole recorded value.
• Where a value list shows up. In the targeting editor, a One of rule on a listed parameter picks its values from the list (labels first, values after them), a Value rule with equals or not equals picks one. Picked values are stored so ad serving reads back exactly the value picked: a comma or backslash inside a value is escaped and a % or + is URL-encoded for you (see How the Value list is split). In the Advanced report’s custom-parameter filter, the parameter name suggests the registered names and the values field offers the listed values. A Substring rule and the numeric Value operators keep a free text box.
• Built-in parameters. Fourteen parameters are built in on every network: sub1 … sub10, the pass-through slots an affiliate integration sends without a cp. prefix, and contentGenre, contentRating, contentLanguage and contentLivestream, which a CTV stitcher fills. They start as single, any-value parameters — exactly how they were read before — and you can label them, list their values or mark them as lists, but not rename or delete them.
• A rule value that holds the separator never matches. A One of rule whose value itself holds the separator — rock\,pop with an escaped comma — can never equal a single item of a comma-split value. Used by marks such a rule never matches, and the editor warns about it, so you can split the value into separate entries or pick another separator.
• Names that are refused. u, which the ad server overwrites with the raw query string, and cps, which carries all custom parameters packed into one value, are refused outright. A name starting with cp. or cp_ is refused too — leave the prefix out — and so is a name of digits alone, such as 7: the API reads digits as a parameter’s id, so it could never be found by name.
• Renaming does not rename the rules. They keep reading the old name, which is then no longer registered, so its settings — the separator — stop applying to them. When rules read the parameter, Save asks first and says how many; a change of case only (genre → Genre) is not a rename and does not ask.
• Switching a listed parameter back to Any value deletes its list when you save, so Save asks first (Delete the value list?). Targeting rules keep the values they picked.
• A parameter sent without the cp. prefix (a bare genre=, or the content parameters a stitcher fills) reaches targeting but was never written to the custom-parameter logs, so Record in analytics cannot add it there.

What reaches analytics

Above the list, Unregistered parameters decides what happens to a cp. parameter nobody registered:

Setting	Recorded in the analytics and conversion parameter logs
Recorded (the default)	every custom parameter, except registered ones with Record in analytics off
Not recorded	only registered parameters with Record in analytics on

Switching to Not recorded asks first and says how many parameters stay recorded. Either way, targeting, macros and click or conversion forwarding read every parameter the tag sent — this only decides what is written down. Logs follow within a minute, and rows already written are not changed.

Moving from the Analytics configuration list

Until this release, Admin → Audience & analytics → Analytics configuration decided which custom parameters the analytics log kept, with an include or exclude list that only took effect where log filtering was switched on for the network. The release moves that decision here without changing what any network records:

The Analytics configuration list	What happens	Recorded afterwards
Empty — no custom-parameter row at all	Moved by itself within a minute; Unregistered parameters is Recorded.	everything, as before
Include only these patterns, filtering on	Waits. The page says how many parameters the list keeps and offers Move it here.	until moved: the list; after: exactly the listed names (Not recorded for the rest)
Exclude these patterns, filtering on	Waits, as above.	until moved: the list; after: everything except the listed names
Any patterns, filtering off on the server that shows the page	Waits too. The page says the filter is off on this server and offers Move it here, which keeps every parameter recorded.	until moved: the list, wherever filtering is on; after: everything

Log filtering is switched on or off per server, so a list with patterns never moves by itself: the server showing the page may have filtering off while the ad servers have it on. Check how filtering is set on your ad servers before you move a list that the page says is off — the move records every parameter on all of them.

Until it is moved, Record in analytics cannot be switched on this page, and the editor says so: the move sets it for every parameter from the list. Moving is the one change that is not neutral: from then on the conversion parameter log follows the same settings, which the old list never filtered — the confirmation says so. The move cannot be undone from the console. Afterwards the Analytics configuration page keeps its custom-parameter patterns but no longer applies or lists them: in place of the custom-parameter filtering it shows a note that links here, and it no longer offers Custom parameter as the type of a row. Its cookie-name list works as before.

• The page address, u. u is not a custom parameter, so Unregistered parameters never drops it. The old list did filter it, though, and moving the list keeps that: an Include only list that does not name u, or an Exclude list that does, leaves a parameter u on this page with Record in analytics off, and the page address stays out of the analytics log. Switch it on to record the page address again.

Not working?

Symptom	Likely cause	Check
The page is missing from the admin sidebar, or the URL shows Record not found.	Your admin role lacks the Custom Parameters permission	Users and roles; it came with Analytics Configuration at the release
genre is one of 3 does not match cp.genre=1,3,5	The parameter is not registered as a list, or on another separator than the tag uses	Editor → The request can carry several values, Separator; Try a value with the exact value the tag sends
The change seems to have no effect	Ad serving reloads once a minute	Wait a minute; the server you saved on reloads at once
has all of is missing from a rule’s operator list	The parameter is not a list parameter	Switch on The request can carry several values
A rule is marked never matches in Used by	Its value holds the separator (rock\,pop on Comma)	Split it into separate entries, or pick another separator
The name is refused	u, cps, a cp. / cp_ prefix, digits only, or a character outside letters, digits, _, ., -; or the name is taken (case does not matter)	The message under Name says which
A rule stopped matching after a rename	Rules keep reading the old name, which is no longer registered	Re-save the rules with the new name, or register the old name again
The Advanced report has no parameter to filter or group by	Record in analytics is off, or Unregistered parameters is Not recorded and the parameter is not registered; or the tag sends it without cp.	Editor → Analytics; the list’s Analytics column
Record in analytics is locked	The Analytics configuration list still decides	Click Move it here above the list (Moving from the Analytics configuration list)
The list says the filter is off on this server	Log filtering is per server; the ad servers may still filter	Check filtering on the ad servers before Move it here
The page address vanished from the analytics log after the move	The old list filtered u; the move kept that	Switch Record in analytics on for u
A value shows as Other (not in list) in reports	The list is closed (Accept values that are not in the list off) and the tag sent something else	Add the value to the list, or accept others

Reference

The list

Column	What it shows
Name	The parameter’s name, with a Built-in badge on a parameter shipped with the platform.
Label	The label pickers show beside the name.
Values	Any value, or N listed — with others accepted when values outside the list are allowed.
Analytics	Recorded or Not recorded — whether the analytics log keeps the parameter now. Once the registry decides, that is the parameter’s Record in analytics. While the Analytics configuration list still decides (Moving from the Analytics configuration list), the list does, and Not recorded says why: Not on the Analytics configuration list (an Include only list without the name) or Dropped by the Analytics configuration list (an Exclude list with it).
Several values	split on , (or `
Targeting rules	How many Custom Parameter targeting rules on live advertisers, campaigns, banners, sites, zones and placements read the parameter — One of, Value and Substring rules by their Parameter, Expression rules by every $name they mention.
Updated	When the parameter was last changed.

Select rows to Delete them; deleting asks first and says how many rules read the parameter. The search box matches the name or the label. When targeting rules read parameters nobody registered, a note above the list names each with the number of rules reading it and a Register link that opens a new parameter with the name filled in — the quickest way to catch a misspelt rule.

The editor

Field	What it does
Name	Required. Letters, digits, _, . and -, up to 128 characters, without the cp. / cp_ prefix, and not digits alone. Names are unique ignoring case — Genre and genre are one parameter, as they are on the request. A built-in parameter keeps its name.
Label	Optional, up to 255 characters.
Description	Optional, up to 1,024 characters.
Values	Any value (the default) or From a list. A list holds up to 1,000 values, each unique (compared case-sensitively, like targeting), at most 255 characters and free of the list separator; each can have a label. The order you give is the order pickers show. Switching a listed parameter back to Any value deletes its list when you save, so Save asks first.
Accept values that are not in the list	Shown for a list. On (the default), pickers also take a value you type; off, they offer only the listed values. Targeting always reads the value the tag sent either way.
Record in analytics	On (the default): the parameter is written to the analytics log and the conversion parameter log. Off: it is left out of both. With a closed list (Accept values… off), a value outside the list is recorded as ~other, shown in reports as Other (not in list).
The request can carry several values	Off: One of rules compare the request value whole. On: they split it on the Separator first and match when any item is in the rule’s list — the table in When the request sends several values. It also unlocks the has all of operator, which needs every value of the rule among the items.
Separator	Comma ,, Pipe `
Try a value	A preview only, never saved: splits what you type exactly as ad serving will.
Used by	Shown when editing: every targeting rule that reads the parameter, with the entity it sits on named by type, id and name — Campaign #990102 · Brand Awareness Q3 — Include · contentGenre is not one of [123]. The names are plain text, not links: the entities live on account pages, which an admin cannot open.

Permissions

Permission	Lets you
Custom Parameters (admin)	Open the page, add, edit and delete parameters, change Unregistered parameters, move the Analytics configuration list, and see Used by, the rule counts and the Description. Granted at the release to every role and user that had Analytics Configuration.
Any signed-in user	Read the registered names, labels and values — what the targeting editor and the Advanced report’s filter offer.

API

/rest-api/custom-parameters lists the parameters to anyone signed in, with the recording policy, and changes them under the Custom Parameters permission. What the targeting rules say — ?usage=true rule counts and unregistered names on the list, rules on a single parameter — and the old list’s names (legacy) come back only under that permission; anyone else gets the parameters with their values, without them. /rest-api/custom-parameter-policy sets Unregistered parameters (ANY or ONLY_VERIFIED) and /rest-api/custom-parameter-policy/adopt-legacy moves the Analytics configuration list — see the Custom Parameters API reference. A value the API cannot read, such as "listSeparator": 9 or "valueMode": "ANY", is a 400 naming the field in errors, with the values it accepts; nothing is stored.

Related

• Custom parameter and cookie value targeting
• Macros
• Ad tags and API
• Users and roles
• Admin area map