# Troubleshooting

Before going live, test that each traffic source shows the right number. If a number does not swap, work through the checks below in order, then the sections on caching and Google Tag Manager if your site uses them.

## Test each traffic source

Before going live, it's worth testing that your swap groups behave correctly for each traffic source you're tracking. Because Nimbata only swaps a number when the session matches the source assigned to a swap group, you need to simulate each source type to verify it independently.

### Test a Google Ads visit

Nimbata detects paid search sessions by reading the `gclid` parameter that Google appends to ad click URLs when auto-tagging is enabled. To simulate this without clicking a real ad:

- Open a new browser tab.
- Navigate to your website URL and append `?gclid=test`. For example: [`https://www.yoursite.com/?gclid=test`](https://www.yoursite.com/?gclid=test)
- The number assigned to your Google Ads swap group should replace your regular number on the page.

> **Tip:** If this works but real Google Ads clicks don't swap, the issue is likely that `gclid` is being stripped by a redirect. See [the troubleshooting checklist](https://help.nimbata.com/tracking/troubleshooting#numbers-not-swapping) for details.

If auto-tagging is disabled in Google Ads, `gclid` will never be appended to real ad clicks:

- Go to **Google Ads > Admin > Account settings > Auto-tagging**.
- Make sure the checkbox is enabled.

### Test a direct visit

A direct session is one with no referrer and no UTM parameters: a visitor who typed your URL or used a bookmark.

- Open a **new incognito or private window** (this clears any existing session cookies).
- Navigate directly to your website URL with no parameters.
- The number assigned to your **Direct** swap group should appear.

> **Tip:** Use incognito to avoid your own existing session cookie being picked up, which could cause Nimbata to show a number from a previous visit rather than a fresh direct session.

### Test an organic visit

An organic session arrives from a search engine with a referrer header but no paid click identifier.

- Open a **new incognito or private window**.
- Go to Google (or another search engine) and search for your business by name.
- Click through to your site from the organic search results.
- The number assigned to your **Organic** swap group should appear.

Alternatively, you can simulate the referrer manually by navigating from [`https://www.google.com`](https://www.google.com) to your site in the same browser tab, which passes Google as the referrer.

### Test a custom UTM source

If you have a swap group assigned to a custom parameter source (for example, a specific campaign):

- Open a new incognito window.
- Navigate to your website URL with the UTM parameters that match your swap group configuration, for example: [`https://www.yoursite.com/?utm_source=facebook_ads&utm_medium=ppc&utm_campaign=spring-promo`](https://www.yoursite.com/?utm_source=facebook_ads\&utm_medium=ppc\&utm_campaign=spring-promo)
- The number assigned to that swap group should appear.

### Confirm visits in Nimbata

After each test visit, check [Dashboards > Visit Stats](https://app.nimbata.com/dashboard/visit-stats) to confirm Nimbata recorded the session under the correct channel. The **Visitors** row should increment for the channel you just tested.

Troubleshooting: [Numbers not swapping](https://help.nimbata.com/tracking/troubleshooting#numbers-not-swapping)\
Detailed guide: [Set up DNI step by step](https://help.nimbata.com/tracking/dni-setup#set-up-dni-step-by-step)\
Detailed guide: [Set up swap groups](https://help.nimbata.com/tracking/swap-groups#set-up-swap-groups)

## Numbers not swapping

Your Nimbata DNI script is installed but the phone number on your website isn't changing. This section covers every known cause, from the most common to the most obscure, in the order you should check them.

**Start here:** visit your website and add `?gclid=test` to the end of the URL. For example: [`https://www.yourwebsite.com/?gclid=test`](https://www.yourwebsite.com/?gclid=test)

- **Number swaps:** the script is working. The issue is with your real traffic conditions. Jump to check 4.
- **Number does not swap:** the script itself is the problem. Start at check 1.

### 1. The script is not installed or not loading

The most common reason numbers don't swap is that the script hasn't been placed on the page, or it's loading on some pages but not others.

- Open your browser's developer console (**F12 > Console**) and type `nimbata`.
- If you see `nimbata is not defined` or an error, the script is not loading on that page.
- Check that the script appears in the page source (**Ctrl+U**) on the page you're testing.
- Use Nimbata's built-in **Website URL checker** under [Tracking > Tracking Code](https://app.nimbata.com/tracking/tracking-code) to confirm detection.
- If deployed via GTM, confirm your tag's trigger is set to **All pages** (or your intended scope) and fires on **DOM Ready**.

**Common causes:**

1. The script was added to the homepage only.
2. The GTM tag has a scoped trigger.
3. The WordPress plugin was deactivated during a theme or plugin update.

### 2. There is no phone number in the page for the script to replace

Nimbata's DNI script works by replacing a number that already exists in your page HTML. It cannot inject a number into a blank space. If the number is rendered dynamically after load (via JavaScript, a page builder, or a CRM widget), or is simply absent from the DOM when the script runs, nothing will swap.

- Right-click the phone number on your page and select **Inspect**.
- Is the number visible as plain text in the DOM, or does the element appear empty?
- If the number is injected dynamically, enable **SPA mode** in [Tracking > Tracking Code](https://app.nimbata.com/tracking/tracking-code) so the swap logic re-runs after DOM changes.
- If the number is inside an `<iframe>`, the script cannot reach it; see check 7.
- Use the span tag method to give the script an explicit, format-independent target, with your regular number inside (use `nimbata_number_1`, `nimbata_number_2` and so on when you have two or more swap groups):

```html
<span class="nimbata_number">555-555-5555</span>
```

Detailed guide: [Use span tags](https://help.nimbata.com/tracking/swap-targets#use-span-tags)

### 3. The swap target doesn't match the number on your page

Nimbata needs to know which number on your page to replace. If your swap target doesn't match the number exactly as it appears in the HTML, including spacing, dashes, and parentheses, the script silently does nothing.

- Go to [Tracking > Tracking Code](https://app.nimbata.com/tracking/tracking-code).
- Compare your swap target to the number in your page source character by character.
- Your website may display `(555) 123-4567` while your swap target specifies `555-123-4567`. These do not match.
- Update your swap target to match the exact string, or switch to the span tag method to eliminate format-matching issues entirely.

Detailed guide: [Swap target formatting rules](https://help.nimbata.com/tracking/swap-targets#formatting-rules)

### 4. The `gclid` parameter is being stripped by a redirect or plugin

If `?gclid=test` works but real Google Ads clicks don't swap, the `gclid` parameter is being removed somewhere between the ad click and the page load.

- Click one of your own Google Ads and check whether `gclid=` appears in the browser address bar once the page loads.
- If it doesn't, something is stripping it.

**Common causes:**

1. HTTP > HTTPS or www > non-www redirects that drop query strings.
2. A CDN or caching plugin (Cloudflare, WP Rocket, W3 Total Cache, Varnish) stripping or ignoring query string parameters.
3. A trailing-slash redirect mismatch between your ad's final URL and your actual page URL.

Fix the redirect to preserve the full query string. Once `gclid=` survives to the page, swapping will work automatically.

Detailed guide: [Caching and CDNs](https://help.nimbata.com/tracking/troubleshooting#caching-and-cdns)

### 5. Auto-tagging is disabled in Google Ads

Nimbata's Google Ads swap groups rely on Google's auto-tagging to append `gclid` to ad URLs. If auto-tagging is off, no `gclid` is ever sent.

- In Google Ads, go to **Admin > Account settings > Auto-tagging** and confirm the checkbox is enabled.

### 6. The tracking source doesn't match your session

If your swap group source is set to a specific channel, for example **Online paid**, the number only swaps for sessions Nimbata attributes to that channel. If you're testing with a direct visit and the source is set to paid search, the number won't swap.

- Go to [Tracking > Tracking Code](https://app.nimbata.com/tracking/tracking-code).
- Check the **Source** setting on your swap group.
- Set it to **All online sources** for general testing, or use `?gclid=test` to simulate a paid search session.
- If you have multiple swap groups all set to **All online sources**, they will conflict; only one will fire unpredictably.
- Assign each swap group its correct, distinct source.

Detailed guide: [Test each traffic source](https://help.nimbata.com/tracking/troubleshooting#test-each-traffic-source)

### 7. The phone number is inside an `<iframe>`

Nimbata's script runs in your main page's JavaScript context and cannot cross iframe boundaries. This affects phone numbers inside embedded contact forms (Typeform, HubSpot forms, JotForm, Calendly), click-to-call widgets, and live chat tools that display a number.

- Move the phone number out of the iframe and onto the main page.
- If the widget is a third-party embed you don't control, contact Nimbata support to explore alternatives.

### 8. The tracking number has no call flow assigned

Even if the script correctly swaps the number on the page, calls will not route if the tracking number has no call flow assigned.

- Go to [Tracking > Numbers](https://app.nimbata.com/tracking/numbers).
- Check the **Call flow** column for your tracking number.
- If it is blank or shows no flow, go to [Call handling > Call Flows](https://app.nimbata.com/call-handling/call-flows).
- Create or open a call flow.
- Assign your tracking number to it.

### 9. A cookie consent manager is blocking the script

Consent banners (OneTrust, Cookiebot, CookieYes, Axeptio, and similar) can delay or entirely block JavaScript execution until the visitor accepts cookies. If Nimbata is categorized as a tracking or analytics script, it will not fire for visitors who decline, and the number will not swap for those sessions.

- Open your site in a fresh browser session without accepting the cookie banner.
- Does the number swap?
- Open the browser console and look for blocked scripts.
- Review how your consent manager categorizes the Nimbata script.
- If compliant with your privacy policy, moving it to a **Functional** or **Necessary** category will resolve this.

> **Warning:** Consult your legal team before changing cookie categorization.

### 10. A browser cache or ad blocker is interfering

- Test in an incognito window with all extensions disabled to rule out browser cache, stored cookies, and ad blockers.

### Still not working?

Submit a request via **? > Submit a request** in your Nimbata dashboard. Include:

- Your website URL
- The tracking number that should be swapping (with country code)
- Whether `?gclid=test` works or not
- A screenshot of your swap target configuration from [Tracking > Tracking Code](https://app.nimbata.com/tracking/tracking-code)
- The browser console output (F12 > Console) when you visit the page
- Whether you have a cookie consent banner, and if so, which tool

Detailed guide: [Set up DNI step by step](https://help.nimbata.com/tracking/dni-setup#set-up-dni-step-by-step)\
Detailed guide: [Set up swap groups](https://help.nimbata.com/tracking/swap-groups#set-up-swap-groups)\
Detailed guide: [Use span tags](https://help.nimbata.com/tracking/swap-targets#use-span-tags)\
Detailed guide: [Caching and CDNs](https://help.nimbata.com/tracking/troubleshooting#caching-and-cdns)

## Caching and CDNs

The Nimbata DNI script must execute fresh on every page visit. It needs to read the current visitor's session and source in real time to decide which number to show. If your site is serving a cached copy of the page or script, the swap may fail silently or behave inconsistently between visitors.

### Why caching causes swap failures

Caching works by storing a copy of your page (or its assets) and serving that copy to subsequent visitors instead of generating a fresh response. This is great for performance but problematic for DNI when:

- The **page HTML is cached** with the original static number baked in, and Nimbata never gets a chance to replace it.
- The **Nimbata script itself is cached** and served with a stale version that doesn't reflect your latest swap group or tracking code configuration.
- **Query string parameters** (like `?gclid=test`) are stripped or ignored by the cache, so Nimbata never receives the signal needed to identify the visit source.

### Cloudflare

Cloudflare's caching can strip query strings, cache page HTML, and delay script updates from reaching visitors.

**Check and fix:**

- In your Cloudflare dashboard, go to **Caching > Configuration**.
- Make sure **Query String** handling is set to preserve all parameters, not to ignore or strip them.
- A setting that strips query strings will prevent `gclid` and UTM parameters from reaching your page.

If Cloudflare is caching your page HTML:

- Create a **Cache Rule** to bypass caching for pages containing your tracking numbers.

If you recently updated your Nimbata script:

- Go to **Caching > Purge cache**.
- Purge the affected URLs so visitors receive the updated version.

Check Rocket Loader too:

- Check whether **Rocket Loader** is enabled under **Speed > Optimization**.
- Rocket Loader defers JavaScript execution and can cause the DNI script to fire after the page has already rendered.
- This results in a visible number flash or missed swap.
- Disable it for the Nimbata script or for the site if DNI swaps are unreliable.

> **Tip:** Cloudflare's **Auto Minify** feature for JavaScript can occasionally corrupt small scripts. If you suspect this, disable Auto Minify for JS and test again.

### WordPress caching plugins

WordPress caching plugins (WP Super Cache, W3 Total Cache, WP Rocket, LiteSpeed Cache, and others) generate static HTML copies of your pages. If the static copy contains your regular number, Nimbata will never see the original page load and the swap won't fire.

**Check and fix:**

- Open your caching plugin's settings.
- Find the **excluded pages** or **cache exclusion** list.
- Add any pages that contain your tracking numbers to the exclusion list.

Alternatively:

- Look for a setting to **exclude scripts from deferral**.
- Add the Nimbata script URL so it is not deferred or async-loaded in a way that delays execution.

In WP Rocket specifically:

- Go to **File Optimization**.
- Add the Nimbata script to the **Excluded JavaScript Files** list.
- This will prevent it from being minified, combined, or deferred.

After making changes, clear your plugin's cache and test in an incognito window.

### Server-level and hosting cache

Some hosting providers (SiteGround, Kinsta, WP Engine, and others) apply server-side caching independently of any plugin. This cache sits below WordPress and is not controlled by caching plugins.

**Check and fix:**

- Log into your hosting control panel.
- Look for a caching section (often called "Dynamic Cache", "Full Page Cache", or similar).
- Flush the server cache after any changes to your Nimbata script or swap group configuration.
- If your host supports cache exclusion rules, exclude pages containing your tracking numbers from full-page caching.
- Contact your hosting support if you cannot locate the cache controls.
- Most managed WordPress hosts can add exclusion rules for specific pages or query strings on request.

### Confirm a caching issue

- Open your page in an incognito window.
- Append `?gclid=test&nocache=1` to the URL.
- The second parameter forces a unique URL that most caches won't have stored.
- If the number swaps with this URL but not without it, a cache is serving a stored version of the page without the query string.
- Compare the page source (Ctrl+U) of the cached version vs. a forced-fresh version to see whether the static number is baked into the HTML.

Troubleshooting: [Numbers not swapping](https://help.nimbata.com/tracking/troubleshooting#numbers-not-swapping)\
Detailed guide: [Set up DNI step by step](https://help.nimbata.com/tracking/dni-setup#set-up-dni-step-by-step)\
Detailed guide: [Install with Google Tag Manager](https://help.nimbata.com/tracking/script-installation#install-with-google-tag-manager)

## Google Tag Manager issues

These are the most common reasons the Nimbata DNI script fails when deployed via Google Tag Manager (GTM), and how to fix each one.

> **Note:** For setup instructions, see [Install with Google Tag Manager](https://help.nimbata.com/tracking/script-installation#install-with-google-tag-manager).

### The number is not swapping at all

**Check 1. Confirm the GTM container is published**

Changes in GTM do not take effect until the workspace is submitted and published. If you added or updated the Nimbata tag but did not click **Submit**, the change is not live.

- In GTM, click **Submit** and then **Publish**.
- Revisit your website and test again.

**Check 2. Confirm the tag trigger fires on all pages**

If the trigger is scoped incorrectly, the tag only fires on specific pages, often just the homepage.

- In GTM, open the Nimbata tag.
- Check the trigger. It should fire on **Page View - DOM Ready > All DOM Ready Events**.
- If it is scoped to a URL match or specific page, update it to fire on all pages (or all pages where your number appears).

**Check 3. Confirm Tag firing options is set to Once per event**

- In the Nimbata tag, expand **Advanced Settings**.
- Set **Tag firing options** to **Once per event**.
- Save and republish.

**Check 4. Confirm the DNI ID is correct**

- Go to [Tracking > Tracking Code](https://app.nimbata.com/tracking/tracking-code) in Nimbata.
- Copy the DNI ID (the value highlighted in green in the script tag).
- In GTM, open the Nimbata tag and confirm this value is entered in the **Dynamic Number Insertion ID** field exactly as it appears.

**Check 5. Click Save & Publish in Nimbata first**

The Nimbata script must be saved and published in your Nimbata account before GTM can load it.

If you made changes to your swap targets or advanced settings but did not click **Save & Publish** in Nimbata, those changes are not live even if GTM is correctly configured.

- Go to [Tracking > Tracking Code](https://app.nimbata.com/tracking/tracking-code).
- Click **Save & Publish**.
- Then retest.

### The number swaps on the homepage but not on other pages

This is almost always a trigger scope issue.

- Open the Nimbata tag in GTM.
- Change the trigger from a URL-specific page view to **All DOM Ready Events**.
- Submit and publish the container.

### The number swaps on a direct visit but not on Google Ads clicks

The DNI script is loading correctly, but the Google Ads swap group is not triggering. The most likely cause is that the `gclid` parameter is being stripped.

- Click one of your own Google Ads and check whether `gclid=` appears in the browser address bar after the page loads.
- If it does not, a redirect or caching layer is removing it.

Common causes include HTTP-to-HTTPS redirects, www to non-www redirects, and CDN or caching plugins (Cloudflare, WP Rocket, Varnish) that strip query string parameters.

- Fix the redirect chain to preserve query strings.
- If you are using Cloudflare or a caching plugin, confirm it is not configured to ignore or strip URL parameters.

Detailed guide: [Caching and CDNs](https://help.nimbata.com/tracking/troubleshooting#caching-and-cdns)

### The number swaps but then disappears or reverts

This happens on Single Page Applications or sites with dynamic content that re-renders after the swap has already fired.

- Open the Nimbata tag in GTM and confirm it fires on **DOM Ready**, not on **Window Loaded** or a custom event that fires before the full DOM is available.
- In Nimbata, go to [Tracking > Tracking Code](https://app.nimbata.com/tracking/tracking-code) and enable **SPA mode** under Advanced Settings.
- Save & Publish, then republish the GTM container.

### GTM preview shows the tag firing but the number still does not swap

The tag is loading but the swap itself is failing. This is a Nimbata configuration issue rather than a GTM issue.

- Confirm your swap target in [Tracking > Tracking Code](https://app.nimbata.com/tracking/tracking-code) matches the phone number in your page source exactly.
- Use the built-in website URL checker in the same page to test detection.

Detailed guide: [Swap target formatting rules](https://help.nimbata.com/tracking/swap-targets#formatting-rules)

### A consent management platform is blocking the tag

Consent banners (OneTrust, Cookiebot, CookieYes, and similar) can prevent GTM tags from firing until the visitor accepts cookies. If Nimbata is categorized as a tracking or analytics script, it will be blocked for visitors who decline.

- Open your site in a fresh browser session without accepting the cookie banner.
- Open the browser console (**F12 > Console**) and check whether the Nimbata script loads.
- Review how your consent tool categorizes the Nimbata GTM tag.
- If appropriate and compliant with your privacy policy, re-categorize it as Functional or Necessary.

> **Warning:** Consult your legal team before changing cookie categorization.

### Still not resolved?

Submit a request via **? > Submit a request** in your Nimbata dashboard. Include:

- Your website URL and which page(s) the number should swap on.
- A screenshot of your GTM tag configuration (trigger, firing options, DNI ID).
- Whether `?gclid=test` appended to your URL produces a swap.
- The output of your browser console (**F12 > Console**) when visiting the page.

Detailed guide: [Install with Google Tag Manager](https://help.nimbata.com/tracking/script-installation#install-with-google-tag-manager)\
Detailed guide: [Numbers not swapping](https://help.nimbata.com/tracking/troubleshooting#numbers-not-swapping)\
Detailed guide: [Advanced settings](https://help.nimbata.com/tracking/advanced-settings#script-settings)
