Source tokens and link parameters
How source tokens turn ad link parameters into macros and sub_id, and how to carry them over into campaign links.
A source token links an ad link parameter to a tracker slot: the parameter value is recorded in the click under the slot name and is available as a macro and in reports. The Source tokens («Токены источника») table is in the source card in the Sources («Источники») section. The owner and admin can change it; other roles with access to the section see the tokens without editing.
Table columns
One table row is one link parameter.
| Column | What to enter | Example |
|---|---|---|
| Slot («Слот») | The name the tracker stores the value under: a system slot or sub_id_1 … sub_id_30 | sub_id_2 |
| Name («Название») | An alias, your own name for the value. A macro with this name works the same as the slot macro | camp_id |
| Parameter («Параметр») | The parameter name in the traffic link. Case-sensitive | camp_id |
| Placeholder | The parameter value in the link: the ad platform's macro, which it replaces with its own data | {{campaign.id}} |
After carrying over to the campaign, the row from the example gives camp_id={{campaign.id}} in the traffic link. When a click arrives, the camp_id parameter value is recorded in sub_id_2 and is available as {sub_id_2} and {camp_id}.
In links and on pages, a macro by name works if the name starts with a Latin letter and consists of Latin letters, digits and the _ sign. In a report filtered to one campaign, the name labels the sub_id grouping, see Report builder.
- + Token («+ Токен») adds a row and puts the first free
sub_idslot in it. When all thirty are taken, select a slot in the list yourself: a row without a slot isn't saved. - ✕ deletes a row.
- Save («Сохранить») writes the source card together with the tokens.
What happens on save:
- rows with an empty Parameter field aren't saved;
- an empty Placeholder is filled with a macro by name, and if there's no name, by slot:
{camp_id}or{sub_id_2}; - for the
fbclid,gclid,ttclidandmsclkidparameters, an empty Placeholder stays empty.
The table on the screen stays the same after saving: the result is visible after you refresh the page.
New tokens start applying to clicks of all the source's campaigns within about 15 seconds after saving. Parameters in campaign links don't change at that point, see carrying over to the campaign.
If there are no tokens, the table shows “No tokens” («Токенов нет»). A source from the template catalog is created with the template's tokens; some templates have no tokens.
Slots
System slots
| Slot | What to store in it | Where it's used |
|---|---|---|
external_id | The click ID on the source's side | The {external_id} macro, including in the postback to the source; click search; the External ID report grouping and filter |
cost | The click cost | The click's cost, see Cost from the cost parameter |
currency | The currency the source passes | Stored in the click. Doesn't affect cost; the {currency} macro always gives USD |
keyword | The keyword | The {keyword} macro; the Keyword («Ключевик») report grouping and filter |
creative_id | The ad or creative ID | The {creative_id} macro; the Creative ID report grouping and filter |
ad_campaign_id | The ad campaign ID or name | The {ad_campaign_id} macro; the Ad Campaign ID report filter |
sub_id_1 … sub_id_30
Thirty slots for any values: placement, ad group, site, pixel ID. The values are available as {sub_id_1} … {sub_id_30} and in the sub 1 … sub 30 report groupings.
In stream conditions, sub_id_1 is selected from the list. Conditions on the other sub_id and on the keyword, creative_id, ad_campaign_id slots are set through the API or stream import, see Extra fields.
Slots with other names
Catalog templates include slots with other names, for example source. Such a slot is shown in the Slot list of its row and works as the {source} macro. If you select another slot in this row, the old name disappears from the list.
The Adset (name) («Adset (назв.)») and Ad (name) («Ad (назв.)») report groupings take values by the names adgroup_name and advert_name: the link parameter or the token name must be called that. In the Facebook Ads template, these are tokens with the sub_id_5 and sub_id_6 slots.
The full list of macros is on the Macros in links and pages page.
Click processing order
- The tracker reads the parameters from the link the visitor came through.
- If a parameter didn't arrive or arrived empty, and the campaign has a preset value for it, the tracker takes the value from the campaign, see Default values.
- The tracker goes through the tokens of the source selected in the campaign. The parameter value of each token is recorded in the slot and under the name.
A value from the link takes priority over the campaign's default value. A token fires when its parameter has a non-empty value, from the link or from the campaign.
Example: a token with the sub_id_2 slot, the camp_id name and the camp_id parameter. The campaign has no default value.
| Request | {sub_id_2} | {camp_id} |
|---|---|---|
https://track.example.com/abc1234?camp_id=777 | 777 | 777 |
https://track.example.com/abc1234?camp_id= | empty | empty |
https://track.example.com/abc1234 | empty | stays as the text {camp_id} |
Parameters without a token
A parameter that has no token is saved in the click too. It's available as a macro by its own name: ?placement=feed gives {placement}. Parameters named sub_id_1 … sub_id_30 go straight into their slots. A built-in macro takes priority over a parameter or token name that matches it, see Syntax.
Cost from the cost parameter
If the source has a token with the cost slot, its parameter value is recorded as the click's cost instead of being calculated by the campaign's cost model.
- A number from
0to1000is accepted. The fractional part uses a dot:0.035. - The value is treated as an amount in USD. The
currencyslot doesn't affect it. - If the parameter didn't arrive, isn't a number or is out of range, the click's cost is calculated by the campaign model.
Example: a token with the cost slot and the cost parameter, with cost=0.035 in the link: the click's cost is 0.035 USD.
How cost from the parameter combines with models and with the adjustment for traffic that didn't arrive is covered in Campaign cost models.
Platform click IDs and secret parameters
The ad platform appends the fbclid, gclid, ttclid and msclkid parameters to the link by itself. A token for such a parameter records the incoming value in a slot; in the Facebook Ads, Google Ads and TikTok Ads templates, this is the external_id slot. The parameter isn't included in the traffic link if its value in the campaign is empty or written as a macro like {fbclid}.
Parameters named token, access_token and capi_token aren't included in the traffic link either: the tracker takes their values from the campaign. The exact conditions for both cases are on the Campaign link, domain and parameters page.
Carrying tokens over to a campaign
Link parameters are set in the campaign: Campaigns («Кампании») → the campaign → the Source and parameters («Источник и параметры») tab.
- Select the source in the list to the right of the Source and link parameters («Источник и параметры ссылки») heading. If the parameter table is empty, the tracker fills it with the source's tokens.
- If the campaign already has parameters, click ↓ from source («↓ из источника»).
- Check the Value («Значение») column: enter your own values where you don't need the platform's macros.
- Click Save parameters («Сохранить параметры»).
How a token becomes a campaign parameter row:
| Campaign column | Where it comes from |
|---|---|
| Name | The token's Name, and if it's empty, the Slot |
| Parameter | The token's Parameter |
| Value | The token's Placeholder. A value already entered isn't replaced |
What the ↓ from source button does with an already filled table is covered on the Campaign link, domain and parameters page.
After you edit tokens, the parameters of existing campaigns stay the same. You can update them in all the source's campaigns at once with the Campaign parameters… («Параметры кампаний…») button in the source card, see Applying a source to campaigns.
Check
- Open the campaign link with parameters in a browser.
- Go back to the campaign and click Statistics («Статистика»).
- Open the Click log («Лог кликов») tab.
- Click the row of your click.
In the click window, the Parameters (sub_id) («Параметры (sub_id)») block shows the values of the sub_id slots, and the Tokens («Токены») block shows the other slots, names and link parameters.
Limits and errors
| What | Limit |
|---|---|
| Tokens per source | 128 |
| Slot | up to 64 bytes |
| Name | up to 160 bytes |
| Parameter | up to 128 bytes |
| Placeholder | up to 1024 bytes |
A Latin letter and a digit take 1 byte, a Cyrillic letter takes 2. Save error messages appear at the top of the Sources page.
Invalid token list (no more than 128)
This message («Некорректный список токенов (не более 128)») means the source has more than 128 tokens. Delete the extra rows and click Save.
A token must have a name and a parameter of valid length
This message («У токена должны быть имя и параметр допустимой длины») means one of the row's fields is longer than the limit from the table, or the Parameter field contains only spaces. Shorten the value or enter the parameter name.
URL parameters in tokens must not repeat
This message («Параметры URL в токенах не должны повторяться») means the same name is in the Parameter column of two rows. Names that differ only in case are considered different. Keep one row per parameter.