Not what you’re looking for?

Submit a Ticket
?

Partnerize Server to Server (s2s) Tracking Integration

__________________________________________________________________________________________________________________

This article will review:

  • An overview of the Partnerize Server to Server tracking solution
  • How the brand should implement the solution 
  • How to test the solution

__________________________________________________________________________________________________________________

Index

Overview

Server to Server (S2S) tracking is an alternative solution to pixel tracking, which is the most common implementation method to record online sales in affiliate marketing. For brands who do not want to implement tracking tags, Partnerize offers this alternative real time solution. 

The Partnerize S2S tracking is suitable for brands who: 

  • Do not want to include additional tracking pixels on their site 
  • Are concerned pixels may increase page load times 
  • Prefer a more robust and secure alternative to pixel tracking 

S2S tracking involves a direct, secure HTTP call, via POST or GET, to the Partnerize tracking API. This server-to-server communication method is transparent to the Web pages on a brand’s site, therefore no tracking tags are rendered within the Web browser, which increases the security and accuracy of the tracking. This method also avoids the need for any 3rd party cookie tracking to be involved, which results in an extremely robust and reliable tracking solution. 

__________________________________________________________________________________________________________________

Implementation Steps

In order to track sales via the S2S, there are two key components to implement as denoted by the diagram below:

Picture_1.png

Event Description

1.Click tracking

This involves the brand capturing a unique ID (click ref) passed from Partnerize into the brand's URL. 

The clickref is ultimately returned to Partnerize so sales can be allocated to the originating publisher.

2. Sale/Conversion capture

At the point of purchase, the brand sends all transactional information to the Partnerize conversion API. 

From this data, the relevant publisher is awarded commission and the sale is recorded in the Partnerize system.

__________________________________________________________________________________________________________________

Step 1 - Click Tracking

All traffic generated by Partnerize publishers, will arrive at the brand's Web site with a unique 'clickref' parameter appended to the URL. The 'clickref' is an alphanumeric value, which identifies a Partnerize click and all information associated with the click.

  • Example 1 :https://www.brandsite.com?clickref=abc123

The brand must capture the value of the 'clickref' parameter, and always store the most recent value in a 1st party cookie on the user’s browser. If a user did not purchase initially and returned later with a new 'clickref', the cookie must be overwritten with the new value and life period reset.

  • Example2 : https://www.brandsite.com?clickref=def456

 

NOTE:

  • The 'clickref' parameter name can be changed per brand request, but please inform Partnerize in advance.
  • The 'clickref' is unique per click so the brand must cookie the most-recent value in order to award commission on a “last click” wins basis. 

__________________________________________________________________________________________________________________

Step 2 - Conversion Tracking

At the point of sale, all transactional information (along with the 'clickref' captured earlier) must be passed into the S2S conversion call. Please note the conversion URL may differ based on a client specific requirements.

 

Example conversion url

https://prf.hn/conversion/tracking_mode:api/campaign:{CAMPAIGNID}/clickref:{CLICKREF}/conversionref:{ORDERID}/country:{COUNTRY}/currency:{CUR}/customertype:{new|existing}/voucher:{VOUCHER}/[category:{CAT}/sku:{SKU}/value:{VALUE}/quantity:{QTY}]

 

Explanation of tracking parameters

The conversion URL is populated with several parameters to record a valid conversion. These are key-value pairs, using a colon to separate the key-value pair, and a forward slash, to delimit each parameter: 

Parameter name Description Example Required

campaign 

Unique identifier assigned to the Partnerize campaign.

Please contact integration.support@partneriz e.com if you do not have one.

campaign:XXXXXX 

Y

clickref 

Most recent clickref used in sale.

 

TIP:

Advisable for this value to be stored against the order within brand's own database, as it allows a robust solution should any conversion replay be required.

clickref:def456 

Y

conversionref 

Unique reference generated by brand for each conversion.

This is used for validation purposes. If no reference can be generated please omit this parameter and Partnerize can automatically create.

Please note if Partnerize creates a reference, it will be difficult to validate, as this value will be random.

