Skip to main content
Before moving to production, conduct thorough User Acceptance Tests (UAT) to ensure a smooth transition. This guide walks you through pre-launch preparation, testing procedures, deployment steps, and post-launch monitoring.
Your go-live process may vary depending on your integration path and ad formats. This guide covers the most common scenarios, but your specific implementation may differ. For example:
  • Sponsored Listings require full catalog integration with product data
  • Banner Ads may only require vendor/advertiser setup without product-level catalog
  • Placement configurations vary based on your ad format choices
Work with your Topsort contact to confirm which sections apply to your integration.

​
Pre-Launch Checklist

  • Product feed is connected and updating regularly
  • All product attributes (id, name, price, image, category) are populated
  • Product availability is accurate
  • Category taxonomy is properly mapped (based on your agreed taxonomy structure)
  • Auction requests include all required fields
  • Response handling is implemented
  • Impression tracking fires when sponsored products are visible
  • Click tracking fires on product clicks (including “Add to Cart” if applicable)
  • Purchase events include all order details
  • User IDs are consistent across all events

​
Common Configuration (All Ad Formats)

API Credentials:
  • Sandbox API keys are properly configured
  • Production API keys are ready (don’t switch yet)
  • API keys are stored securely in environment variables
  • Key rotation process is documented
Environment Setup:
  • Staging environment mirrors production configuration
  • All API endpoints are configured correctly
  • Timeout values are appropriate (recommended: 500-1000ms)
  • Error handling is implemented
Ad Display:
  • Ad placements render correctly on all device types
  • Ad labels are clearly visible (see labeling guidelines below)
  • Ad images/creatives load properly with fallbacks
  • Click-through behavior works as expected
Performance:
  • Page load times are acceptable with ads
  • Ads don’t block critical page rendering
  • Mobile experience is optimized (touch targets, responsive layouts, fast load times)
  • Accessibility requirements are met
Instrumentation:
  • Error tracking is configured (Sentry, Datadog, etc.)
  • Performance monitoring is in place
  • Custom dashboards are set up
  • Alerting thresholds are defined
Logging:
  • API request/response logging is enabled
  • Error logs are being captured
  • Audit trail for ad events is configured
  • Log retention policies are set

​
Ad Labeling Guidelines

Recommended Labels

Use labels that clearly indicate promotional content while avoiding ad-blocker triggers:
  • “Featured”
  • “Recommended”
  • “Client’s Choice”
  • “Top Pick”
Avoid using “Sponsored” or “Ad” as these terms are commonly targeted by ad blockers.

European Customers (DSA Compliance)

If operating in the European Union, the Digital Services Act (DSA) requires:
  • Clear labeling that content is an advertisement
  • Display of the advertiser name in ad details
  • Transparency about why the ad was shown to the user
Work with your legal team to ensure full DSA compliance.

​
User Acceptance Testing (UAT)

​
1. Catalog Testing

Verify Product Data

In Topsort Admin Panel:
  1. Navigate to Catalog section
  2. Verify products are visible and searchable
  3. Check that product data is complete:
    • Product names, images, and prices are correct
    • Categories are properly assigned
    • Product availability status is accurate
Test Campaign Creation:
  1. Create a new test campaign named UAT-TEST-[DATE]
  2. Try adding products to the campaign
  3. Verify product search and filtering works
  4. Confirm product selection saves correctly
Expected Result: All products should be selectable when creating campaigns, with accurate and complete information.

​
2. Auctions & Events Testing

Auction Testing

Setup:
  • Create UAT-TEST campaign with 3-5 products
  • Set high bid amount ($10+) to ensure wins
  • Activate the campaign
Test Scenarios:
  1. Verify auction request is sent
  2. Check that winning products are returned
  3. Confirm products render on page
Validation:
  • Check browser network tab for API calls
  • Verify auction response contains products
  • Ensure resolvedBidId is captured for event tracking

Event Testing

Test All Event Types:Impression Events:
  • Load page with sponsored products
  • Verify impression event fires when ad is visible
  • Check resolvedBidId is included
Click Events:
  • Click on sponsored product
  • Verify click event fires immediately
  • Note: “Add to Cart” actions also count as clicks if configured
  • Confirm navigation/action works correctly
Purchase Events:
  • Complete a purchase with sponsored product
  • Verify purchase event includes:
    • Product ID and quantity
    • Order value and order ID
    • User ID (required for attribution)
Test with Two Different Users: Perform all tests with at least two unique user sessions to verify proper user tracking and attribution.

​
3. Data Validation

1

Capture Test Evidence

For Each Test User:
  • Take screenshots of ad placements
  • Capture network requests showing API calls
  • Document order details for purchase events (if applicable)
  • Note timestamps for each action
2

Submit to Topsort

Send the following to your Topsort contact:
  • Screenshots of ad impressions
  • Network logs showing auction and event calls
  • Test campaign name and time range
  • User identifiers used in testing
3

Review Data Summary

Topsort will provide a summary including:
  • Total auctions received
  • Impression and click counts
  • Purchase counts (for listing ad integrations)
  • Data quality score
  • Any data discrepancies or issues
Verify Alignment:
  • Numbers match your test actions
  • Attribution chain is complete
  • No missing or duplicate events

​
Production Deployment

