Guides
Log In
Guides
Start typing to search…

Manual S2S integration

Server-to-server conversion tracking - manual integration.

Overview

This topic describes how to set up S2S (server-to-server) conversion tracking manually.

👍

Intended audience

This flow requires some technical knowledge.

👍

Custom development

Custom development is required (in order to pass the event to Taboola).

Realize

Create an event-based conversion rule

🚧

The instructions below illustrate how to track a registration conversion.

Similar steps can be taken for other conversions - e.g. lead submissions, account upgrades, or subscription renewals.

For S2S-only use cases - such as tracking CRM-based conversions - see Track CRM-based conversions using S2S.

  1. Open Realize, and select the account (top, left) that you will use to track this conversion.

  2. In the sidebar (left), select Tracking.

  3. Click on + New Conversion (far right).

    Select Create conversions using code and click Continue.

  4. Type in a Conversion Name of your choice - e.g. Complete Registration.

    This is a descriptive name for your convenience. It is not used for matching purposes.

  5. For Conversion Type, select EVENT:

  6. (Optional) If relevant, fill in a Fixed Value.

    Tip: If the event returns a dynamic value, leave this field blank. For additional guidelines, see the Help Center.

  7. Scroll through the list of categories provided and select the relevant Category - e.g. Complete Registration.

  8. (Optional) If desired, edit the Event Name. For example, you might prefer the name registration, in place of complete_registration.

    🚧

    You will need to pass the event name - exactly as entered here - via the postback URL. If the naming convention is not identical, Taboola will not receive the event.

  9. (Optional) If desired, edit the following fields:

    1. Click Through Conversion Window
    2. View Through Conversion Window

  10. (Optional) If relevant, clear the Include in total conversions checkbox.

    Tip: Always include the most important conversions, so that the Taboola algorithm will optimize towards them. For additional guidelines, see the Help Center.

  11. (Optional) If relevant, clear the Include in total value checkbox.

  12. (Optional) If desired, edit the following fields:

    1. Audience Properties
    2. Aggregation Type

  13. Skip the Event Code section.

    (You will post the event values to Taboola via the Postback URL.)

  14. Review your chosen settings, and click on Create (bottom, right):

Understanding the Click ID parameter

🚧

Default Click ID param (tblci)

Taboola automatically appends the following to all ad URLs: tblci={click_id}

If your system can accept this parameter, no additional setup is required in Realize. Otherwise, you will need to add a custom Click ID parameter (see below).

📘

The Click ID

When your ad displays, the Click ID macro generates an actual Click ID value.

This is a case-sensitive string of variable length (approx CLICK_ID_LENGTH characters). It looks something like this:

CLICK_ID_EXAMPLE

Make sure to pass the string 'as is'. A truncated (or otherwise corrupted) value will be ignored.

Add a custom Click ID param (optional)

🚧

By default, Taboola automatically appends tblci={click_id} to all ad URLs. Only follow these steps if you need to use a different parameter name.

You can add a custom Click ID parameter at either the campaign level or the ad level. Choose the method that works best for your setup.

Option I: Add at the campaign level
  1. Open Realize, and select the account (top, right) that is running the campaign.
  2. Locate the relevant campaign and click on the Edit Campaign icon:
  3. Within the campaign settings, scroll down to the </> Tracking section.
  4. Append your custom parameter to the existing query string: &tbl_click_id={click_id}
📘

Example

Original string: utm_source=taboola&utm_medium=referral

Updated string: utm_source=taboola&utm_medium=referral&tbl_click_id={click_id}

🚧

Important

Enter the value on the right exactly as shown above: {click_id}

You can customize the parameter name on the left - but make sure your system uses the identical name.

Example:

If you append &tbl_click_id={click_id}, then your system must look for a parameter called tbl_click_id.

  1. Click on Save (bottom, right):

Option II: Add at the ad level

  1. Open Realize, and select the account (top, right) that is running the campaign.

  2. Locate the relevant campaign and open it.

  3. Find the ad you want to edit and click on it to open the ad settings.

  4. In the ad settings, locate the URL field (the target URL for the ad).

  5. Append your custom parameter to the end of the URL: &tbl_click_id={click_id}

    📘

    Example

    Original URL: https://example.com/landing-page?utm_source=taboola

    Updated URL: https://example.com/landing-page?utm_source=taboola&tbl_click_id={click_id}

    🚧

    Important

    Enter the value on the right exactly as shown above: {click_id}

    You can customize the parameter name on the left - but make sure your system uses the identical name.

    Example:

    If you append &tbl_click_id={click_id}, then your system must look for a parameter called tbl_click_id.

  6. Click on Save (bottom, right).

Pass the event data to Taboola

Overview

Now that you have defined an event-based conversion - and added the Click ID macro to your campaign - you need some way to pass the event data to Taboola.

2 methods are supported:

  1. The postback URL
  2. Bulk submit conversions

For an overview of the end-to-end flow, refer to the next section.

End-to-end flow

  1. By default, Taboola automatically appends the Click ID parameter to all ad URLs: ...&tblci={click_id}

    If you configured a custom parameter name (previous section), that parameter will be used instead.

  2. When your ad displays, an actual Click ID value is appended to the target URL: https://example.com/landing_page?...&tblci=a1b2c3d4e5f6
  3. Your landing page looks for the relevant parameter (tblci by default, or your custom parameter name) and grabs the value (a1b2c3d4e5f6).
  4. Your server is responsible to pass the event data to Taboola. 2 methods are supported:

    1. The postback URL

      For each conversion, invoke the postback URL. Use query parameters (e.g. click-id) to pass the event data for that conversion.

    2. Bulk submit conversions

      Pass a JSON object with event data (e.g. click-id) for multiple conversions.

    🚧

    Important: API parameter name

    When sending data to Taboola via the postback URL or bulk submit API, the parameter must be named click-id (with a hyphen), exactly as shown. This is different from the landing page parameter name (tblci by default, or your custom parameter name).

The sections that follow describe the postback URL and bulk submission flows.

Updated 1 day ago