Outbrain

Outbrain is a traffic source (native). Its own documentation: https://www.outbrain.com/help/advertisers/amplify-api/.

What it connects

• Sends your conversions back to Outbrain.
• Pulls your spend from its API.
• Blocks placements in a source campaign.
• Pauses and resumes its campaigns and ads.
• Sets bids on its campaigns and ads.
• Sets daily budgets on its campaigns.
• Counts impressions (fired by the ad’s own pixel in the browser).
• Checks the connection with a harmless request when you test it.

How to connect it

Login. You set the account’s credentials below. Tallyray trades them for a token at the source’s login (GET https://api.outbrain.com/amplify/v0.1/login). The token lasts 30d; Tallyray logs in again before it ends, and at once if the source refuses it. If the source refuses the credentials, the connection needs them set again.

Conversions go without it: the postback carries no credentials, so a connection that lacks the API’s goes on sending conversions.

Set these on the connection:

Field	Name	Kind	What to enter
Marketer id	marketer_id	string, required	Your marketer’s id, as Outbrain’s Amplify API names it
Account currency	currency	string	Your marketer’s currency, such as USD. Its spend reads in it, USD when unset
Account time zone	time_zone	string	For spend, your marketer’s time zone, such as America/New_York; Outbrain reports by its days, and it can’t change once spend is reported
API user	username	string, secret	An Outbrain user the Amplify API is open to, for spend, sections and pauses; conversions go without it
API user’s password	password	string, secret	connectors logs in with it for the API’s token, every 30 days at most once an hour; set it here again when it changes in Outbrain

A secret is set by the workspace’s owner alone and never shown again. A required secret that is missing holds the connection’s deliveries until it is set; one that is optional holds only what reads it.

Tracking macros

Each token is a query parameter on the campaign URL; the source replaces its macro with the value when it sends the visitor. The columns say which part of the visit it fills and which report column (v1 to v20) it lands in.

Parameter	Macro	Fills	Report column
obclid	{{ob_click_id}}	The source’s click id
section	{{section_id}}	Placement	v1 (Section)
publisher	{{publisher_id}}	Site	v2 (Publisher)
cmp	{{campaign_id}}	Source campaign	v3 (Campaign)
ad	{{ad_id}}	Creative	v4 (Ad)
section_name	{{section_name}}	Custom value	v5 (Section name)
cost	{{cpc}}	Cost

The campaign URL you paste into the source is the tracking domain, the campaign’s key and the tokens the source fills, in this order (the domain below is an example, and {url_key} stands for the campaign’s own key):

https://trk.example.com/{url_key}?obclid={{ob_click_id}}&section={{section_id}}&publisher={{publisher_id}}&cmp={{campaign_id}}&ad={{ad_id}}&section_name={{section_name}}&cost={{cpc}}

Cost models, the first the default: from_token (the source’s own cost, passed in a token), cpc (cost per click), api (the spend pulled from the source’s API).

With from_token, the cost is the value of cost, per visit in USD.

Preview the campaign URL

Your tracking domain

Campaign URL

https://trk.example.com/{url_key}?obclid={{ob_click_id}}&section={{section_id}}&publisher={{publisher_id}}&cmp={{campaign_id}}&ad={{ad_id}}&section_name={{section_name}}&cost={{cpc}}

Copy

Impression URL

https://trk.example.com/i/{url_key}?section={{section_id}}&publisher={{publisher_id}}&cmp={{campaign_id}}&ad={{ad_id}}

Copy

Paste the campaign URL into the source's ad. {url_key} stands for the campaign's own key, which the portal fills in; the macros are the source's, which it replaces with each visit's values.

How conversions get back to it

Tallyray sends a conversion to Outbrain when it enters one of these statuses: approved. A conversion is sent once per status it enters; an adjustment, with revenue moving and its status not, isn’t sent. A conversion older than 30d isn’t sent.

Tallyray’s event kinds, and the name each is sent as. A conversion of a kind not listed isn’t sent:

Tallyray event	Sent to Outbrain as
lead	lead
registration	registration
sale	sale
deposit	deposit
subscription	subscription

The request: GET https://tr.outbrain.com/unifiedPixel.

A conversion is sent only when this holds:

=visit.external_click_id != ''

Conversions are retried when the source can’t be reached or answers with an error that can pass; see the limits below.

Spend

Tallyray pulls spend from the source’s API every 1h, covering the last 2d again, as sources restate spend, 1d at most per request, by day, in the zone =conn.time_zone != '' ? conn.time_zone : 'set the account time zone'. With api among the cost models, a campaign is priced by it.

The request: GET https://api.outbrain.com/amplify/v0.1/reports/marketers/{…}/campaigns.

Pulling spend needs the API’s credential. A connection without it goes on sending conversions and pulls no spend.

Placements

Placements are the visit’s placement value, as the tokens above fill it.

Blocking: PUT https://api.outbrain.com/amplify/v0.1/campaigns/{…}. Mode replace: the source takes a campaign’s whole list, so Tallyray reads it first, adds the blocks, and writes it back with the placements you blocked at the source kept.

Pausing and resuming

Rules and reports can pause and resume the source’s own objects at these levels. Tallyray reads an object before it writes, and writes only what isn’t so already, so a repeated pause never toggles anything.

Level	Named by
campaigns	cmp
ads	ad

A write may take up to 2m to show in a read; a read within that time that disagrees is read again later, not taken for a person’s change at the source.

Bids

Rules and reports can set the source’s bids at these levels. Each value is read before it’s written, in the account’s currency, never converted; a value the source sets itself isn’t written.

Level	Named by	Prices	Bounds	Notes
campaigns	cmp	cpc	step 0.001
ads	ad	factor	min 0.01, max 11, step 0.01	can be reset to the inherited value

Daily budgets

Rules and reports can set the source’s daily budgets at these levels, read before they’re written, in the account’s currency.

Level	Named by	Prices	Bounds	Notes
campaigns	cmp	daily	step 0.01

Impressions

The source fires a URL when its ad shows. It’s fired by the ad’s own pixel in the browser, so Tallyray judges them by the visit’s bot signals. Tokens on it: section, publisher, cmp, ad.

Limits

• Rate: at most 2/s per connection, 2 at once.
• Retries: up to 15 attempts, waiting from 30s and doubling up to 6h, longer when the source’s Retry-After asks, and never past the conversion’s age limit.
• Hosts it reaches: tr.outbrain.com, api.outbrain.com. No other.
• What a connection may override: /tokens, /conversions/events, /conversions/send_on, /cost. Hosts, authentication and requests never are, and an override may only lower the limits.

This page describes version 2 of the Outbrain template, the latest published. The version your connection runs is the one your administrators approved, and the portal shows it.