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
Pre-Launch Checklist
- Sponsored Listings
Catalog Integration
Catalog Integration
- 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)
Auctions Integration
Auctions Integration
- Auction requests include all required fields
- Response handling is implemented
Events Integration
Events Integration
- 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)
Environment Configuration
Environment Configuration
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
- Staging environment mirrors production configuration
- All API endpoints are configured correctly
- Timeout values are appropriate (recommended: 500-1000ms)
- Error handling is implemented
UI/UX Verification
UI/UX Verification
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
- 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
Monitoring & Analytics
Monitoring & Analytics
Instrumentation:
- Error tracking is configured (Sentry, Datadog, etc.)
- Performance monitoring is in place
- Custom dashboards are set up
- Alerting thresholds are defined
- 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”
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
User Acceptance Testing (UAT)
1. Catalog Testing
- Sponsored Listings
Verify Product Data
In Topsort Admin Panel:
- Navigate to Catalog section
- Verify products are visible and searchable
- Check that product data is complete:
- Product names, images, and prices are correct
- Categories are properly assigned
- Product availability status is accurate
- Create a new test campaign named
UAT-TEST-[DATE] - Try adding products to the campaign
- Verify product search and filtering works
- Confirm product selection saves correctly
2. Auctions & Events Testing
- Sponsored Listings
Auction Testing
Setup:
- Create
UAT-TESTcampaign with 3-5 products - Set high bid amount ($10+) to ensure wins
- Activate the campaign
- Verify auction request is sent
- Check that winning products are returned
- Confirm products render on page
- 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 on sponsored product
- Verify click event fires immediately
- Note: “Add to Cart” actions also count as clicks if configured
- Confirm navigation/action works correctly
- Complete a purchase with sponsored product
- Verify purchase event includes:
- Product ID and quantity
- Order value and order ID
- User ID (required for 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
- Numbers match your test actions
- Attribution chain is complete
- No missing or duplicate events
Production Deployment
Deployment Steps
1
Connect Production Catalog
- Sponsored Listings
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
- Use the Catalog API for real-time updates
- Implement create, update, and delete operations
- Set up scheduled full catalog sync
- Product count matches expectations
- All required fields are populated
- Images are loading correctly
2
Obtain Production Credentials
Using Topsort UI:
- Topsort provides admin panel credentials
- You receive production API URL
- Generate API keys in admin
- Store keys securely in production environment
- Receive production API URL from Topsort
- Receive production API key(s)
- Configure keys in your environment
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
- Deploy code to production environment
- Update environment variables with production credentials
- Restart services to pick up new configuration
- Verify application starts successfully
- 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
- Compare metrics with baseline
- Ensure system stability
- Fine-tune if needed
- 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
- Instant rollback without deployment
- Gradual rollout control
- Per-placement configuration
- Reduced deployment risk
Post-Launch Monitoring
Critical Metrics to Monitor
Technical Health
Technical Health
API Performance:
- Auction API response time (target: <500ms p95)
- Event API success rate (target: >99.5%)
- Error rates and types
- API timeout frequency
- Page load time impact
- Time to first ad render
- JavaScript errors
- Memory usage patterns
- Response time >1s: Review timeout settings
- Error rate >1%: Check API credentials and network
- High JS errors: Review client-side implementation
Data Quality
Data Quality
Event Tracking:
- Impression-to-click ratio (typical: 1-5%)
- Click-to-purchase ratio (typical: 2-10%, for listing ads)
- Event volume consistency
- Attribution completeness
- User IDs are present and consistent
- resolvedBidIds are captured for impressions and clicks
- Purchase amounts are reasonable (listing ads)
- Duplicate events are minimal
- Compare Topsort dashboard with your analytics
- Verify revenue attribution matches
- Check for data gaps or spikes
Business Metrics
Business Metrics
Campaign Performance:
- Total impressions delivered
- Click-through rate (CTR)
- Conversion rate (listing ads)
- Return on ad spend (ROAS)
- Ad viewability rates
- User engagement with ads
- Impact on organic conversion rate
- Page bounce rate changes
- Incremental revenue from ads
- Average order value changes
- Vendor adoption rate
- Campaign creation velocity
Troubleshooting Common Issues
- Listing Ads
- Common Issues
No Products Showing
Possible Causes:
- No active campaigns
- Bid amounts too low
- Product targeting too narrow
- Auction API errors
- Check browser console for errors
- Verify auction API response
- Confirm campaigns are active
- 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
- Test purchase flow manually
- Check event payload structure
- Verify user ID is included
- Review server logs
Best Practices
Communication
Internal Coordination:
- Notify engineering team of deployment
- Alert customer support of new features
- Update sales team on capabilities
- Coordinate with Topsort team
- Schedule launch calls
- Establish escalation paths
Documentation
Maintain:
- Deployment runbooks
- Rollback procedures
- API integration specs
- Troubleshooting guides
- Configuration changes
- Known issues and workarounds
- Performance benchmarks
Optimization
Continuous Improvement:
- Review performance weekly
- Optimize slow queries
- Refine targeting
- Test new placements
- 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
- 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.