conversionref:138516768 

Y

country

The site country where the purchase occurred.

Must conform to the ISO 3166 letter country codes.

 

country:GB

N

currency

The currency used for purchase.

 

Must conform to the ISO 4217 3-letter currency codes.

 

Not required if conversion event has no monetary values (E.g sign up / applications) 

currency:GBP

Y

customertype

Defines whether a customer is a 1st time buyer or a repeat customer. Populated with ‘new’ or ‘existing’

 

How a customer is defined as ‘new’ or ‘existing’ is based on the brand's own business rules

customertype:new

N

voucher

The voucher used at point of purchase.

 

IMPORTANT:

The discount of the voucher must be reflected in the value amount for all items to which it relates. 

 

This ensures that the commission calculated from the conversion is taken from the fully discounted total, not the pre-voucher amount

voucher:discount10

N

 

NOTE: If a parameter does not contain any value still include the parameter and leave blank

__________________________________________________________________________________________________________________

Basket Data Parameters 

To record individual items within a conversion, pass the details of each into a specific item container, which is held within square brackets []. The available parameters are listed below. Although not all parameters are required, it is advisable to return as much as possible to increase reporting granularity:

 

Parameter name Description Example Required
category The category of the item, which has a percentage or fixed value attributed to it. category:DVD  Y
sku The item product code.  sku:98735c  N
value

Ensure "value" is the individual item value

 

Exclude tax, delivery costs and any currency symbols

 

This value is only compulsory if the brand wishes to award % commission.

value:19.99  N
quantity

The quantity of the item. 


This must be a positive number and cannot be negative.

quantity:1 Y

 

NOTE:

  • "value"  is multiplied by "quantity" to calculate the total basket cost. 
    • If brand awards % based commission, this total cost is used 
  • No Personal Identifiable Information (PII) that a 3rd party could use to identify the end user should be passed into any of the tracking parameters (i.e. email address, home address, phone number, etc).

__________________________________________________________________________________________________________________

Retrospective insert Parameter

Partnerize system will track sales in real time (whenever the server to server call is made). However,  if conversions are systematically queued up to be inserted after the initial event, it's still possible to track against the original sale time. 

 

Parameter name Description Example Required

conversion_time 

An optional UTC date/time can be specified to 

retrospectively insert a sale YYYY-MM-DD HH:MM:SS 

 

conversion_time:2014-02-01%2 014:17:21

N

 

NOTE:

  • If no "conversion_time" parameter is used PZ will use the current UTC time for insert date
  • MUST be in UTC 
  • This parameter must sit outside of the item block []

__________________________________________________________________________________________________________________

API Response

Upon success, the sale API will return a unique Conversion ID of type VARCHAR (64), When this is empty it represents a failure to insert. 

1011l127393111

 

NOTE: To suppress these outputs remove parameter "/tracking_mode:api/" from the conversion URL. 

__________________________________________________________________________________________________________________

Populated Examples

Single Item Conversion Example:

Note certain parameters are left blank if no value 

https://prf.hn/conversion/tracking_mode:api/campaign:XXXXXX/clickref:def456/conversionref:87971/country:GB/currency:GBP/customertype:/voucher:/[category:SHOES/sku:4A7CAA/value:50.99/quantity:1]

 

Multiple Items Conversion Example:

Example Involving 2 Bags and 1 Shoes. Note the usage of two separate item blocks [ ] :

https://prf.hn/conversion/tracking_mode:api/campaign:XXXXXX/clickref:def456/conversionref:787977/country:US/currency:USD/customertype:existing/voucher:Discount10/[category:BAG/sku:bao98/value:35.00/quantity:2]/[category:SHOES/sku:4A7CAA/value:50.99/quantity:1]

 

Retrospective Conversion insert Example:

Example time based insert with voucher populated

https://prf.hn/conversion/tracking_mode:api/campaign:XXXXXX/clickref:def456/conversionref:87971/country:GB/currency:GBP/customertype:existing/voucher:discount10/[category:SHOES/sku:4A7CAA/value:45.20/quantity:1]/conversion_time:2021-10-01+18:33:03

 

