> ## Documentation Index
> Fetch the complete documentation index at: https://agentref.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug Mode

> Inspect tracking state, diagnose attribution issues, and troubleshoot the AgentRef script with built-in debug tools.

Debug mode gives you a console readout of the tracking script's state – what cookies are set, what parameters were detected, and whether anything went wrong during initialization.

## Enabling debug mode

You can enable debug mode in two ways:

**Option 1: URL parameter (temporary, no code change)**

Append `?agentref_debug=1` to any page URL on your site:

```
https://yoursite.com/pricing?via=abc123&agentref_debug=1
```

Open the browser console – you'll see an `[AgentRef]` log entry immediately after the script initializes.

**Option 2: Script attribute (always-on)**

Add `data-debug="true"` to your script tag to log on every page load:

```html theme={null}
<script
  src="https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID"
  data-debug="true"
  async
></script>
```

<Warning>
  Do not ship `data-debug="true"` to production. It logs attribution state to the browser console on every page visit, which is noisy for real users and may expose referral context on shared machines.
</Warning>

## What debug mode shows

The console output is the return value of `window.AgentRef.getDebugInfo()`. Here is an example:

```json theme={null}
{
  "params": {
    "referralParam": "ref",
    "referralCode": "abc123",
    "clickToken": null,
    "debug": true,
    "subIds": { "sub1": null, "sub2": null, "sub3": null, "sub4": null, "sub5": null },
    "utm": { "utmSource": "twitter", "utmMedium": "social", "utmCampaign": null, "utmTerm": null, "utmContent": null },
    "adClickIds": { "gclid": null, "fbclid": null, "msclkid": null, "ttclid": null, "liFatId": null }
  },
  "cookies": {
    "clickToken": "clk_a1b2c3d4e5",
    "source": "script_direct",
    "programId": "550e8400-e29b-41d4-a716-446655440000",
    "visitorId": "v_k8m2n4p6q7",
    "timestamp": "1711234567890"
  },
  "lastResolution": {
    "clickToken": "clk_a1b2c3d4e5",
    "programId": "550e8400-e29b-41d4-a716-446655440000",
    "source": "script_direct"
  },
  "trackingScope": {
    "trackingDomain": "yoursite.com",
    "mode": "root"
  },
  "warnings": []
}
```

### Field reference

| Field                 | What it tells you                                                                     |
| --------------------- | ------------------------------------------------------------------------------------- |
| `params.referralCode` | The affiliate code detected in the URL (`null` if none)                               |
| `params.clickToken`   | Pre-existing click token from a redirect URL (`null` for direct clicks)               |
| `cookies.clickToken`  | The `agentref_cid` cookie value – this is what goes into Stripe metadata              |
| `cookies.programId`   | The `agentref_pid` cookie – confirms which program the current attribution belongs to |
| `trackingScope.mode`  | `"root"` = cookies scoped to root domain; `"host"` = scoped to exact hostname only    |
| `warnings`            | Array of warning codes if anything went wrong (empty = clean init)                    |

### Warning codes

| Warning                              | Meaning                                                          |
| ------------------------------------ | ---------------------------------------------------------------- |
| `consent_pending`                    | Consent is required but not yet granted – tracking was skipped   |
| `host_outside_website_domain`        | The current hostname doesn't match your program's website domain |
| `cleanup_failed`                     | URL parameter cleanup via `history.replaceState` failed          |
| `stripe_payment_link_rewrite_failed` | Could not append `client_reference_id` to a Stripe Payment Link  |
| `direct_click_failed`                | The click recording request to AgentRef failed                   |
| `tracking_verify_failed`             | The verification request failed                                  |

## Calling `getDebugInfo()` manually

You can call it any time from the browser console:

```js theme={null}
window.AgentRef.getDebugInfo()
```

This is useful after navigation, after granting consent, or after a manual `AgentRef.refresh()` call – any time you want to see the current state without reloading the page.

## Troubleshooting checklist

<Accordion title="Script is not loading">
  1. Open the Network tab in DevTools and filter for `script.js`. Check the response status.
  2. A `404` means your `?pid=` value is invalid or the program does not exist. Verify the program ID in your AgentRef dashboard.
  3. A `400` response with `// Missing program ID` means the `?pid=` query string is missing entirely.
  4. Check for Content Security Policy (CSP) headers blocking `https://www.agentref.co`. Add it to your `script-src` and `connect-src` directives.
</Accordion>

<Accordion title="Cookies are not being set">
  1. Enable debug mode and check `params.referralCode` – if it's `null`, no referral parameter was found in the URL. Make sure your affiliate link includes `?via=<code>` or another supported alias.
  2. Check `warnings` – `consent_pending` means consent mode is enabled and the visitor hasn't granted consent yet.
  3. Check `trackingScope.mode` – if it's `"host"` and your checkout is on a subdomain, cookies may not be shared across subdomains. Set your website URL in program settings to the root domain (e.g., `yoursite.com` not `www.yoursite.com`).
  4. If the referral code is present but no click token is in cookies, the click recording request may have failed. Check the Network tab for a failed POST to `/api/tracking/click`.
</Accordion>

<Accordion title="Clicks are tracked but conversions are not created">
  1. Verify that `getCheckoutMetadata()` returns a non-empty object before checkout. Call it from the console: `window.AgentRef.getCheckoutMetadata()`.
  2. Confirm the metadata is being passed to Stripe. Check the session object in your Stripe dashboard – look for `agentref_cid` in the metadata fields.
  3. For Payment Links, confirm the link on your page has `data-agentref-instrumented="true"` after the script loads – this attribute is set by the script when it successfully instruments a link.
  4. Check that your Stripe Connect integration is active in AgentRef. If the webhook is not receiving events, no conversions will be created.
</Accordion>

<Accordion title="Attribution is set but the wrong affiliate gets credit">
  AgentRef uses last-click attribution. If a visitor clicked multiple affiliate links before purchasing, the most recent click wins.

  Coupon codes take priority over click tokens – if the customer uses a coupon linked to a different affiliate, that affiliate gets credit regardless of which link the visitor clicked.

  Check the conversion detail in your dashboard to see which attribution method was used (click token vs. coupon code).
</Accordion>