Troubleshooting
Start with the install check. It shows what twelvebit has received for the site:
sh
curl -sS https://twelvebit.app/api/v1/install-check -H "Authorization: Bearer $TWELVEBIT_API_KEY"Then add data-debug="true" to the script tag and open the browser console. When the script decides not to track, it logs the reason, for example [twelvebit] not tracking: localhost.
Nothing arrives#
| Cause | What you see | Fix |
|---|---|---|
You test on localhost, 127.*, *.local or *.test | Console (with data-debug): not tracking: localhost | Add data-allow-localhost="true" while you test. Remove it before production. |
| This browser is excluded | not tracking: ignored by this browser | Run localStorage.removeItem("twelvebit_ignore") in the console. |
| Automated browser | not tracking: automation | Playwright, Puppeteer, Selenium and Cypress set navigator.webdriver. Test in a normal browser. |
| The page is opened as a file | not tracking: file | Serve the page over HTTP. |
| An ad blocker blocks the script or the request | The request to /js/script.js or /api/e fails in the Network tab | Serve the script from your domain. See Proxy. |
| The page host is not the site's domain | POST /api/e answers 403 domain not allowed | Use the root domain in the dashboard and in data-domain, or add the other domain in the site settings (extra domains). Subdomains of the site domain are always allowed. |
| Wrong site id | POST /api/e answers 404 unknown site | Copy the id from the site's setup page. It starts with tb_. |
| Content Security Policy | A CSP error in the console | Add https://twelvebit.app to script-src and connect-src, or proxy the script. |
| The visit is excluded | POST /api/e answers 202 but no visit shows | Check the site's exclusions: IP addresses, paths, hostnames and countries. |
| The request looks like a bot | POST /api/e answers 202, nothing shows | Server-side bot filtering drops known bot user agents. Use a normal browser. |
Events arrive, but not the ones I expect#
- Goal names are changed to lower case and cut to 64 characters.
Signuparrives assignup. data-tb-goalsends on click. Check that no other handler stops the event before the document sees it (the script listens in the capture phase, so most handlers do not block it).- Calls made before the script has loaded are lost unless you add the queue stub.
- Compare your code with the plan:
npx -y https://twelvebit.app/cli/twelvebit-cli.tgz check.
Revenue does not show a source#
- The checkout must carry
twelvebit_visitor_idandtwelvebit_session_idin its metadata. Read the_tb_vidand_tb_sidcookies on the server when you create the checkout. See Revenue. - In cookieless mode there are no cookies. Use
identifywith the customer's email before the checkout, so twelvebit can match the payment by email. - The provider must be connected in the site's revenue settings, or you must send payments with
POST /api/v1/payments.
Every visitor shows the same city#
Your proxy sends the requests from its own address. See Proxy.
Still stuck#
Send the output of the install check and the console lines with data-debug="true" to support.