Skip to content

Pixels and Postbacks Overview

Publisher Platform Pixel and Postback Integration Guide

Integration Types: Client-Side JavaScript/HTML & Server-to-Server HTTP
Products: All Publisher Products
Version: 0.0.1
Last Updated: 2025-08-22

📋 Overview

The Publisher platform supports comprehensive pixel and postback tracking through two primary integration methods: client-side pixels that execute in the user's browser and server-side postbacks that fire from our backend servers.

Integration Methods

Client-Side Pixels

Client-side pixels are JavaScript or HTML-based tracking codes that fire directly from the user's browser during form sessions. These pixels provide real-time tracking capabilities but may be affected by ad blockers or browser restrictions.

Server-Side Postbacks

Server-side postbacks are HTTP requests fired from Publisher backend servers directly to external endpoints. These postbacks bypass client-side limitations and provide guaranteed delivery with access to complete session data.

📖 Complete Tokens & Macros Reference

→ View All Available Tokens & Macros

Comprehensive reference table showing all tokens available across all pixel and postback types, including platform-specific tokens and support matrix.

🔧 Configuration

Portal Setup

  1. Access Publisher Portal with appropriate permissions
  2. Navigate to Campaign detail page
  3. Select Pixels Tab for configuration
  4. Add New Pixel configuration
  5. Set Friendly Name for identification
  6. Select Pixel Type from dropdown menu (e.g., "Client-Side Pixel: Session")
  7. Configure Content with pixel script or URL
  8. Test Configuration (recommended)
  9. Save Configuration to activate

🎯 Comprehensive Pixel and Postback Type Overview

This section provides detailed overviews of all pixel and postback types available in the Publisher platform.

🖥️ Client-Side Pixels

Client-Side Pixel: Session (Initialize)

  • Portal Name: Client-Side Pixel: Session
  • Event Trigger: Form session initialization
  • Token Format: #TOKEN# (hash symbols)
  • Documentation: Client-Side Pixels

Primary Use Cases

  • Session Attribution: Track traffic sources and campaign attribution

Available Tokens

  • Session tokens, URL parameters
  • Contact tokens: ❌ Not available (session start only)

Client-Side Pixel: Conversion

  • Portal Name: Client-Side Pixel: Conversion
  • Event Trigger: Form conversion/completion
  • Token Format: #TOKEN# (hash symbols)
  • Documentation: Client-Side Pixels

Primary Use Cases

  • Conversion Tracking: Monitor lead generation and form completion rates
  • Attribution: Attribute conversions to specific traffic sources

Available Tokens

  • Session tokens, contact tokens (SHA256 hashed), URL parameters

🖧 Server-Side Postbacks

📊 Session Tracking Postbacks

S2 Postback: Session

Primary Use Cases

  • Session Attribution: Track session sources and initial campaign attribution
  • Traffic Analysis: Monitor traffic patterns and source effectiveness
  • Real-time Monitoring: Immediate session tracking for live analytics

Available Tokens

  • Core event tokens, request data tokens
  • User data tokens: ❌ Not available (session start only)

🎯 Conversion Tracking Postbacks

S2 Postback: Conversion

Primary Use Cases

  • Attribution: Track conversion sources and campaign attribution
  • Conversion Analytics: Monitor conversion rates and performance metrics

Available Tokens

  • Core event tokens, user data tokens (SHA256 hashed), request data tokens
  • Revenue tokens: ✅ Available (may be 0 for non-revenue conversions)

💰 Payout/Revenue Tracking Postbacks

S2 Postback: Payout

  • HTTP Method: GET / POST
  • Event Trigger: Revenue generation or payout attribution
  • Payout Type Required: Yes (All, Payout, Debit)
  • Documentation: Payout Postbacks

Primary Use Cases

  • Revenue Attribution: Track revenue sources and campaign ROI
  • Financial Reporting: Generate detailed financial reports and analytics
  • Performance Analytics: Analyze revenue performance across different traffic sources

Available Tokens

  • Core event tokens, user data tokens (SHA256 hashed), revenue tokens

Payout Type Options

  • All: Fire for any revenue event (positive or negative)
  • Payout: Fire only for positive revenue (≥ 0)
  • Debit: Fire only for negative revenue (< 0)

