SDK

To dynamically manage A/B testing and personalized elements on your website, you need to integrate the pagent SDK script directly into your webpage. Choose one of two loading strategies and follow the steps below.

1. Pick a loading strategy

Strategy	When to use	Requirements
Synchronous (blocking)	You want the simplest setup and can tolerate the script being parsed during the initial render.	Only the SDK tag inside `<head>`.
Asynchronous (non-blocking)	You need the main thread free during the first paint (e.g. performance-critical landing pages).	A short anti-flicker snippet plus the SDK tag with `async`.

Both variants require the data-client-key attribute that you will find in your pagent workspace.

2. Synchronous loading

Add the tag as early as possible inside the <head> tag:

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY">
  </script>
</head>

This ensures the SDK executes during the initial render cycle, preventing visual flashes. (We recommend against loading the SDK through Google Tag Manager or similar tools that inject scripts after the page has loaded, as this may cause flickering.)

3. Asynchronous loading with anti-flicker

Paste the anti-flicker snippet right after the opening <head> tag:

<script>
    (() => {
        const MAX_WAIT = 500; // Your maximum wait time for our script to load
        const STYLE_ID = "pagent-body";
        if (window.pagentInit) return;
        window.pagentInit = true;

        const head = document.head || document.getElementsByTagName("head")[0];
        if (!head || document.getElementById(STYLE_ID)) return;

        const style = document.createElement("style");
        style.id = STYLE_ID;
        style.textContent = "body{opacity:0 !important; pointer-events:none !important}";
        head.appendChild(style);

        let shown = false;
        let timeoutId = setTimeout(() => display("timeout"), MAX_WAIT);

        function display(cause) {
            if (shown) return;
            if (style.parentNode) style.parentNode.removeChild(style);
            shown = true;
            if (timeoutId) {
                clearTimeout(timeoutId);
                timeoutId = 0;
            }
            window.pagentTimeout = cause === "timeout";
        }
        
        window.pagentDisplayPage = () => display("engine");
    })();
</script>

Feel free to lower MAX_WAIT if you can accept the risk that variations might not be applied in time. Note: if the SDK loads while the snippet’s curtain is still up, it takes over the curtain and its own resolved timeout decides when the page shows (see section 6), so a hydration wait is not cut short by MAX_WAIT. MAX_WAIT still applies as the fallback for cases where the SDK itself fails to load. If you prefer a minified version:

<script>
  ((e,t,n)=>{const o="pagent-body";if(e.pagentInit)return;e.pagentInit=!0;const i=t.head||t.getElementsByTagName("head")[0];if(!i||t.getElementById(o))return;const a=t.createElement("style");a.id=o,a.textContent="body{opacity:0 !important; pointer-events:none !important}",i.appendChild(a);let p=!1,d=setTimeout((()=>m("timeout")),n);function m(t){p||(a.parentNode&&a.parentNode.removeChild(a),p=!0,d&&(clearTimeout(d),d=0),e.pagentTimeout="timeout"===t)}e.pagentDisplayPage=()=>m("engine")})(window,document,1000);
</script>

Load the SDK asynchronously:

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY"
    async
    fetchpriority="high">
  </script>
</head>

4. Skip page hide (no flicker)

If you want to disable the page-hiding mechanism entirely, you can add the data-skip-page-hide="true" attribute to the SDK script tag. This prevents the SDK from hiding the page during initialization.

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY"
    data-skip-page-hide="true">
  </script>
</head>

You can combine this with the async attribute for asynchronous loading:

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY"
    data-skip-page-hide="true"
    async
    fetchpriority="high">
  </script>
</head>

What this does:

✅ No page hiding – The page remains visible throughout initialization
✅ No flicker – Users won’t see the page fade in/out
⚠️ Content overwrite – Variations are applied directly to the visible page
⚠️ Brief flash possible – Users may see the original content briefly before it’s replaced with variations

When to use this:

When you prefer no visual hiding/flicker over perfect content replacement
When your variations are subtle and a brief flash is acceptable
When you want to avoid any opacity changes to the page body
When using with asynchronous loading and you don’t want the anti-flicker snippet

Note: If you use data-skip-page-hide="true" with asynchronous loading, you do not need to include the anti-flicker snippet from section 3.

5. Analytics only mode

For scenarios where you only need to track analytics data without running tests, you can use the SDK in “analytics only mode” by adding the data-analytics-only="true" attribute:

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY"
    data-analytics-only="true">
  </script>
</head>

What this mode does:

✅ Tracks analytics and user behavior data
✅ Makes the _pgnt property available for custom tracking
❌ Never loads or runs A/B tests
❌ Never overwrites variations or content
❌ Never loads anti-flicker mechanisms

This mode is perfect for:

Analytics tracking without experimentation
Gradual migration from other analytics tools
Testing pagent’s data collection before enabling experiments
Compliance scenarios where you need data but not content changes

6. Wait for framework hydration

If your site uses a JavaScript framework like React, Next.js, Gatsby, or Nuxt, the framework “hydrates” the server-rendered HTML after the page loads. This hydration can overwrite any DOM changes the SDK made during initialization. Adding data-await-hydration="true" tells the SDK to wait until the framework has finished hydrating before applying variations, so your changes persist.

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY"
    data-await-hydration="true">
  </script>
</head>

You can combine this with other attributes:

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY"
    data-await-hydration="true"
    async
    fetchpriority="high">
  </script>
</head>

How it works:

