Taboola Integration

In adstage, you can automatically collect spend, impressions, and clicks from Taboola (Realize) campaigns with an API key, and report clicks and conversions arriving through a tracking link under the taboola.ads channel. Sending purchases back to Taboola as an S2S postback is configured per link.

Beta

The Taboola integration is still being verified with live advertiser accounts (the integration card shows a Beta badge). If the numbers in adstage differ from Taboola Realize, please let the adstage support team know.

1. Integration Overview

Taboola connects with a Client ID and Client Secret that you generate in Realize, not with an OAuth sign-in.

2. Getting Your API Key

1. Sign in to Taboola Realize and open the API Keys page.

2. Generate and copy the client_id and client_secret. The Client Secret is stored encrypted in adstage.

3. Note your account ID. This is the alphabetic account name shown in Realize, such as my-company-sc — not a numeric ID.

Please note

If you cannot see the API Keys page or generate a key, ask your Taboola account manager. Taboola states that existing customers can generate credentials on the API Keys page, and that others need to apply for API access.

The same guidance (How to get your Taboola key) and an Open Taboola key page button are also shown in the Cost Integration tab and in the add-account dialog.

3. Connecting Your Account

1. In the adstage dashboard, go to Integrations > Ad Channel Integration > Taboola and open the Cost Integration tab.

2. Turn on the Taboola Cost Integration switch. The Add Integration Account button is disabled while the switch is off.

3. Click Add Integration Account and fill in the Integration Information Registration dialog.

4. Click Integrate. Before saving, adstage calls the Taboola API once to verify the key and confirm it can access the account ID you entered (the button shows Verifying...).

5. The account is added with the Preparing status and the first collection (last 30 days) starts immediately. It usually changes to Success within a few minutes.

If something is wrong with the values, one of these messages appears.

If you run several accounts, add one entry per account ID.

Managing Connected Accounts

The account list shows Account Name, Status, Last Data Update, and Management (delete).

• Preparing: the first collection is running right after the account was added.
• Success: Taboola API calls are working. An account with no spend still shows Success.
• Failed: Taboola rejected the request because the key changed or lacks permission. Hover over the badge to see the reason. adstage retries on every collection, so the status returns to Success once the cause is fixed.
• Even with a Success status, a warning appears next to the status if no cost data has been stored for more than 3 days. Unless you simply paused your ads, check the integration.

Connection details cannot be edited. If you regenerated the key, delete the account and add it again with the new key. Deleting an account stops its collection, but data already collected stays in adstage.

4. Creating Tracking Links

In Deep Links > Create, select Taboola as the ad channel. The campaign field is pre-filled with {campaign_name}, and the sub channel fields under additional parameters with {site} and {site_id}. Leave them as they are — Taboola replaces them with real values at click time.

The link contains the macros below. The click ID and the campaign and ad IDs are always appended, whether or not you fill in the form fields.

Example:

https://adg.im/@{org}/track/taboola.ads?short_path={link_path}&click_id={click_id}&campaign={campaign_name}&campaign_id={campaign_id}&ad_creative_id={campaign_item_id}&sub_channel={site}&sub_channel_1={site_id}

Adding the Link in Taboola

When you create an ad in Realize, paste the link into the Landing Page URL field. To apply it at the campaign level instead, put only the parameters into the Tracking Code field at the bottom of the New or Edit Campaign page (do not start them with ? or & — Taboola adds those).

Please note

• Do not put the same parameter at both the campaign level and the ad level. Taboola asks you to use one level only; using both can produce inaccurate data.
• Do not remove or rename the macros. In particular, without click_id={click_id} conversions sent to Taboola cannot be matched. The macro value {click_id} must be entered exactly as documented; only the parameter name on the left can be changed.
• Leave the ad group field empty. Taboola has no ad group level, and cost is collected at the campaign level only. The creative name macro is filled only when the advertiser names the creative, so it is not used either.
• Taboola also appends its Click ID to every ad URL as a tblci parameter by default. adstage uses the click_id value from the link, so no extra setup is needed.

