General
This document outlines how to send advertiser website events to Clinch via server-to-server (S2S) communication, also referred to as a server proxy or webhook.
The S2S pixel mirrors the structure of traditional browser-based website pixels but requires a few additional technical parameters, such as timestamp, IP address, user agent, and identity signals.
S2S events are sent via the regular Website Pixel Data Source in Flight Control, under Account > Data Sources.
Common use cases for setting up S2S communication include:
- Using a Customer Data Platform (CDP) as a tag manager to transmit all brand online events to Clinch (website events)
- Passing offline conversion events (e.g., in-store purchases) from the CDP to Clinch.
Prerequisites
- Before implementation, the feasibility of server-to-server (S2S) event transfer, particularly for identity matching, should be reviewed with a Clinch solution architect. Please contact your Clinch account manager or customer success representative to coordinate this discussion.
S2S Pixel Implementation
Follow the steps below to set up a website pixel data source in Flight Control:
- Go to Account > Data Sources.
- Click Create > Add Website Pixel.
- Enter a name for the pixel.
- The new data source will be added to the Data Sources table.
- Locate the Advertiser ID (cid) and Pixel ID (dsid) from the newly created data source.
- You can find these within the downloadable pixel code (hover over the data source in the table, and click on the Download pixel code link to generate the pixel code).
- Ask for the Partner ID (optional) from your Clinch account manager.
- IP whitelisting: (Optional) Provide Clinch with the calling server IP addresses or IP ranges.
Endpoint Details
- https://trkweb.clinch.co/trk
- HTTP Method: GET
Event URL Parameters
The following tables list all the parameters (mandatory and optional) that can be sent via the S2S communication.
Note: It's recommended to URL encode any parameter on the request query string that might contain special characters.
Required Technical Parameters
| Parameter | Description | Required? | Format |
| cid | Encoded client ID | Yes | string |
| dsid | Encoded data source ID | Yes | string |
| timestamp | Event timestamp (in UTC) | Yes, if events are not sent in realtime | Epoch MS format |
| partner | Vendor partner ID on Clinch | Only needed if custom integration logic has been implemented between Clinch and the partner. | number |
| user_ip |
IPv4. Must be included using one of the following methods:
|
Yes | XXX.XXX.XXX.XXX |
| user_agent |
User agent. Must be included using one of the following methods:
|
Yes | URL-encoded string |
| referrer | The page URL from which the event originated | Yes | Full URL-encoded URL schema |
Identity Parameters
| Parameter | Description | Required? |
| clinch-sid | Clinch cookie id, as given in cookie sync with Clinch, or read from the website 1P cookie named 'clinch-sid' | No |
| clinchClickId_{client_enc_id} |
Clinch click ID, which is captured when a user clicks through an ad served by Clinch (via a landing page URL parameter), and is intended to be included with each event, whether client-side or server-side, to improve attribution coverage. See section below on How to Retrieve the Clinch Click ID
|
No |
| hem |
Hashed email address (SHA-256)
|
No |
| did |
Mobile resettable advertising ID (MAID), such as ADID(Android) or IDFA (iOS)
|
No |
| atsEnvelop | Liveramp ATS envelope | No |
| uid2 | UID2.0 identifier (usually UID2 encrypted token) | No |
Event Parameters
| Parameter | Description | Required? | Format |
| type | Event type (from known list) | Yes |
enum (string) that includes one of:
|
| stype | Event secondary type (usually provided in conversion events) | No | string (free text) |
| product | The product type /vertical, in case the event contains products or categories to match from product feeds. This can be left empty otherwise. |
Yes, if products from feeds are involved |
enum (string) that includes one of the following:
|
Content Parameters (E-Commerce)
| Parameter | Description | Required? | Format |
| ids | Viewed product IDs (should match product IDs in product feed) | No | comma-separated values |
| category | product category (should match the category in product feed) | No | string |
| recommended |
Recommended product IDs (should match product IDs in product feed). These are product IDs that the website or vendor recommendation engine may suggest to the user, as opposed to products the user engaged with. |
No | comma-separated string values |
| term | search term (usually in search term) | No | string |
Content Parameters (Travel)
| Parameter | Description | Required? | Format |
| from | Viewed product IDs (should match product IDs in product feed) | No | Example: NYC, LON, PAR |
| to | product category (should match the category in product feed) | No | Example: NYC, LON, PAR |
| depart or check in or outbound |
Recommended product IDs (should match product IDs in product feed). These are product IDs that the website or vendor recommendation engine may suggest to the user, as opposed to products the user engaged with. |
No | ISO 8601 example: 2023-09-21 |
| return or check in or outbound | search term (usually in search term) | No | ISO 8601 example: 2023-09-21 |
| city | City code for hotel products (must match the city parameter in hotel feed) | No | Must match the hotel feed's city parameter |
| ids | Hotel IDs | No | comma-separated IDs |
Purchase Event Parameters
| Parameter | Description | Required? | Format |
| orderId | Purchase order ID or confirmation ID. | No | string |
| amount | Total price amount | No | number |
| currency | Currency code | No | 3-letter code, like USD |
Privacy and Consent Parameters
| Parameter | Description | Required? | Format |
| tcf_string |
GDPR TCF string (can be replaced with gpp below) |
IAB TCF format | |
| usp_string |
US privacy string (CCPA, etc.) (can be replaced with gpp below) |
string | |
| gpp_string | Global Privacy Platform (GPP) consent string |
string; IAB GPP format Example: DBABBg~BUoAAABg.Q |
|
| gpp_sid | Global Privacy Platform (GPP) -> array of Section IDs to enforce |
comma-separated integers (usually 1) Example: 8 (indicates the CA-CPRA section to enforce) |
Other Parameters
| Parameter | Description | Required? | Format |
| utags | User tags, such as audience segments or user attributes. These tags are entered into the user profile and can be used during the ad decisioning process. |
No | comma-separated string values |
Retrieving the Clinch Cookie ID
The Clinch Cookie ID can be collected using one of the following methods:
1. Fetch from Clinch Endpoint
Partners can retrieve the Clinch Cookie ID directly from Clinch servers and store it in the website's first-party context.
Endpoint: https://trkweb.clinch.co/clinch-sid?cid={client_enc_id}
HTTP Method: GET
Response Format: application/json
Example Response:
{ "clinch-sid": "5c299f0f-c409-4abc-bd10-4e17b5d12eb3" }
Important Note:
- The request must include the cid parameter with the client’s encoded ID (available in Flight Control).
- The request is cross-origin and supports CORS (Cross-Origin Resource Sharing).
- The endpoint may return an HTTP 302 redirect to confirm cookie persistence.
- If no data is available, the response will be: { "clinch-sid": null }
- To avoid repeated empty responses, store the null value in the first-party context and retry only after several days.
2. Read from Advertiser Website’s First-Party Context
If already stored, the Clinch cookie ID can be read directly from:
- A first-party cookie named clinch-sid or a localStorage item named clinch-sid, depending on the implementation on the advertiser website.
- A small JavaScript snippet must be implemented on the site to fetch the Clinch third-party cookie and store it in the first-party context.
- This script can be:
- Hosted and provided by Clinch as a <script> tag.
- Or self-hosted by the advertiser via tag manager or website server.
3. Perform a Cookie Sync with Clinch
Partners may choose to sync cookies directly with Clinch servers.
- Reach out to your Clinch Account Manager/Customer Success Team to receive the appropriate sync endpoint.
- Store the resulting mapping between the Clinch Cookie ID and the partner user ID on the partner side.
Retrieving the Clinch Click ID
The Clinch Click ID should be sourced from the first-party cookie named clinchId_{client_enc_id} where {client_enc_id} is the client’s encoded ID, available in Flight Control for your account.
To populate this value:
- The Clinch JavaScript tag must be implemented on the advertiser’s website.
- The tag extracts the Clinch Click ID from the page URL and stores it in the website’s first-party context (cookie)
Alternatively:
- The Clinch Click ID can be manually extracted from the URL parameter: &clinchClickId_{client_enc_id}
- This value should then be persisted in a first-party cookie and included in each subsequent event sent to Clinch.