NOTE:

  • The overall value of the conversion is calculated from the value of each item. 
  • campaign:XXXXXX is a test campaign reference. Please ensure XXXXXX is replaced by your unique ID. The Partnerize deployment team will supply this during the integration phase 
  • clickref must contain the most recent ID that drove the purchase in order to award the sale to originating publisher

__________________________________________________________________________________________________________________

Metadata Tracking

Partnerize offers a flexible and robust pixel, allowing brands to record additional sale information outside of the standard predefined tracking parameters. Within the Partnerize conversion tag a brand can include as much metadata as possible. 

This flexibility provides brands a greater insight and granular level of reporting for sale optimisation. 

The meta parameter name can be defined by the brand but must follow the syntax of parameter_name:value delimited by the ‘/’ 

 

Metadata Example (with delivery_cost)

https://prf.hn/conversion/tracking_mode:api/campaign:XXXXXX/clickref:def456/conversionref:87971/country:GB/currency:GBP/customertype:new/voucher:/[category:SHOES/sku:4A7CAA/value:45.20/quantity:1/delivery_cost:free]

 

NOTE:

  • Any meta parameters must be contained within the item blocks[ ]
  • Please avoid using the parameter name of ‘destination’

__________________________________________________________________________________________________________________

Vertical specific metadata parameters

Below are some examples of commonly used meta parameters for different verticals e.g.

  • Retail
  • Travel
  • Finance
  • Telecoms

Retail:

Meta Parameter Name Description Example Value

product_name

Populated with the product name for the item purchased

product_name:Nike Air Max 270

product_brand

Populated with the product brand for the item purchased

product_brand:Nike

product_type

Populated with the product type for the item purchased

product_type:Trainers

product_size

Populated with the size for the item purchased

product_size:10

product_colour

Populated with the colour for the item purchased

product_colour:Black

product_gender

Populated with the product gender for the item purchased

product_gender:Men

 

Travel:

Meta Parameter Name Description Example Value

check_in_date

Populated with the check in date for the booking

check_in_date:2019-09-17

check_out_date

Populated with the check out date for the booking

check_out_date:2019-09-20

hotel_id

Populated with the hotel ID for the booking

hotel_id:55871

hotel_location

Populated with the hotel location

hotel_location:London

refundable

Populated with the cancellation status for the booking

refundable:Yes

number_of_guests

Populated with the number of guests for the booking

number_of_guests:2

number_of_nights

Populated with the number of nights for the booking

number_of_nights:1

origin

Populated with the flight origin (i.e. airport code)

origin:NCL

dest

Populated with the flight destination (i.e. airport code)

dest:AMS

passengers

Populated with the number of passengers

passengers:2

haul

Populated with the flight haul (i.e. long haul / short haul)

haul:Short+Haul

return

Populated based on if the booking is a one way or return journey

return:Yes

flight_class

Populated with the flight class for the booking (i.e. Economy / Business Class / First Class)

flight_class:Economy

net_value

Populated with the net booking value


NOTE: This is on the assumption that the VALUE parameter is populated with GROSS booking value.  These parameters are interchangable (i.e. VALUE can be populated with NET booking value, and GROSS can the be tracked as an additional meta parameter instead)

net_value:150.00

 

Finance:

Meta Parameter Name Description Example Value

cover_type

Populated with the cover type for the policy

cover_type:Buildings+Contents

policy_start_date

Populated with the policy start date

policy_start_date:2019-09-17

policy_end_date

Populated with the policy end date

policy_end_date:2020-09-17

monthly_payment

Populated with the monthly payment amount

monthly_payment:21.57

application_status

Populated with the application status, where a real time decision is returned

application_status:Approved

product_name

Populated with the product that was applied for

product_name:Balance+Transfer

credit_limit

Populated with the credit limit provided

credit_limit:5000

loan_amount

Populated with the loan amount

loan_amount:10000

loan_term

Populated with the loan term

loan_term:15

 

Telecoms:

Meta Parameter Name Description Example Value

contract_length

Populated with the contract length for the order