🌐 Platform API Integrations

Platform API integrations provide direct server-to-server connections with major advertising platforms.

Facebook Conversion API

  • HTTP Method: POST
  • API Endpoint: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}
  • Event Name: Lead
  • Documentation: Server-Side Postbacks

Available Tokens

  • Core event tokens, user data tokens (SHA256 hashed), Facebook-specific tokens

Facebook Revenue API

  • HTTP Method: POST
  • API Endpoint: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}
  • Event Name: Lead
  • Documentation: Server-Side Postbacks

Available Tokens

  • Core event tokens, user data tokens (SHA256 hashed), revenue tokens, Facebook-specific tokens

TikTok Conversion API

  • HTTP Method: POST
  • API Endpoint: https://business-api.tiktok.com/open_api/v1.3/pixel/track/
  • Event Name: SubmitForm
  • Documentation: Server-Side Postbacks

Available Tokens

  • Core event tokens, user data tokens (SHA256 hashed), TikTok-specific tokens

TikTok Revenue API

  • HTTP Method: POST
  • API Endpoint: https://business-api.tiktok.com/open_api/v1.3/pixel/track/
  • Event Name: CompletePayment
  • Documentation: Server-Side Postbacks

Available Tokens

  • Core event tokens, user data tokens (SHA256 hashed), revenue tokens, TikTok-specific tokens

Snapchat Conversion API

  • HTTP Method: POST
  • API Endpoint: https://tr.snapchat.com/v3/{PIXEL_ID}/events?access_token={TOKEN}
  • Event Name: SIGN_UP
  • Documentation: Server-Side Postbacks

Available Tokens

  • Core event tokens, user data tokens (SHA256 hashed), Snapchat-specific tokens

Snapchat Revenue API

  • HTTP Method: POST
  • API Endpoint: https://tr.snapchat.com/v3/{PIXEL_ID}/events?access_token={TOKEN}
  • Event Name: PURCHASE
  • Documentation: Server-Side Postbacks

Available Tokens

  • Core event tokens, user data tokens (SHA256 hashed), revenue tokens, Snapchat-specific tokens

🔧 Specialized Postbacks

Session Ad Pixel

  • HTTP Method: POST
  • Event Trigger: Session events with ad response data
  • Special Requirements: Requires session cache, posts to ad request service
  • Documentation: Session Ad Pixel

Primary Use Cases

  • Ad Attribution: Track ad response data for attribution analysis
  • Session Analytics: Monitor session performance with ad context

Available Tokens

  • Core event tokens, session data tokens, request data tokens
  • Revenue tokens: ❌ Not available (non-revenue event)

🔄 Handling Data Deduplication

Data deduplication is critical for accurate reporting and preventing duplicate revenue attribution in vendor systems. The Publisher platform provides different deduplication strategies based on the type of event being tracked.

Revenue Event Deduplication

For Revenue/Payout Events Only:

  • Token: {externalidentifier}
  • Purpose: Unique identifier for revenue events to prevent duplicate revenue attribution
  • Availability: Revenue/payout postback types only (Payout postbacks, Platform Revenue APIs)

Example Revenue Deduplication: 

Postback URL: https://vendor.com/revenue?amount={publisherrevenue}&txn_id={externalidentifier}
Result: https://vendor.com/revenue?amount=8.50&txn_id=VENDOR_TXN_12345

Session/Event Deduplication

For Non-Revenue Events:

Client-Side Pixels

  • Token: #SESSION_ID#
  • Purpose: Unique session identifier for client-side tracking
  • Availability: All client-side pixel types

Server-Side Postbacks

  • Token: {sessionid}
  • Purpose: Unique session identifier for server-side tracking
  • Availability: All server-side postback types

Example Session Deduplication: 

Client-Side: https://vendor.com/session?id=#SESSION_ID#
Server-Side: https://vendor.com/conversion?session={sessionid}&event=conversion

🔄 Pass-Through Identifier Guide

Common Vendor Question: "How do I pass in an identifier and have it passed back in a pixel?"

The Publisher platform supports pass-through identifiers via URL parameters that can be captured and returned in both client-side and server-side integrations.

Client-Side Pass-Through Flow

Step 1: Pass Identifier in URL 

