pagent JavaScript SDK Integration Guide

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 guarantees that the SDK runs during the first render cycle, avoiding any visual flashes.
Because the tag must execute before the page is painted, we do not recommend inserting it via Google Tag Manager or any tool that injects scripts late.

3. Asynchronous loading with anti-flicker

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

<script>
    (() => {
        const MAX_WAIT = 1000;
        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.

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. 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.
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.

Next GDPR >>