5. Sending Conversions to Taboola

Taboola publishes an S2S postback specification that advertisers call from their own servers. In adstage this is configured in the link's Network Postback section, not on the integration screen.

1. Create the conversion in Realize first, and note the Event Name value in its conversion settings. This is the Event Name, not the Conversion Name.

2. Turn on Network Postback on the link you created above and choose Taboola — S2S under Network Preset. The URL below is filled in, the click ID parameter name is set to click_id, and the postback event is set to purchase.

https://trc.taboola.com/actions-handler/log/3/s2s-action?click-id={click_id}&name={event}&revenue={revenue}&currency={currency}

3. If your adstage event name (for example purchase) differs from the Event Name in Realize, map it under Event Name Mapping. Event names are case-sensitive.

Please note

• The receiving parameter must be named click-id with a hyphen. Keep the preset URL as it is.
• Postbacks are sent only for conversions attributed to this link, and the same event on the same click is sent only once. See Network Postback for details.
• Among Taboola's optional parameters, orderid and quantity have no matching adstage macro and are not sent.

6. Collected Data

In reports, channel-reported metrics are suffixed with (Channel) — for example, Cost (Channel) and Impressions (Channel).

Conversions (CPA Actions) and conversion value reported by Taboola are not app installs, so they are not counted in the Installs (Channel) or Conversions (Channel) metrics. Use the conversions adstage measures through the tracking link instead.

7. Cautions

• Campaigns with no spend, impressions, or clicks are not stored. Empty periods while ads were paused are expected.
• Data for the current day is not collected. Reports show data up to yesterday.
• Numbers may differ between Taboola and adstage. Taboola updates data with a delay of a few hours, and clicks can change retroactively for up to 48 hours and conversions for up to 30 days, so recent days may shift on each collection.
• Impressions will not match the Served Ads column in Realize, because adstage collects viewable impressions.
• A custom link with the channel set to just taboola is still reported as taboola.ads.

8. Troubleshooting

The account cannot be added

1. Check the account ID: make sure you entered the alphabetic account ID shown in Realize, not a numeric ID, with no leading or trailing spaces
2. Check the key: make sure the Client ID and Client Secret are not swapped and contain no stray spaces
3. Check permissions: ask your Taboola account manager whether the key can access that account
4. Check the switch: make sure the Taboola Cost Integration switch is on

No data is collected

1. Check the status: if it is Failed, hover over it to see the reason. For an authentication error, delete the account and add it again with a new key
2. Check delivery: confirm in Realize that there was actual spend in that period
3. Check the range: the current day is never collected, and only the last 30 days are fetched
4. Check the warning: if a warning appears next to the status, see how many days data has been missing

Conversions do not appear in Taboola

1. Check the link: confirm click_id={click_id} is still present in the URL you pasted into Realize
2. Check the event name: confirm the name you send matches the Event Name in the Realize conversion settings, including capitalization
3. Check the postback settings: confirm Network Postback is on for that link and the event you want is listed as a postback event
4. Check attribution: confirm in adstage reports that the conversion was attributed to taboola.ads. Events that are not attributed are not sent

If you need more help, please contact the adstage support team.

9. Frequently Asked Questions

Can I connect without help from Taboola? Yes, if you can generate a key on the API Keys page in Realize. If the page is not available to you, ask your Taboola account manager to approve API access.

Can I see cost by ad group or creative? No. Cost is collected at the campaign level only. To compare conversions by creative, enter a creative name in the link and create one link per creative.

Do Impressions in Realize and in adstage match? Yes. Both are viewable impressions. They differ from the Served Ads column.

Is historical data collected? The last 30 days are fetched automatically right after you connect. If you need data from before that, contact the adstage support team.

Reference Documentation

• Backstage API getting started (how credentials are issued)
• Realize API Keys page
• Client Credentials Flow
• Campaign Summary report
• Campaign Summary standard columns (impressions, viewable impressions, conversions)
• URL parameters for tracking (macros)
• S2S manual integration (how the Click ID is passed)
• The S2S postback URL