<script id='coframe-installation-script'>
  (function () {
    // Early exit for performance testing
    if (/cf_disable/.test(location.search)) return console.warn('[Coframe] Disabled via URL parameter');

    // Coframe config
    const config = {
      projectId: 'YOUR_PROJECT_ID',
      startTime: Date.now(),
      timeoutMs: 1000,
      currentUrl: window.location.href,
    };

    // Prevent duplicate installation
    const script_id = 'coframe-sdk-js';
    if (document.getElementById(script_id)) return console.warn('[Coframe] SDK already installed');

    // Coframe queue setup
    (window.CFQ = window.CFQ || []).push({ config });

    // Coframe antiflicker CSS
    const style = document.createElement('style');
    style.id = 'coframe-antiflicker';
    style.textContent =
      ':root { --cf-show: 0;}' +
      'body { opacity: var(--cf-show) !important; transition: opacity 0.2s ease; }'
    function hide() { document.head.appendChild(style); }
    function show() {
      document.documentElement.style.setProperty('--cf-show', '1');
      style.parentNode && style.parentNode.removeChild(style);
    }
    hide(); setTimeout(show, config.timeoutMs);

    // Coframe SDK JS
    var edgeUrl = new URL('https://edge.cofra.me/cf.js');
    edgeUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));

    const script = document.createElement('script');
    script.id = script_id;
    script.async = true;
    script.src = edgeUrl.toString();
    script.onerror = () => { show(); console.error('[Coframe] SDK failed to load'); };
    document.head.appendChild(script);
  })();
</script>

window.CFQ = window.CFQ || [];
window.CFQ.push({
    subscribe: 'treatmentApplied',
    bulkCallbackV2: (treatments) => {
        // TODO: Send all treatments to your analytics platform
        treatments.forEach(treatment => {
            console.log('[Coframe] treatment:', treatment);
        });
    }
});

<script id='coframe-feature-flag-control' async>
  const coframeEnabled = true; // Replace with your feature flag logic
  window.CFQ = window.CFQ || [];
  window.CFQ.push({ featureFlagSet: coframeEnabled });
</script>

<script id='coframe-cookie-consent' async>
  window.CFQ = window.CFQ || [];
  window.CFQ.push({ cookiesEnabled: true });
</script>

<script>
  // User token - provide visitor identity from your application
  const userToken = 'visitor-123'; // TODO: replace with your visitor/user ID
  window.CFQ = window.CFQ || [];
  if (userToken) {
    window.CFQ.push({ setUserToken: userToken });
  }
</script>

<script>
  window.CFQ = window.CFQ || [];
  window.CFQ.push({
    conversion: {
      metricName: 'purchase_completed',
      value: 99.99
    }
  });
</script>

# SDK Options

The complete Coframe configuration reference — antiflicker, analytics callback, feature flag control, cookie consent, cookieless, conversion events, tracking-only mode, and CSP nonce

The Coframe install script accepts a config object that controls how the SDK
initializes, how long it waits before revealing the page, and which optional
behaviors are active. This page is the complete reference for every
configuration setting — the same set of options you toggle in the in-app
Configuration settings panel when generating your install script.


Each setting below corresponds to one toggle in that panel. Some are runtime
fields on the config object; others add a small companion script to your page.
Where a setting has a dedicated guide, it is linked at the end of the section.

## Try It: Build Your Install Script

Toggle the settings below to generate your install script. Each option maps to
a section in the reference further down this page.


Configuration settingsChoose your options, then copy the generated scripts. Changes here do not update your live project.

Use Antiflicker (Synchronous)Hides page content briefly to prevent visual flicker when Coframe applies changes. Required if Coframe will modify visible content above the fold. Optional for tracking-only implementations or below-the-fold changes.Analytics callbackSend Coframe treatment data to your third-party analytics platform (Google Analytics, Amplitude, etc.).Feature Flag ControlEnable Coframe based on your feature flag system (e.g. emergency shutdown).Cookies ConsentOnly write coframe tracking cookies after user has accepted cookies consent. E.g. for GDPR compliance.CookielessCall this when the user/visitor unique id is handled by your tracking system. No coframe cookies are used when this option is enabled.Custom Conversion EventsTrack custom conversion events by calling the conversion tracking script when users complete specific actions (e.g., button clicks, form submissions, page views).Tracking Only ModeEnable this if you only want Coframe tracking and analytics, without applying variant changes to the page.CSP NonceApply a Content Security Policy nonce to dynamically injected scripts. Required if your site enforces a CSP with nonce-based script allowlisting.

## The Config Object

Every Coframe installation passes a config object to the SDK. The fields below
are the ones generated by the in-app install script. Some fields are always
present; others appear only when you enable a specific option.





