Common Integration Issues

Common Integration Issues

If tracking signals are missing or inconsistent, the cause is usually related to configuration setup rather than a platform failure.

This page helps you quickly identify whether the problem comes from a setup mistake or a technical integration issue.

Common Configuration Mistakes

These situations are caused by incorrect setup decisions and can usually be fixed quickly.

Incorrect Tracking Key

Tracking will not work if the SDK is initialised with the wrong key.

Check that:

• you copied the publishable key from your own OneLence workspace
• the key is complete and not modified
• browser tracking uses the publishable key (not the server secret key)

After updating the key, refresh the page and test again.

Script Installed in the Wrong Location

Tracking may not start if the SDK snippet is not loaded globally.

Verify that:

• the snippet is placed in the global site header or global script area
• the snippet loads before users interact with the page
• the snippet is not installed only on a single page

For website builders or WordPress, confirm installation in site-wide settings.

Consent Blocking Tracking

If consent mode is enabled, tracking will only start after the visitor accepts cookies.

Typical symptoms:

• no page view signals
• visitor ID not created
• attribution parameters missing

Check that:

• your consent banner triggers Mark.setConsent('granted')
• testing sessions include accepted consent
• require_consent configuration matches your privacy setup

No Trackable User Actions

Tracking may be working correctly but no meaningful events have occurred.

Examples:

• user only loads one page and leaves
• conversion events are not yet configured
• interaction tracking has not been added

During testing, trigger at least one action such as:

• clicking a CTA button
• starting signup
• completing checkout step

Using the Wrong SDK Environment

Tracking can fail if the SDK type does not match the runtime environment.

Typical mistakes:

• using the browser Mark SDK inside backend or Node.js code
• using the Node/server SDK inside browser pages

Always use:

• browser snippet or browser SDK → for website tracking
• server SDK → for backend event sending

Technical Integration Issues

These situations relate to signal transmission or identity linkage.

Server and Browser Identity Not Linked

In hybrid tracking setups, attribution may fail if browser and backend events cannot be joined.

Common causes:

• visitor ID not passed to backend systems
• server events use a different site_id
• webhook events processed before identity exists

Ensure that:

• browser identity context is sent to your backend
• server events reuse the same tracking identifiers
• event names are consistent across environments

JavaScript Errors Blocking SDK Execution

Tracking may silently fail if other scripts cause runtime errors.

Recommended checks:

• open browser developer console
• verify no critical JavaScript errors appear
• confirm tracking network requests are successfully sent

Common Error Codes

If you see error responses in network logs or server integrations, use the table below for guidance.

Recommended Quick Diagnostic Flow

If tracking still appears inactive:

1. open your site in a private browser window
2. disable any active adblockers or privacy extensions
3. accept the cookie banner
4. trigger a meaningful action
5. check the dashboard after a short delay

Most signal visibility issues are resolved after correcting one of the situations above.