This article will review:
- How to upgrade your Pixel tracking solution to Server to Server (S2S)
- Updating your website to start accepting the 'clickref' value
- Creating & Implementing a TEST- version of the S2S tracking
- Reviewing and monitoring the data for comparison checks
- Switching to the new S2S tracking solution
This guide will outline the steps required to upgrade your existing pixel tracking to Server to Server (S2S) tracking solution. The goal is to ensure the live pixel tracking activity continues as normal whilst the new S2S solution is tested fully before switching over.
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 an advertiser’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.
Before proceeding please ensure :
- You ARE currently using the standard Partnerize pixel implementation to track sales from your confirmation pages
- You are UNABLE to implement Partnerize Tag
- If you ARE using a tag manager / eCommerce platform (E.g Google Tag manager, Shopify, Magento) and wish to upgrade, contact email@example.com for further instructions
This is designed to ensure a smooth transition from your old solution to new (S2S) with no disruption to live activity.
|1. Implement clickref / 1st party cookie||
Update website to start accepting the 'clickref' value and store in a 1st party cookie
❗NOTE: Contact firstname.lastname@example.org to enable 'clickref'
|2. Implementation of TEST- version of S2S tracking solution||
Implement the "TEST-" S2S solution to run in conjunction with the current live pixel
❗NOTE: Do NOT remove the existing pixel
|3. Notify Partnerize||Inform PZ when the "TEST-" S2S solution is implemented||Brand|
|4 .Review the TEST- S2S data||Feedback on performance & syntax of the "TEST-" S2S tracking||Partnerize|
|5. Switch from Pixel tracking to S2S tracking||Advise brand when tracking can be switched over to the new solution||Partnerize|
|6. Monitor performance||Monitor the new API activity||Partnerize & Brand|
Step 1 - Implement clickref / 1st party cookie (Brand)
All Partnerize referred traffic to brand's site will include a unique ID ("clickref") within the query string.
- E.g) https://www.brand-site.com?clickref=ABC1234
The 'clickref' is a unique ID which defines a Partnerize click and all associated information regarding the click (E.g which partner, creative used, which brand, time&date etc). This 'clickref' is generated every time a link is followed and allows Partnerize to allocate a sale back to a partner.
This 'clickref' must be stored by the brand in a 1st party cookie and ultimately returned to Partnerize via the S2S call so that sales can be allocated to the originating publisher. Whenever a new click is initiated, a new "clickref" is generated and updated.
- E.g) https://www.brand-site.com?clickref=DEF456
Upon checkout, the most recent "clickref" present will be used to reward "last click" wins.
- You will need to begin capturing the clickref for at least the length of time set as your cookie period in advance of switching over the new S2S to live.
- For example, if your cookie period is 30 days, you will need to capture the clickref for 30 days before the switch over. This is to account for all conversions within the cookie period, where the sales can take place after the changeover, where the click happened prior to the changeover.
Step 2 - Implementation of TEST- version of S2S tracking solution (Brand)
To ensure that your LIVE pixel tracking solution continues as normal while the new S2S solution is tested, we advise brand implement a "TEST-" version. This should be implemented to fire in conjunction with the existing Pixel tracking solution.
❗IMPORTANT : DO NOT REMOVE the existing LIVE pixel tracking solution❗
Here is how a standard pixel example may look (REFER to your implementation):
<img src="https://prf.hn/conversion/campaign:XXXXXXX/conversionref:CONVERSIONREF[category:CATEGORY/sku:SKU/value:VALUE/quantity:QUANTITY]" height="1" width="2" />
TEST- S2S conversion call (Please replicate existing parameters as current pixel):
There are new additional parameters which you need to include. Do NOT change the live pixel yet. Simply take the HTTPS call from your existing pixel and then add in these new data parameters.
This defines that this is an S2S conversion call
Upon success a unique conversion ID will be returned
❗NOTE : During test phase this will be blank
This is the Campaign ID but is prefixed with "TEST-" for the purposes of testing
This will not impact your live activity
This is to be populated with the latest captured CLICKREF, set in a 1st party cookie -
❗NOTE: "TEST-" must be prefixed before the clickref value so does not disrupt live activity
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.
An optional UTC date/time can be specified to
retrospectively insert a sale YYYY-MM-DD HH:MM:SS
If this parameter is OMITED, the time when the S2S conversion call is sent to Partnerize will be used as the conversion time
This must be populated with one of following user device:
This must be populated with the context (values in bold)
- The "TEST-" version must replicate all existing parameters as captured by pixel
- If you are unable to obtain a copy of your current tracking solution in order to check which parameters need to be included, please contact email@example.com and we can provide this to you.
- If these steps are not followed, this could result in tracking issues with LIVE conversions and in turn cause problems with the reporting and commissioning.
Step 3 - Notify Partnerize (Brand)
Once you have implemented the "TEST-" version of the S2S conversion call to run in conjunction with your LIVE pixel, please inform the Partnerize Integrations team, and performance of the new solution will be monitored.
Your system should be set up so that when live transactions take place, we should be seeing 2 logs in our Pixel/Server logs
- Live Pixel (v1)
- TEST- S2S (v2)
The live pixel (v1) will continue to track your current activity so no disruption is made to reports / partners and the "campaign:TEST-" (v2) will help the team review implementation.
Step 4 - Review the TEST- S2S data (Partnerize)
Partnerize will monitor and compare the live pixel data against the "TEST-" S2S conversion call data to ensure sure everything is correct before advising the brand when to make the switchover.
We will check the following during this process:
- Live pixel tracking is continuing as normal
- The volume of "TEST-" S2S conversion calls match the volume of live pixel calls
- The "TEST-" S2S syntax is correct and that the data being passed through matches that of the live pixel
- The "TEST-" version includes a valid clickref format value
- Further internal checks to make sure that the Campaign is ready to switch from pixel tracking to S2S tracking.
Step 5 - Switch from Pixel tracking to S2S tracking (Brand)
Once Partnerize has performed the necessary checks and can confirm data in the "TEST-" solution looks correct, we will advise the brand to make the switch over.
This involves the following actions by the brand:
- Brand to remove "TEST-" from parameters "/campaign:" and "/clickref:" thus making it live
- Remove the old (live) Pixel
- Informing Partnerize Integrations team that the above three steps have been actioned
BEFORE - Here is how the "TEST-" S2S conversion call will look BEFORE the changes:
AFTER - Here is how the "TEST-" S2S conversion call will look AFTER the changes:
The last step is for the brand to turn off the old 'live' pixel, leaving only the live S2S conversion call in place. Instead of deleting old pixel, we would recommend simply turning it off and potentially rename to PZ-OLD so it can easily be reverted back if necessary.
Please inform Partnerize when you have made the changes to the "TEST-" S2S conversion call and removed the old pixel.
- Only when the "clickref" has been stored for at least the cookie period (e.g 30 days), will it be advisable to make the switch over.
- This ensures any conversions made from clicks prior to the switch over will still track.
Step 5b - When to trigger S2S / Exclusive codes Tracking
The S2S conversion should be triggered at point of checkout and typically when a "clickref" value is present. If a brand wishes to utilise Partnerize's exclusive code functionality https://help.phgsupport.com/hc/en-us/articles/4405844671377 it is essential that vouchers are passed into the 'voucher' parameter.
Exclusive Codes also introduces the concept of clickless tracking, allowing brands to work with non-traditional partnerships who don't work with tracking links. In order to utilize clickless tracking, a brand must trigger the tracking unconditionally for every sale regardless if a clickref value is present.
The "clickref" parameter can be left empty as "/clickref:/"
❗NOTE: Even though tracking is loaded for every sale Partnerize will only attribute sales that were referred by our partners.
Step 6 - Monitor Performance (All)
Both the brand and Partnerize must monitor the live S2S activity to make sure sales are tracking as expected.
- Values are allowed to have unicode characters and any symbol excluding
"(unless URL encoded)
- slash ( / ) , colon ( : ) , square brackets ( [ ] ) are reserved characters in Partnerize System so please exclude
- For all non alphanumeric characters please ensure these are URL encoded
- E.g.) A space will be encoded to
conversionref:test orderwill become
- E.g.) A space will be encoded to
- Please exclude currency symbols (E.g. £ $ ) and comma separator from
- E.g.) If the product amount is
£1,980.99, you need set
- E.g.) If the product amount is
Notes & Considerations
If you are currently using a 3rd party container solution to trigger the pixel conditionally, as opposed to being fired directly from a confirmation page, then please read the considerations below:
Typical usages of 3rd parties include :
- Analysing traffic sources across multiple online channels.
- Firing the pixels conditionally (as they are implemented alongside other affiliate network pixels), for the purpose of sale de-duplication.
As the container solutions relies heavily on pixels, the S2S tracking solution will BYPASS this 3rd party as it involves a direct HTTP interaction which is outside of their control, which has the following impact:
- 3rd party not recording the sale within their system since API is not connected
- No sale duplication between pixels in container vs the API.
As conversion calls will no longer be sent to us directly from the user's browser we can no longer determine the DEVICE and CONTEXT automatically which means you must now pass this data through to us at the point of sale if you wish to continue tracking this data. Further details and examples can be found on the API Integration Document.