Integration Guide for pagent 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. By follow these instructions, you can ensure that the script runs early and efficiently in the page lifecycle, preventing any impact on loading times.

SDK Integration Requirements

The pagent SDK script is designed to run at page load and immediately activate experiment variations for specific elements on your page.

Script Placement

Place the SDK script inside the <head> section of your HTML. This ensures it loads early in the page lifecycle, preventing any impact on loading times. We do not recommend integrating the pagent SDK via Google Tag Manager, as the script needs to run as early as possible for optimal performance.

Script Variants

  1. Default Variant: Sets a cookie immediately upon page load. Only use this in the EU when you deem pagent mandatory for you site’s operation.

  2. Opt-In Variant: Uses cookie-less tracking for up to 24h and sets a permanent cookie only once optIn is triggered.

Example Integration

Replace [YOUR_KEY] with the actual key provided by pagent. You can find the script to include in your pagent settings.

Default Variant

<head>
  <!-- pagent SDK Script - Default Variant -->
  <script data-client-key="[YOUR_KEY]" src="https://cdn.pagent.ai/js/sdk.js"></script>
</head>

Opt-In Variant

<head>
  <!-- pagent SDK Script - Opt-In Variant -->
  <script data-client-key="[YOUR_KEY]" data-opt-in="true" src="https://cdn.pagent.ai/js/sdk.js"></script>
</head>

Once you have consent from your user, execute the optIn command as follows:

window._pgnt = window._pgnt || [];
window._pgnt.push({ kind: "opt-in" });

Alternatively, you can have a script injected into your page upon consent, like below:

<script>
    window._pgnt = window._pgnt || [];
    window._pgnt.push({ kind: "opt-in" });
</script>

Important Notes

  • Performance Impact: The SDK script is served via a CDN to reduce latency and should not negatively affect your page load times.
  • Flicker-Free Execution: Integrating the script in the section allows pagent to make any necessary page modifications without causing a flash of unstyled content (FOUC) or other visible page shifts.

Troubleshooting Tips

  • Test in Staging: Before deploying to production, test the integration in a staging environment to ensure A/B variations apply as expected.
  • Verify Consent Mechanisms: If using the opt-in variant, confirm that consent is collected and managed correctly on your site.
  • Monitor Loading Times: Regularly audit the page load performance to ensure the script remains optimized.

For further assistance, please refer to support@pagent.ai.

Setting Security Headers

To ensure your web page can securely access and send data to pagent, you need to configure the appropriate security headers. Below is a guide for setting up these headers, including a Content Security Policy (CSP).

Content Security Policy (CSP)

The Content Security Policy header controls which resources can be loaded on your page. To allow *.pagent.ai, you need to include it in your policy. Here’s an example configuration:

Content-Security-Policy: connect-src 'self' https://*.pagent.ai; frame-src 'self' *.pagent.ai;