Option | 
Type | 
Purpose | 





`projectId` | 
string | 
Your Coframe project ID | 



`startTime` | 
number | 
`Date.now()` at install, for timing | 



`timeoutMs` | 
number | 
Max wait before revealing the page (default `1000`) | 



`currentUrl` | 
string | 
`window.location.href` | 



`waitForHydration` | 
boolean | 
Wait for client hydration before applying changes — set by the [framework guides](../docs/react.html), not a builder toggle | 



`trackingOnly` | 
boolean | 
Track treatments/events without applying variant changes | 



`waitForFeatureFlag` | 
boolean | 
Wait for a feature-flag signal before initializing | 



`waitForCookiesEnabled` | 
boolean | 
Wait for cookie consent before storing cookies | 



`waitForUserToken` | 
boolean | 
Wait for a client-provided user token (cookieless) | 



`nonce` | 
string | 
CSP nonce for the injected `<script>`/`<style>` |

## Use Antiflicker (Synchronous)

Hides page content briefly to prevent visual flicker when Coframe applies
changes. Required if Coframe will modify visible content above the fold.
Optional for tracking-only implementations or below-the-fold changes.


When enabled, the install script adds a small synchronous snippet that hides
`<body>` on page load and reveals it once the SDK has applied its changes or
`timeoutMs` (default `1000` ms) has elapsed — whichever comes first. This
prevents the “flash of original content” a visitor would otherwise see between
first paint and when the variant is applied.