contract_length:24m

download_limit

Populated with the download limit

download_limit:Unlimited

speed

Populated with the broadband speed

speed:100Mbps

activation_fee

Populated with the activation fee for the order

activation_fee:30.00

manufacturer

Populated with the manufacturer of the handset purchased

manufacturer:Samsung

handset

Populated with the handset purchased

handset:Galaxy+S10

minutes

Populated with the number of available minutes for the contract

minutes:Unlimited

texts

Populated with the number of available texts for the contract

texts:Unlimited

data

Populated with the amount of available data for the contract

data:10Mb

operating_system

Populated with the operating system

operating_system:Android

add_ons

Populated with any add ons. add_ons:5mb_data

 

__________________________________________________________________________________________________________________

Tracking Customer Device & User Context

Device and user context information is typically obtained from the User Agent string which is sent as part of the HTTP header from a desktop browser. As Server to Server implementations will not have a User Agent (since not loaded from a browser), information such as desktop or tablet will not be present to report. To address this, Partnerize now has functionality, which allows clients to send device & user context information with their server to server requests. This ensures that conversion data can still be correctly segmented within the Partnerize reports & provides the same pivot functionality, which is available in the platform for pixel clients.

 

The top-level conversion parameters of which are required to be passed through in order to override the device and user context are device and context. They both must be supplied in the request for the device to be captured correctly. In a S2S example, these would sit at the top level of the conversion call (prior to the item brackets): 

 

Example

https://prf.hn/conversion/campaign:XXXXXX/clickref:def456/tracking_mode:api/conversionref:568043/device:{device}/context:{context}/[category:DVD/sku:98735c/value:19.99/quantity:1/productname:ET/delivery:freeshipping/age:PG] 

 

Device & Context Values:

The following values are valid values for device and context:

Device

bot

desktop

mobile

tablet

Other

 

Context Description

web

Standard desktop web

m_web

Mobile web

m_app

Mobile app

in_app

In Mobile App

cd_d

Cross device - deterministic

cd_p

Cross device - probabilistic

other

Other/unknown

offline

Offline

 

Example:

Should a brand wish to record a transaction of which occurred on a mobile device via mobile web, the resulting conversion call might look something like this (values in bold should be dynamically populated):

https://prf.hn/conversion/tracking_mode:api/campaign:{CAMPAIGNID}/clickref:def456/conversionref:138a76098/device:mobile/context:m_web/[category:DVD/sku:back+to+future/value:9.99/quantity:1]

Tracking the Device & User context in this way will mean that both fields will be available & pivotable/filterable in the Partnerize reporting table.

 

NOTE:

  •  It is entirely possible to mix and match any device and context values and it is the responsibility of the requester to ensure the correct values of each parameter.

__________________________________________________________________________________________________________________

Testing

Once the tags are deployed, they should be tested by submitting a test transaction via the brand’s live website.  A non session test should be performed, which simulates a returning customer who originally followed a partner link but purchased at a later date. Providing the sale is made within the cookie period of the brand, the transaction should track successfully.  Full testing instructions can be found here:

https://help.phgsupport.com/hc/en-us/articles/360019824018-Testing-Tracking-Solutions-FAQs

You should also test the implementation of the 1st party cookie to ensure that the clickref is being stored correctly:

  • Click a test Partnerize link
  • Check that the clickref is being stored in a 1st party cookie 
  • Click the same test Partnerize link again and ensure that the previously set clickref is overwritten to the most recent clickref generated

__________________________________________________________________________________________________________________

Next Steps

  • Request a campaign_id & that the clickref is enabled on the campaign.  You can do this by emailing the Partnerize Integration team at integration.support@partnerize.com.
  • Implement the relevant tracking, as described in the above guidance.
  • Perform testing using the above instructions - Transactions will need to be submitted via the brand’s live website, so that the implementation can be fully tested.  

Questions 

If you have any technical questions regarding this document please get in touch with our Integration team at integration.support@partnerize.com   

Was this article helpful? 1 out of 1 found this helpful

Didn't get the answer you need?

Get in Touch