Landing Page URL: https://publisher.com/form?vendor_id=ABC123&campaign=summer

Step 2: Configure Pixel Template 

<!-- Pixel template in Publisher Portal -->
<iframe src="https://vendor.com/track?id=#VENDOR_ID#&camp=#CAMPAIGN#&session=#SESSION_ID#"
        scrolling="no" frameborder="0" width="1" height="1"></iframe>

Step 3: Pixel Fires with Values 

<!-- Actual pixel execution -->
<iframe src="https://vendor.com/track?id=ABC123&camp=summer&session=c3cb2110-67e0-11f0-b666-bd02cda1aec3"
        scrolling="no" frameborder="0" width="1" height="1"></iframe>

Server-Side Pass-Through Flow

Step 1: Pass Identifier in URL 

Landing Page URL: https://publisher.com/form?vendor_id=ABC123&source=google

Step 2: Configure Postback Template 

Postback URL: https://vendor.com/postback?vendor_id={req.qs.vendor_id}&source={req.qs.source}&session={sessionid}

Step 3: Postback Fires with Values 

Actual Request: https://vendor.com/postback?vendor_id=ABC123&source=google&session=c3cb2110-67e0-11f0-b666-bd02cda1aec3

Implementation Best Practices

  • Parameter Naming: Use descriptive parameter names to avoid conflicts
  • Data Validation: Validate parameter values in your receiving endpoints

🚨 Troubleshooting

Common Configuration Issues

Token not replaced

  • Solution: Verify token spelling and format (#TOKEN# vs {token})
  • Check: Ensure token is supported for your specific pixel/postback type
  • Reference: See Common Tokens for complete token compatibility

Macro not replaced in postback URL/payload

  • Solution: Verify macro spelling and availability for your postback type
  • Check: Review macro compatibility table and ensure proper URL encoding

Invalid JSON payload structure

  • Check: Use JSON validation tools to verify payload structure
  • Note: Ensure commas, brackets, and quotes are properly formatted

Postback/Pixel not firing

  • Solution: Verify endpoint URL accessibility and campaign activation
  • Check: Review campaign status and pixel/postback configuration
  • Note: Ensure campaign is active and events are triggering

Contact Data Issues

Contact tokens showing as unreplaced

  • Solution: Contact data may not be available during session initialization
  • Check: Ensure form has been completed and contact data is available in session

Hash values appear incorrect

  • Solution: Contact tokens are automatically SHA256 hashed for privacy
  • Check: This is expected behavior, not an error
  • Note: Raw contact data is never exposed in client-side pixels

URL Parameter Issues

URL parameter tokens not working

  • Solution: Ensure the parameter exists in the landing page URL
  • Format: Use #PARAMETER_NAME# for client-side or {req.qs.parameter_name} for server-side

Custom query string tokens not working

  • Solution: Ensure the parameter exists in the initial entry URL
  • Format: Use {req.qs.parameter_name} exactly as it appears in URL

Session Data Issues

Session data tokens not working

  • Solution: Ensure form has been completed and session data is available
  • Check: Verify the specific form field exists in the session data
  • Format: Use {req.sessionData.PROPERTY} exactly as documented

Server-Side Postback Issues

Macro replacement breaking JSON

  • Solution: Ensure macro values don't contain characters that break JSON
  • Check: Test with various macro values to ensure JSON remains valid

Revenue Event Issues

Revenue data tokens not working

  • Solution: Ensure revenue events are being generated and tracked
  • Check: Verify campaign has active revenue attribution rules
  • Format: Use revenue-specific macros like {publisherrevenue} and {advertisername}

Payout type filtering not working

  • Solution: Verify payout type selection in postback configuration
  • Check: Ensure the correct payout type ("All", "Payout", "Debit") is selected

Browser Compatibility Issues

Pixel blocked by ad blockers

  • Solution: Consider server-side alternatives for critical tracking
  • Check: Test across different browser configurations and ad blocker settings

Pixel not firing on conversion

  • Solution: Verify pixel configuration and form completion events
  • Check: Confirm pixel is saved and campaign is active
  • Debug: Use browser developer tools to monitor network requests

For detailed implementation guides, see the specific documentation for each pixel and postback type.