​
Deployment Steps

1

Connect Production Catalog

Option 1: Product Feed
  • Share your production feed URL with Topsort
  • Ensure feed is accessible and updates regularly
  • Recommended update frequency: Every 15-60 minutes
Option 2: Catalog API
  • Use the Catalog API for real-time updates
  • Implement create, update, and delete operations
  • Set up scheduled full catalog sync
Verify:
  • Product count matches expectations
  • All required fields are populated
  • Images are loading correctly
2

Obtain Production Credentials

Using Topsort UI:
  1. Topsort provides admin panel credentials
  2. You receive production API URL
  3. Generate API keys in admin
  4. Store keys securely in production environment
Using Custom UI:
  1. Receive production API URL from Topsort
  2. Receive production API key(s)
  3. Configure keys in your environment
Never commit API keys to version control. Use environment variables or secure secret management systems.
3

Deploy Integration Code

Pre-Deployment:
  • Review all code changes one final time
  • Ensure sandbox credentials are parameterized
  • Confirm rollback procedure is documented
  • Schedule deployment during low-traffic period
Deployment Process:
  1. Deploy code to production environment
  2. Update environment variables with production credentials
  3. Restart services to pick up new configuration
  4. Verify application starts successfully
Immediate Verification:
  • Check application logs for errors
  • Test basic functionality (page loads)
  • Verify API connectivity

​
Traffic Ramping Strategy

Gradual Rollout

Recommended Approach:Day 1-2: 10% of traffic
  • Monitor closely for errors
  • Validate data accuracy
  • Check performance metrics
Day 3-5: 50% of traffic
  • Compare metrics with baseline
  • Ensure system stability
  • Fine-tune if needed
Day 6+: 100% of traffic
  • Full production launch
  • Continue monitoring
  • Optimize performance

Feature Flags

Use Feature Flags to Control:
  • Which placements show ads
  • Percentage of users seeing ads
  • A/B testing configurations
  • Emergency kill switch
Benefits:
  • Instant rollback without deployment
  • Gradual rollout control
  • Per-placement configuration
  • Reduced deployment risk

​
Post-Launch Monitoring

​
Critical Metrics to Monitor

API Performance:
  • Auction API response time (target: <500ms p95)
  • Event API success rate (target: >99.5%)
  • Error rates and types
  • API timeout frequency
Application Performance:
  • Page load time impact
  • Time to first ad render
  • JavaScript errors
  • Memory usage patterns
Action Items if Issues Detected:
  • Response time >1s: Review timeout settings
  • Error rate >1%: Check API credentials and network
  • High JS errors: Review client-side implementation
Event Tracking:
  • Impression-to-click ratio (typical: 1-5%)
  • Click-to-purchase ratio (typical: 2-10%, for listing ads)
  • Event volume consistency
  • Attribution completeness
Data Integrity:
  • User IDs are present and consistent
  • resolvedBidIds are captured for impressions and clicks
  • Purchase amounts are reasonable (listing ads)
  • Duplicate events are minimal
Dashboard Checks:
  • Compare Topsort dashboard with your analytics
  • Verify revenue attribution matches
  • Check for data gaps or spikes
Campaign Performance:
  • Total impressions delivered
  • Click-through rate (CTR)
  • Conversion rate (listing ads)
  • Return on ad spend (ROAS)
User Experience:
  • Ad viewability rates
  • User engagement with ads
  • Impact on organic conversion rate
  • Page bounce rate changes
Revenue Impact:
  • Incremental revenue from ads
  • Average order value changes
  • Vendor adoption rate
  • Campaign creation velocity

​
Troubleshooting Common Issues

No Products Showing

Possible Causes:
  • No active campaigns
  • Bid amounts too low
  • Product targeting too narrow
  • Auction API errors
Debugging Steps:
  1. Check browser console for errors
  2. Verify auction API response
  3. Confirm campaigns are active
  4. Review targeting criteria

Missing Purchase Events

Possible Causes:
  • Event not triggered on checkout
  • Missing user ID in event payload
  • Incorrect product ID format
  • Network failures
Debugging Steps:
  1. Test purchase flow manually
  2. Check event payload structure
  3. Verify user ID is included
  4. Review server logs

​
Best Practices

Communication

Internal Coordination:
  • Notify engineering team of deployment
  • Alert customer support of new features
  • Update sales team on capabilities
External Communication:
  • Coordinate with Topsort team
  • Schedule launch calls
  • Establish escalation paths

Documentation

Maintain:
  • Deployment runbooks
  • Rollback procedures
  • API integration specs
  • Troubleshooting guides
Keep Updated:
  • Configuration changes
  • Known issues and workarounds
  • Performance benchmarks

Optimization

Continuous Improvement:
  • Review performance weekly
  • Optimize slow queries
  • Refine targeting
  • Test new placements
A/B Testing:
  • Ad placement positions
  • Number of ads per page
  • Ad formats and styles
  • Targeting strategies

Support

Establish:
  • On-call rotation
  • Incident response process
  • Topsort escalation contacts
  • SLA expectations
Document:
  • Common support scenarios
  • Resolution procedures
  • Contact information
Once you’re live, you’re ready to start optimizing. Reach out to your Topsort contact for guidance on campaign strategies, attribution tuning, and advanced configurations.