Server-to-Server (S2S) Postback Integration

overview server to server (s2s) postback integration allows advertisers to send conversion data directly to momentscience from their servers this method provides a reliable way to track conversions without requiring client side implementation on conversion pages this is the server side equivalent of the momentscience javascript tracking sdk (omnisdk) when momentscience sends traffic to your landing pages, we include an adpx click id parameter in the url you store this identifier with the user session, then send it back to us via postback when conversions occur key benefits no client side dependencies track conversions without javascript, ideal when browser based tracking is restricted or unreliable multi event attribution record multiple conversion actions per user session with dynamic payout values privacy compliant meet gdpr/ccpa requirements with server side data handling cross platform support works with mobile apps, backend systems, and any environment that can make http requests prerequisites before you begin, ensure you have technical capability to capture url parameters from incoming traffic server infrastructure to store click identifiers and trigger postbacks if you already work with affiliate networks, you're likely familiar with this process the integration follows standard industry practices for server to server conversion tracking how s2s postback works momentscience sends traffic to your landing page with adpx click id parameter your system captures the adpx click id and stores it with the user session user completes an action (purchase, signup, etc ) your server sends a postback to momentscience with conversion details momentscience processes the conversion and attributes it correctly data requirements mandatory parameters on incoming traffic from momentscience adpx click id unique identifier for tracking this click (required for all postbacks) on your postback to momentscience click id the adpx click id value you received from incoming traffic measurement must be set to 1 for all tracking requests, required for variable payout tracking) event event type identifier (e g , purchase , signup , lead ), required for variable payout tracking payout payout amount for the conversion in usd (e g , 25 50 , not cents) optional parameters optional parameters momentscience may send affiliate id unique identifier for the partner/traffic source this parameter is appended to tracking links to help you attribute traffic and conversions back to the specific partner additional parameters you can send in postbacks sale amount sale amount for cps (cost per sale) goal tracking used alongside payout when tracking the actual sale value for cps calculations you can store any parameters from the incoming url that are useful for your tracking needs the adpx click id is mandatory for the postback single conversion offers some offers support only one conversion type without multiple event tracking there are two scenarios fixed payout (same amount for every conversion) https //trk pubtailer com/track/?click id={adpx click id} variable payout (different amounts per conversion) https //trk pubtailer com/track/?click id={adpx click id}\&measurement=1\&event={event}\&payout={payout} for the event parameter, you can use any event identifier that your offer supports common choices include mosci , conversion , purchase , or any custom event name integration steps step 1 capture the click id from incoming traffic when momentscience sends traffic to your landing page, capture the adpx click id parameter from the url and store the adpx click id value with the user's session the method depends on your technology stack example landing page url https //yourdomain com/landing page?adpx click id=abc123def456\&other param=value the adpx click id must be stored reliably if this value is lost, you won't be able to attribute conversions back to momentscience step 2 configure your postback url configure your system to send postbacks to the momentscience tracking endpoint tracking endpoint base url https //trk pubtailer com/track/ method get postback url formats all postbacks use the same endpoint with the following parameters fixed payout https //trk pubtailer com/track/?click id={adpx click id} variable payout https //trk pubtailer com/track/?click id={adpx click id}\&measurement=1\&event={event}\&payout={payout} variable payout with sale amount https //trk pubtailer com/track/?click id={adpx click id}\&measurement=1\&event={event}\&payout={payout}\&sale amount={amount} note that the url parameter uses a hyphen ( click id ), not an underscore url parameters reference parameter type required description click id string yes the adpx click id value received from incoming traffic measurement integer conditional must be set to 1 required for variable payout tracking event string conditional event type identifier (e g , purchase , signup , conversion ) required for variable payout tracking payout decimal conditional payout amount for the conversion in usd (e g , 25 50 ) required for variable payout tracking sale amount decimal no sale amount for cps goal tracking step 3 trigger postbacks on conversion events when a user completes a conversion action, send a postback to momentscience with the stored adpx click id example postback urls single conversion offer (default event) curl x get "https //trk pubtailer com/track/?click id=abc123def456" \\ h "accept / " \\ h "cache control no cache" purchase event with payout curl x get "https //trk pubtailer com/track/?click id=abc123def456\&measurement=1\&event=conversion\&payout=25 00" \\ h "accept / " \\ h "cache control no cache" lead generation curl x get "https //trk pubtailer com/track/?click id=abc123def456\&measurement=1\&event=lead\&payout=5 00" \\ h "accept / " subscription with payout and sale amount (for cps) curl x get "https //trk pubtailer com/track/?click id=abc123def456\&measurement=1\&event=subscription\&payout=29 99\&sale amount=149 99" \\ h "accept / " implementation example // retrieve stored click id and check expiration const adpxclickid = getfromsession('adpx click id'); const expiresat = getfromsession('adpx click id expires'); if (!adpxclickid || date now() > expiresat) { console log('no valid click id available'); return false; } // build tracking url const trackingurl = new url('https //trk pubtailer com/track/'); trackingurl searchparams append('click id', adpxclickid); trackingurl searchparams append('measurement', '1'); trackingurl searchparams append('event', 'purchase'); // event name of your choice trackingurl searchparams append('payout', '99 99'); // required payout in usd // send tracking request await fetch(trackingurl tostring(), { method 'get', headers { 'accept' ' / ', 'cache control' 'no cache' } }) then(response => { if (response ok) { console log('conversion tracked successfully'); } }) catch(error => { console error('tracking failed ', error); }); use lowercase event names with underscores (e g , profile complete , trial start ) keep names descriptive but concise, avoid special characters except underscores, and limit to 50 characters maximum tracking function example you can send multiple postbacks for the same adpx click id if multiple conversion events occur for example, a user might sign up (first event) and then make a purchase (second event) within your defined conversion window / track an event to momentscience @param {string} adpxclickid the click identifier from landing page @param {string} eventname event type (e g , 'purchase', 'signup') pass null for fixed payout offers @param {number} payout payout amount in usd pass null for fixed payout offers @param {number} saleamount optional sale amount for cps goal tracking @returns {promise\<boolean>} success status / async function trackevent(adpxclickid, eventname = null, payout = null, saleamount = null) { // check if click id exists and hasn't expired const expiresat = getfromsession('adpx click id expires'); if (!adpxclickid || date now() > expiresat) { console log('no valid click id available'); return false; } const trackingurl = new url('https //trk pubtailer com/track/'); trackingurl searchparams append('click id', adpxclickid); // for variable payout tracking, include measurement, event, and payout if (eventname !== null && payout !== null) { trackingurl searchparams append('measurement', '1'); trackingurl searchparams append('event', eventname); trackingurl searchparams append('payout', payout tofixed(2)); if (saleamount !== null) { trackingurl searchparams append('sale amount', saleamount tofixed(2)); } } try { const response = await fetch(trackingurl tostring(), { method 'get', headers { 'accept' ' / ', 'cache control' 'no cache' } }); if (response ok) { console log(`conversion tracked ${eventname || 'fixed payout'}${payout ? ` $${payout}` ''}`); return true; } else { console error('tracking failed with status ', response status); return false; } } catch (error) { console error('tracking request failed ', error); return false; } } // usage examples const adpxclickid = getfromsession('adpx click id'); // fixed payout offer (no event or payout needed) await trackevent(adpxclickid); // variable payout offers await trackevent(adpxclickid, 'conversion', 25 00); await trackevent(adpxclickid, 'signup', 5 00); await trackevent(adpxclickid, 'purchase', 99 99); // with sale amount for cps tracking await trackevent(adpxclickid, 'subscription', 29 99, 149 99); step 4 handle multiple conversions per user momentscience supports tracking multiple conversion events for a single user session this is useful for multi step funnels track signup, then track purchase recurring actions track multiple purchases over time different event types track various user actions with different payouts time window considerations conversions can be tracked from the initial click up to 30 days (default) custom attribution windows can be configured (contact your account manager) all conversions within the window will be attributed to the original adpx click id postback response codes momentscience returns http status codes to indicate the result of your postback request status code meaning action required 200 ok conversion successfully recorded no action needed do not resend any other status request failed or error occurred retry the request with exponential backoff only retry postbacks that receive a non 200 status code if you receive a 200 ok response, the conversion has been recorded successfully and should not be sent again if you encounter any issues during integration or have questions about s2s postback tracking, contact us mailto\ help\@momentscience com