Web SDK - Troubleshooting & Best Practices

Follow
Avatar
Jared Ornstead
Updated

Overview

This guide covers common implementation issues, best practices, and solutions to help you avoid tracking problems and ensure data accuracy.

Common Implementation Errors

Error 1: Duplicate Implementation (Native + GTM)

Problem: The most common error is implementing both the Native JavaScript SDK and the Google Tag Manager SDK simultaneously. This causes every session and event to be tracked twice, inflating all metrics by 200%.

IMPORTANT! Singular does not deduplicate events automatically. Using both implementation methods will double-count all your data.

How to identify this issue:

  • Check your website's source code for the Singular SDK script
  • Check Google Tag Manager for Singular tags
  • In browser developer tools, filter network requests by singular and count how many requests fire on page load (should be 1, not 2)

Solution:

  1. Decide which implementation method you want to use (Native JS recommended)
  2. Remove the other implementation completely
  3. Test to verify only one request fires per event
  4. Monitor your data for 24-48 hours to ensure metrics return to normal

Error 2: Incorrect Product ID Format

Problem: Using the wrong format for your Product ID. The Product ID should be consistent for the Web App across all subdomains.

Common mistakes:

  • Using a website URL: www.mycompany.com ❌
  • Using dashes: my-company-store ❌
  • Using forward DNS: mycompany.com.store ❌
  • Using spaces: my company store ❌

Correct format (Reverse DNS notation):

  • com.mycompany ✓

TIP! Think of your Product ID like a mobile app bundle identifier. Use lowercase letters, start with your domain in reverse, and use dots to separate components.

How to identify this issue:

  • Check network requests in developer tools - look for 400 or 403 errors
  • Verify the i parameter in the request payload from the browser developer tools.
  • Check for errors in the browser console

Solution:

  1. Get the correct value from your Singular Apps Page (BundleId)
  2. Update your implementation with the correct format
  3. Test and verify 200 status codes in network requests

Error 3: Events Firing Multiple Times

Problem: Events fire multiple times due to page reloads, rapid user clicks, or lack of deduplication logic. This inflates event counts and conversion numbers.

Common causes:

  • User clicks a button multiple times rapidly
  • Event code runs on every page render (React, Vue, Angular apps)
  • Form submissions that don't prevent default behavior
  • Page refreshes or back button navigation
  • Google Tag Manager triggers firing multiple times

IMPORTANT! Unlike some analytics platforms, Singular does not deduplicate events automatically. It is your responsibility to implement safety mechanisms to prevent duplicate tracking.

Solution strategies:

Review the strategies in the implementation guides for more details. Native JS, GTM

Error 4: SDK Not Loading

Problem: The Singular SDK script doesn't load, preventing any tracking.

Common causes:

  • Script blocked by ad blockers (mainly affects GTM)
  • Content Security Policy (CSP) restrictions
  • Script placed in wrong location on page
  • Syntax errors in implementation code
  • Network connectivity issues

How to diagnose:

  1. Open browser developer tools Console tab
  2. Look for errors mentioning "singular" or "sdk"
  3. Type typeof singularSdk in console - should return "function", not "undefined"
  4. Check Network tab for failed script loads
  5. Disable ad blockers and test again

Solutions:

  • Ad blockers: Switch to Native JavaScript implementation (less likely to be blocked)
  • CSP issues: Add Singular domains to your Content Security Policy
  • Script placement: Ensure SDK script is in <head> tag
  • Syntax errors: Validate your JavaScript code

Content Security Policy Configuration

If your website uses CSP headers, add these directives:

Content-Security-Policy: 
  script-src 'self' https://web-sdk-v1.singular.net;
  connect-src 'self' https://sdk-api-v1.singular.net;

Best Practices

Product ID Management

  • Use one Product ID per website or web app
  • Keep Product IDs consistent across all pages and subdomains
  • Document your Product IDs in your team's knowledge base
  • Use separate Product IDs for development, staging, and production environments

Event Naming Conventions