The SDK detects common framework root elements (e.g. __next, ___gatsby, __nuxt, root)
It waits for the framework to attach to the DOM, confirming hydration is complete
Once hydrated, the SDK applies variations safely without them being overwritten
If no framework is detected, the SDK proceeds immediately
The wait has a budget (500 ms by default, configurable, see below). If hydration hasn’t been confirmed once the budget runs out, the SDK falls back to analytics-only for that page view: no changes are applied, the visitor sees the original page, and analytics keep working

When to use this:

When using Next.js, Gatsby, Nuxt, or other frameworks with server-side rendering
When you notice variations briefly appear and then revert after page load
When your framework hydration overwrites SDK-applied changes

Try it before committing: You don’t need to add the attribute right away. Append ?pagent_await_hydration=true to any preview URL to test the behavior first:

https://yoursite.com/landing-page?pagent_await_hydration=true

If the variations apply correctly with the parameter, add data-await-hydration="true" to your script tag permanently.

Configuring the wait budget

The wait defaults to 500 ms and can be adjusted with data-hydration-timeout (in milliseconds):

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY"
    data-await-hydration="true"
    data-hydration-timeout="800">
  </script>
</head>

Try a different budget on a preview URL first with ?pagent_hydration_timeout=800.

Choosing what happens on timeout

By default (data-hydration-timeout-mode="drop"), a hydration wait that times out falls back to analytics-only for that page view, as described above. Set data-hydration-timeout-mode="apply" to have the SDK apply variations anyway and defend them instead:

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY"
    data-await-hydration="true"
    data-hydration-timeout-mode="apply">
  </script>
</head>

What apply mode does:

✅ Applies variations as soon as the wait times out, instead of dropping the page view
✅ Watches the modified elements for about 3 seconds afterward and re-applies the change if a late hydration pass overwrites the content, or even replaces the element
⚠️ After that 3-second window, the SDK leaves the page to the framework, so a hydration pass that lands later can still overwrite the change
⚠️ Can cause a brief flicker while the framework renders and the SDK restores the change

Apply mode only kicks in when the wait saw something concrete before timing out (a hydration container such as #root or #__next, or another framework signal) on a document that had finished parsing. A timeout with nothing detected, a still-loading document, or a detection error keeps the default drop behavior. Important caveat: the SDK can’t tell a hydrating framework root apart from a plain page that happens to use <div id="root"> for its own markup, so that page qualifies for apply mode too. Only enable apply mode on pages where applying changes without confirmed hydration is acceptable. When to use this:

Sites where the hydration wait times out on a meaningful share of page views (for example, server-rendered markup in a root container that never finishes hydrating)
When dropping those visitors from experiments is costing you real traffic

Try it first with ?pagent_hydration_timeout_mode=apply on a preview URL.

Scaling the wait on slow connections

With data-await-hydration set, the SDK automatically stretches the wait budget on slow connections so visitors don’t get dropped just because the network is slow. This is on by default:

3G: budget doubled
2G and slow-2G: budget tripled
Scaling never pushes the budget past 1.5 seconds; a larger budget you configure yourself is kept as is
The anti-flicker page hide stretches with it, so the wait is never cut short by its own curtain

Detection uses the browser’s Network Information API, available in Chromium browsers; elsewhere the budget stays as configured. Disable it with data-hydration-connection-scaling="false":

<head>
  <script
    src="https://cdn.pagent.ai/js/sdk.js"
    data-client-key="YOUR_CLIENT_KEY"
    data-await-hydration="true"
    data-hydration-connection-scaling="false">
  </script>
</head>

Try it with ?pagent_hydration_connection_scaling=false on a preview URL. When you don’t need this:

Static HTML sites with no JavaScript framework
Client-side-only SPAs that don’t server-render (no hydration step)
Sites where the SDK loads after the framework has already hydrated

7. Best practices & troubleshooting

Keep it fast – The SDK is delivered from our global CDN and is heavily cached. Still, monitor Web Vitals to ensure no regressions.
Avoid flicker – In both modes the SDK temporarily sets body{opacity:0}. This usually lasts less than 50 ms, but audit on slow connections. With a hydration wait configured (section 6), the hide can last up to the hydration budget plus a small margin, about 1.75 seconds at most with connection scaling.
Test first – Roll out the integration to a staging environment before production.
Need help? – Reach out at support@pagent.ai.

By following these steps you will have pagent running on your site, ready to serve experiments and personalized content from the moment your users land.

Getting started

AI clients

Integration

FAQ

1. Pick a loading strategy

2. Synchronous loading

3. Asynchronous loading with anti-flicker

4. Skip page hide (no flicker)

5. Analytics only mode

6. Wait for framework hydration

Configuring the wait budget

Choosing what happens on timeout

Scaling the wait on slow connections

7. Best practices & troubleshooting

​1. Pick a loading strategy

​2. Synchronous loading

​3. Asynchronous loading with anti-flicker

​4. Skip page hide (no flicker)

​5. Analytics only mode

​6. Wait for framework hydration

​Configuring the wait budget

​Choosing what happens on timeout

​Scaling the wait on slow connections

​7. Best practices & troubleshooting

1. Pick a loading strategy

2. Synchronous loading

3. Asynchronous loading with anti-flicker

4. Skip page hide (no flicker)

5. Analytics only mode

6. Wait for framework hydration

Configuring the wait budget

Choosing what happens on timeout

Scaling the wait on slow connections

7. Best practices & troubleshooting