Overview
The Singular Web SDK enables you to track user visits, conversions, and events on your website. When implemented correctly, Singular attributes website conversions to the marketing campaigns that drove those visits, giving you complete visibility into your web marketing performance.
INFO: Web Attribution is an enterprise feature. Contact your Customer Success Manager to enable this feature for your account.
How Web Attribution Works
The Singular Web SDK uses JavaScript to identify users by their browser and track their journey through your website. When a user visits your site, the SDK determines whether this is a first-time visit or a returning session following a web campaign.
Key capabilities include:
- Tracking page visits and user sessions
- Recording conversion events (purchases, signups, subscriptions)
- Measuring custom events specific to your business
- Attributing conversions to marketing campaigns
- Cross-device attribution when combined with mobile SDKs (Requires Cross-Device feature subscription)
Before You Begin
Before implementing the Web SDK, ensure you have the following:
| Requirement | Description |
|---|---|
| SDK Key | Your Singular SDK Key. Find this in your Singular account under Developer Tools > SDK Integration > SDK Keys. |
| Website Access | Permission to add JavaScript code to your website's HTML, either directly or through a tag management system. |
| Event Planning | A documented list of events you want to track (e.g., Purchase, Add to Cart, Signup). |
| Privacy Policy | Updated privacy policy if you enable cross-subdomain tracking (which uses cookies). |
Choosing Your Integration Method
Singular offers two integration options. Choose the method that best fits your technical setup:
Native JavaScript Implementation
Best for: Teams with direct access to website code, developers comfortable with JavaScript, or situations where you want maximum control and minimal third-party dependencies.
Advantages:
- Not blocked by common ad blockers
- Faster page load performance
- More reliable tracking
- Direct control over implementation
- Banners Support
Disadvantages:
- Requires code changes to your website
- Updates require developer involvement
TIP! Singular recommends the Native JavaScript implementation for most use cases because it provides better reliability and is less likely to be blocked by ad blockers.
Google Tag Manager Implementation
Best for: Teams already using Google Tag Manager, marketing teams who need to make changes without developer assistance.
Advantages:
- No direct code changes needed
- Easier for non-technical teams to manage
- Changes can be deployed through GTM interface
Disadvantages:
- Often blocked by ad blockers
- Dependent on GTM loading correctly
- Additional complexity in debugging
- No Banner Support
IMPORTANT! Only implement ONE method. Using both Native JavaScript and Google Tag Manager simultaneously will cause duplicate tracking and inflated metrics. Singular does not deduplicate events automatically.
Understanding Key Concepts
Product ID (App Bundle ID)
The Product ID identifies your website to Singular. It must be in reverse DNS notation, similar to mobile app bundle identifiers.
Format: com.website-name
Examples:
- Correct:
com.acme - Incorrect:
acme-store - Incorrect:
www.acme.com
TIP! Use the same Product ID across all pages of your website. If you have multiple subdomains associates with the same website: (www.acme.com,shop.acme.com,store.acme.com) you should used the same Product ID com.acme for all of them. Websites or web properties with different domains: (www.site1.com,www.site2.com,www.site3.com), should be create using a separate Product ID for each in your Singular account and treat them as separate Apps.
Sessions and Re-engagement
What is a Session?
A session in Singular tracking represents a distinct period of user engagement with your website. Unlike HTTP sessions (which maintain technical state like login status across page requests), Singular sessions are analytics-focused and measure user activity patterns for attribution and engagement metrics.
When Sessions Are Created
Singular automatically creates a new session when:
- A user has been inactive for 30 minutes or more (default session timeout)
- A user visits with new campaign parameters (different ad source)
- A user arrives from a different referring website
Session Timeout vs. Re-engagement Inactivity Window
It's important to understand two distinct time-based settings:
Session Timeout (SDK-Level)
- Controls when a new session begins
- Default: 30 minutes for WebSDK, 60 seconds for mobile SDKs
- Configurable via SDK initialization
- Resets each time user activity is detected
- Used for session-based metrics (session count, session duration, etc.)
Re-engagement Inactivity Window (Platform-Level)
- Controls when re-engagement attribution is eligible
- Default: 7 days
- Configured per app in Settings > Apps
- Determines the minimum time a user must be inactive before a retargeting campaign click counts as a re-engagement event
- Does not affect regular session creation
Example Scenario
Consider a user who:
- Visits your site, then leaves after 5 minutes
- Returns 45 minutes later via a retargeting ad
What happens:
- A new session is created (exceeded 30-minute session timeout)
- No re-engagement attribution occurs (user was not inactive for 7 days)
- The visit is tracked as a normal session cohorted to the previous attribution source
If the same user returned after 10 days of inactivity via a retargeting ad:
- A new session is created
- Re-engagement attribution is triggered (exceeded 7-day inactivity window)
- The event is recorded as a re-engagement with proper attribution to the retargeting campaign
Configuration Options
Customizing Session Timeout:
The session timeout can be adjusted during SDK initialization. Review the WebSDK Initialization options in our documentation relevant to your implementation method: Native JavaScript or Google Tag Manager
Customizing Re-engagement Inactivity Window:
The Re-engagement Inactivity Window for re-engagement attribution can be customized per app by navigating to Settings > Apps and expanding the "Show Advanced Settings" options in the Singular platform. Adjust this based on your typical user engagement patterns and retargeting campaign strategies.
INFO: The inactivity period can be customized if needed. Read more about it in the Re-engagement FAQ.
Events: Conversion vs. Standard
Singular distinguishes between two types of events:
Conversion Events: Business-critical actions that indicate success (purchases, subscriptions, signups, downloads). These appear in attribution reports and ROI calculations.
Standard Events: Supporting actions that help understand user behavior (page views, add to cart, video plays). These appear in raw data reports and help analyze user journeys.
TIP! Configure which events are classified as "conversion events" in your Singular account settings. This ensures they appear in the correct reports.
Privacy and Cookie Usage
By default, Singular does not use cookies. However, if you enable cross-subdomain identifier persistence, Singular sets a first-party cookie to maintain user identity across subdomains.
Cookie Details (when enabled):
| Property | Value |
|---|---|
| Cookie Name | singular_device_id |
| Purpose | Assigns a unique ID to users to track their activities and interactions across sessions without collecting personal information |
| Duration | 1 year |
| Type | First-party cookie (set on your domain) |
| Privacy Policy | https://www.singular.net/privacy-policy/ |
IMPORTANT! If you enable cross-subdomain tracking, update your website's privacy policy to disclose the use of the singular_device_id cookie.
Next Steps
- Choose your integration method (Native JavaScript or Google Tag Manager)
- Follow the step-by-step implementation guide for your chosen method
- Test your implementation using the validation steps provided
- Review the Troubleshooting guide for best practices