Good naming practices:

  • Use clear, descriptive names: Purchase, Signup_Completed, Video_Play
  • Use consistent capitalization (recommend Title_Case)
  • Use underscores instead of spaces
  • Keep names under 32 characters
  • Avoid special characters and emojis

Bad examples:

  • Purchase!!!🎉 (special characters and emojis)
  • user clicked the purchase button on the checkout page (too long, spaces)
  • evt_123 (not descriptive)

TIP! Create an event naming document shared across marketing, product, and engineering teams to maintain consistency.

Event Parameters Best Practices

  • Revenue: Always send as a number, not a string: revenue: 49.99 not revenue: "$49.99"
  • Currency: Use 3-letter ISO currency codes: USD, EUR, GBP
  • IDs: Send as strings even if numeric: product_id: "12345"
  • Parameter names: Use snake_case for consistency
  • Values: Keep string values under 100 characters

Testing Strategy

Follow this testing checklist before launching:

Table

Test How to Verify Expected Result
SDK loads Console: typeof singularSdk Returns "function"
Init/PageVisit tracked Network tab: Filter "__PAGE_VISIT__" 1 request on page load with status 200
Events fire Trigger event, check Network tab, validate event name ("n" parameter) in payload. New request per event with status 200
Product ID correct Check request payload, validate event name ("i" parameter) in payload. Reverse DNS format
No duplicates Trigger same event 3 times quickly Only 1 request sent
Revenue tracked Check purchase event payload Revenue appears as number
Multiple pages Navigate to different pages Tracking works on all pages
Mobile devices Test on iOS and Android browsers Tracking works on mobile

Performance Optimization

  • Place SDK script in <head> tag for early loading
  • Minimize the number of events tracked per page (focus on meaningful actions, marketing events)
  • Avoid tracking on every keystroke (use debouncing)

Privacy and Compliance

Cookie Disclosure

If you enable Cross-Sub Domain Tracking in your configuration, Singular sets a first-party cookie. You must disclose this in your privacy policy.

Recommended privacy policy language:

We use cookies to track user behavior and improve your website experience. Specifically, we use the following cookies:

singular_device_id - This cookie assigns a unique ID to users who visit our website. This ID helps us track user activities and interactions during their visit without collecting personal information. It allows us to differentiate between users and monitor visitor behavior across different sessions.

  • Duration: 1 year
  • Type: First-party cookie
  • Provider: Singular (https://www.singular.net/privacy-policy/)

GDPR and Privacy Compliance

For GDPR compliance:

  • Set persistentIdentifier: false by default
  • Only enable cookies after user consent
  • Provide users ability to opt-out of tracking
  • Include Singular in your cookie consent banner

Debugging Tools and Techniques

Browser Developer Tools

Console commands for debugging:

// Check if SDK is loaded
typeof singularSdk
// Should return: "function"

// Test firing an event manually
window.singularSdk.event("test");

Migration Checklist

If moving from another analytics platform or upgrading your implementation:

  1. Audit current implementation
    • Document all events currently tracked
    • Identify all pages with tracking code
    • Note any custom parameters or user IDs
  2. Plan new implementation
    • Map old event names to new naming convention
    • Decide on Native JS vs GTM
    • Create testing plan
  3. Implement in stages
    • Start with test/staging environment
    • Test thoroughly (minimum 1 week)
    • Deploy to production during low-traffic period
    • Run parallel with old system for 1-2 weeks
  4. Validate data
    • Compare metrics between old and new systems
    • Check for duplicate tracking
    • Verify all events firing correctly
    • Monitor for 2-4 weeks
  5. Decommission old system
    • Remove old tracking code
    • Update documentation
    • Train team on new system

Getting Help

If you encounter issues not covered in this guide:

  • Contact your Singular Customer Success Manager.
  • Submit a support ticket through the Singular dashboard.
  • Include browser console logs and network request screenshots.
  • Provide your website URL and detailed steps to replicate any issue.

Related Articles