This snippet must run synchronously, before first paint — do not load it
through an async tag manager or with an `async`/`defer` attribute, or the
flash will have already occurred before it can hide anything. Antiflicker is
automatically disabled in [tracking-only mode](#tracking-only-mode), since no
content changes are applied.


For the mechanism, timeout behavior, and tuning, see
[Anti-Flicker](../docs/anti-flicker.html).

## Analytics Callback

Send Coframe treatment data to your third-party analytics platform (Google
Analytics, Amplitude, etc.).


When Coframe applies a treatment, it can notify your analytics platform so you
can record the experiment assignment alongside the rest of your event stream.
Subscribe to `treatmentApplied` by pushing a `bulkCallbackV2` handler to
`window.CFQ`:


JS



```
window.CFQ = window.CFQ || [];
window.CFQ.push({
    subscribe: 'treatmentApplied',
    bulkCallbackV2: (treatments) => {
        // TODO: Send all treatments to your analytics platform
        treatments.forEach(treatment => {
            console.log('[Coframe] treatment:', treatment);
        });
    }
});
```




The callback receives an array of `CoframeTreatmentDataV2` objects, each containing
the experiment ID, variant ID, user token, and other assignment fields. See
the [field reference](../docs/experiment-assignment.html) for the
complete list.


Platform-specific `bulkCallbackV2` implementations — mapping treatment fields
to Segment, Amplitude, Heap, and others — are covered under
[Analytics Integrations](../docs/segment.html).

## Feature Flag Control

Enable Coframe based on your feature flag system (e.g. emergency shutdown).


This option gates the Coframe SDK behind your own flag system. Coframe’s
own feature flags product (release toggles, variants, remote config) is
documented under [Feature Flags](../docs/feature-flags-overview.html).




Set `waitForFeatureFlag: true` in the config object to gate Coframe behind your
own feature flag system. With this option enabled, the SDK waits for an
explicit signal before it initializes. Without that signal, Coframe stays
dormant regardless of the other config values.


To send the signal, add the following script to your page. It must run after
the Coframe install script:


HTML



```
<script id='coframe-feature-flag-control' async>
  const coframeEnabled = true; // Replace with your feature flag logic
  window.CFQ = window.CFQ || [];
  window.CFQ.push({ featureFlagSet: coframeEnabled });
</script>
```




Run this script even when the flag evaluates to `false`. The SDK needs the
explicit signal either way. If the script is omitted or never runs, the SDK
treats the value as `undefined` and keeps waiting for the signal.

## Cookies Consent

Only write Coframe tracking cookies after the user has accepted cookies
consent. E.g. for GDPR compliance.


Set `waitForCookiesEnabled: true` in the config object to delay cookie storage
until the visitor has accepted your cookie consent prompt. With this option
enabled, the SDK holds off on writing any cookies until it receives a consent
signal.


Send the signal from your consent callback or from a script that fires after
the visitor accepts:


HTML



```
<script id='coframe-cookie-consent' async>
  window.CFQ = window.CFQ || [];
  window.CFQ.push({ cookiesEnabled: true });
</script>
```




If a visitor declines consent and the signal is never pushed, Coframe runs
without writing cookies for that session.

## Cookieless

Call this when the user/visitor unique ID is handled by your tracking system.
No Coframe cookies are used when this option is enabled.


Set `waitForUserToken: true` in the config object to disable Coframe’s
cookie-based visitor identity and supply the identity yourself. When enabled,
Coframe waits for your application to call `setUserToken` before assigning the
visitor to any experiment, and writes no Coframe cookies.


Place the following snippet before the main Coframe SDK script, replacing
`visitor-123` with the actual visitor or user ID from your application:


HTML



```
<script>
  // User token - provide visitor identity from your application
  const userToken = 'visitor-123'; // TODO: replace with your visitor/user ID
  window.CFQ = window.CFQ || [];
  if (userToken) {
    window.CFQ.push({ setUserToken: userToken });
  }
</script>
```




The value you pass is forwarded as `coframe_user_token` in the analytics
treatment callback, letting you join Coframe experiment data back to your own
user records. For the full details, see
[Identity Settings](../docs/identity-settings.html).

## Custom Conversion Events

Track custom conversion events by calling the conversion tracking script when
users complete specific actions (e.g., button clicks, form submissions, page
views).


A conversion event tells Coframe that a visitor completed a meaningful action
— a purchase, a sign-up, a checkout step — so the action can be counted as a
metric outcome for any active experiments. Push a `conversion` command to
`window.CFQ` at the point in your code where the action occurs:


HTML



```
<script>
  window.CFQ = window.CFQ || [];
  window.CFQ.push({
    conversion: {
      metricName: 'purchase_completed',
      value: 99.99
    }
  });
</script>
```




Replace `purchase_completed` with the metric name you configured for your
experiment. The `value` field is optional and can carry a numeric payload such
as revenue or quantity. See
[Tracking Settings](../docs/tracking-settings.html) for more on
conversion tracking.

## Tracking Only Mode

Enable this if you only want Coframe tracking and analytics, without applying
variant changes to the page.


Set `trackingOnly: true` in the config object to run Coframe in observation
mode. The SDK records which treatment a visitor would have received and emits
the corresponding analytics events, but it does not apply any visual or content
changes to the page. [Antiflicker](#use-antiflicker-synchronous) is also
disabled in this mode, since there is nothing to hide during initialization.


This mode is useful during an initial integration phase, when you want to
validate that events are flowing correctly before enabling live variant
delivery, or when you want to audit assignment logic without affecting the
visitor experience. For what Coframe tracks in this mode, see
[Tracking Settings](../docs/tracking-settings.html).

## CSP Nonce

Apply a Content Security Policy nonce to dynamically injected scripts.
Required if your site enforces a CSP with nonce-based script allowlisting.


Set the `nonce` field in the config object to your generated nonce value, and
add `nonce='YOUR_NONCE_VALUE'` as an attribute to each Coframe `<script>` tag
on the page. The nonce value must match what your server sends in the
`Content-Security-Policy` response header for the injected scripts and styles
to be accepted by the browser.



For related configuration, see:



- [Identity Settings](../docs/identity-settings.html)


- [Tracking Settings](../docs/tracking-settings.html)


- [Anti-Flicker](../docs/anti-flicker.html)


- [Analytics Integrations](../docs/segment.html)

## Selected configuration

### Main Installation Script

```html
<script id='coframe-installation-script'>
  (function () {
    // Early exit for performance testing
    if (/cf_disable/.test(location.search)) return console.warn('[Coframe] Disabled via URL parameter');

    // Coframe config
    const config = {
      projectId: 'YOUR_PROJECT_ID',
      startTime: Date.now(),
      timeoutMs: 1000,
      currentUrl: window.location.href,
    };

    // Prevent duplicate installation
    const script_id = 'coframe-sdk-js';
    if (document.getElementById(script_id)) return console.warn('[Coframe] SDK already installed');

    // Coframe queue setup
    (window.CFQ = window.CFQ || []).push({ config });

    // Coframe antiflicker CSS
    const style = document.createElement('style');
    style.id = 'coframe-antiflicker';
    style.textContent =
      ':root { --cf-show: 0;}' +
      'body { opacity: var(--cf-show) !important; transition: opacity 0.2s ease; }'
    function hide() { document.head.appendChild(style); }
    function show() {
      document.documentElement.style.setProperty('--cf-show', '1');
      style.parentNode && style.parentNode.removeChild(style);
    }
    hide(); setTimeout(show, config.timeoutMs);

    // Coframe SDK JS
    var edgeUrl = new URL('https://edge.cofra.me/cf.js');
    edgeUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));

    const script = document.createElement('script');
    script.id = script_id;
    script.async = true;
    script.src = edgeUrl.toString();
    script.onerror = () => { show(); console.error('[Coframe] SDK failed to load'); };
    document.head.appendChild(script);
  })();
</script>
```