Once the pixel is installed, you can track custom events to capture user interactions.

Basic Event Tracking

Use the advPxl function to track events:

// Add to Cart
advPxl("event", "add_to_cart");

// Initiated Checkout
advPxl("event", "initiated_checkout");

Standard Events

Autocapture

The v3 pixel can capture user interactions automatically — clicks, form submits, input changes, rage clicks, and copy/cut actions — without manual advPxl calls. Disabled by default: opt in per workspace by setting window.adverfly.activate_autocapture = true before init.

window.adverfly = window.adverfly || [];
window.adverfly.activate_autocapture = true;
advPxl("init", 8397799);

Captured Events

Privacy

Autocapture is designed to never leak sensitive data. The following are enforced client-side before anything is sent:

• Input types never captured: password, hidden, file.
• Sensitive fields blocked by name / autocomplete: credit card (cc-*, card-num, card-no), CVC/CVV, expiry, SSN, social, password, API keys, auth tokens, one-time-codes.
• Freeform input values never read: <input type="text|email|tel|..."> and <textarea> values are never included. Only <select> options and checkbox/radio state are captured.
• Text scrubbing: any token in visible text that looks like a credit card number, SSN, or a run of 13+ digits is stripped before sending. Result is truncated to 200 characters.
• Opt-out selectors: elements (and their descendants) marked with class adv-no-capture or attribute data-adv-no-capture are skipped entirely.

Excluding Elements

Exclude a specific element (and all its children) from autocapture:

<!-- Class-based -->
<div class="adv-no-capture">
  <input type="text" name="internal-note" />
</div>

<!-- Attribute-based -->
<section data-adv-no-capture>
  <button>Internal action</button>
</section>

Configuration

Fine-grained control via window.adverfly.autocapture_config (set before init):

window.adverfly = window.adverfly || [];
window.adverfly.autocapture_config = {
  url_ignorelist: [/\/admin/, "/debug"],
  css_selector_allowlist: [".track-me", "[data-adv-track]"],
};
advPxl("init", 8397799);

Rate Limiting

Built-in limits protect your site and your event quota:

• Global: max 30 autocapture events per second.
• Per element: minimum 500 ms between events on the same element.
• Rage click: 1 s cooldown per element after a $rageclick fires.

Conversions are the most important events to track. They represent completed goals like purchases or lead submissions.

Purchase Conversion

Track when a user completes a purchase:

advPxl("conversion", "purchase", {
  transaction_id: "order123",              // required
  transaction_gross_revenue: 10999,        // required (in cents)
  transaction_currency: "EUR",             // required
  transaction_shipping_costs: 499,         // optional (in cents)
  transaction_tax: 1900,                   // optional (in cents)
  transaction_city: "Berlin",              // optional
  transaction_country_code: "DE",          // optional
  transaction_discount_code: "SUMMER20",   // optional
  customer_id: "customer@email.com",       // optional
  is_new_customer: 1,                       // optional (1 = new, 0 = returning)
});

Conversion Parameters

With Line Items

You can also pass individual line items:

advPxl("conversion", "purchase", {
  transaction_id: "order123",
  transaction_gross_revenue: 2000,
  transaction_currency: "EUR",
  transaction_shipping_costs: 350,
  transaction_tax: 150,
  transaction_city: "Berlin",
  transaction_country_code: "DE",
  customer_id: "customer@email.com",
  is_new_customer: 1,
  transaction_items: [
    {
      transaction_item_id: "123",
      transaction_item_name: "Product 1",
      transaction_item_price: 1000,
      transaction_item_tax: 50,
      transaction_item_quantity: 2,
    },
    {
      transaction_item_id: "124",
      transaction_item_name: "Product 2",
      transaction_item_price: 500,
      transaction_item_quantity: 1,
    },
  ],
});

Item Parameters

Lead Conversion

Track when a user submits a lead form:

advPxl("conversion", "lead", {
  transaction_id: "lead-456",
});

You can install the Adverfly Pixel using Google Tag Manager for easier management.

Installation Steps

1. Open your GTM container
2. Create a new Tag
3. Choose Custom HTML
4. Paste the following code:

<script>
  window.adverfly = window.adverfly || [];
  function advPxl() {
    var args = [false];
    for (var i = 0; i < arguments.length; i++) {
      args.push(arguments[i]);
    }
    adverfly.push(args);
  }
  advPxl("init", YOUR_WORKSPACE_ID);
  window.adverfly.store_currency = "EUR";
  window.adverfly.store_timezone = "Europe/Berlin";

  var script = document.createElement("script");
  script.type = "text/javascript";
  script.async = true;
  script.src = "https://sos-de-fra-1.exo.io/adv/advv2.01.js";
  document.getElementsByTagName("head")[0].appendChild(script);
</script>

5. Set the trigger to All Pages
6. Save and publish

Configuration

Tracking Conversions via Data Layer

If you're using the Data Layer for e-commerce events:

<script>
  // This tag should fire on the purchase confirmation page
  advPxl("conversion", "purchase", {
    transaction_id: {{DL - Transaction ID}},
    transaction_gross_revenue: {{DL - Revenue}} * 100,
    transaction_currency: {{DL - Currency}}
  });
</script>

Tracking Custom Events

Create additional tags for custom events:

<script>
  // Add to Cart tag - trigger on add_to_cart event
  advPxl("event", "add_to_cart");
</script>

<script>
  // Initiated Checkout tag - trigger on checkout start
  advPxl("event", "initiated_checkout");
</script>

Recommended Triggers

Adverfly integrates natively with Shopify's Customer Events API for accurate tracking.

Installation Steps

1. Go to your Shopify Admin
2. Navigate to Settings → Customer events
3. Click Add custom pixel
4. Name it "Adverfly"
5. Paste the following code:

const script = document.createElement("script");
script.type = "text/javascript";
script.async = true;
script.src = "https://sos-de-fra-1.exo.io/adv/script-shopify.js";
document.getElementsByTagName("script")[0].parentNode.appendChild(script);

window.adverfly_web_pixel = true;
window.adverfly_init = init;
window.adverfly_browser = browser;
window.adverfly_settings = api.settings;

window.adverfly = window.adverfly || [];
window.advPxl = function () {
  adverfly.push([false, ...arguments]);
};

analytics.subscribe("all_events", (event) => {
  window.adverfly.push(["all_shopify_events", event]);
  advPxl("init", YOUR_WORKSPACE_ID);
  window.adverfly.store_currency = "EUR";
  window.adverfly.store_timezone = "Europe/Berlin";

  if (event.name === "page_viewed") {
    advPxl("check", "vikeys", event);
  }
});

Replace YOUR_WORKSPACE_ID with your Workspace ID and set your store's currency and timezone.

Configuration

Tracked Events

The Shopify integration automatically tracks all standard e-commerce events:

Embed Adverfly surveys directly on your website to collect customer feedback, post-purchase reviews, or NPS scores.

Quick Start

If you already have the Adverfly pixel installed, simply add this div where you want the survey to appear:

<div data-adv-survey-id="SURVEY_ID" data-adv-workspace-id="WORKSPACE_ID"></div>

Replace SURVEY_ID with your survey ID and WORKSPACE_ID with your workspace ID (both found in the survey settings).

The pixel automatically detects survey embeds and renders them.

Parameters

Customer & Transaction Tracking

Survey events automatically include customer_id and transaction_id when set via the Adverfly Layer. This allows you to link survey responses to specific customers and orders.

<script>
  window.adverfly = window.adverfly || [];
  function advPxl() { adverfly.push([!1, ...arguments]); }
  advPxl("init", WORKSPACE_ID);
  window.adverfly.store_currency = "EUR";
  window.adverfly.store_timezone = "Europe/Berlin";

  /* Set customer and transaction IDs */
  window.adverfly.customer_id = "customer_123";
  window.adverfly.transaction_id = "order_456";
</script>

Adverfly Layer Properties

These properties are automatically included in all survey events (survey_opened, survey_answer, survey_completed).

Multi-Language Support

Surveys support multiple languages. Set data-adv-lang to display translated content. Use default to force the survey base content while keeping the UI fallback in English:

<div
  data-adv-survey-id="SURVEY_ID"
  data-adv-workspace-id="WORKSPACE_ID"
  data-adv-lang="de"
></div>

If data-adv-lang is omitted entirely, the public embed keeps the legacy behavior: English UI with the survey base content. Translations must be configured in the survey settings within Adverfly.

Survey Features

• Required questions: Questions marked as required show a red asterisk (*) and validate before proceeding
• Multi-step navigation: Surveys display one question at a time with Back/Next buttons
• Progress indicator: Shows current step and progress bar
• Thank you screen: Customizable message after submission

Survey Requirements

For the embed to work, your survey must:

• Be set to live status
• Have the Adverfly v2 pixel installed on the page (surveys are not supported in the v1 pixel)

Survey Events

The pixel automatically tracks these events for analytics:

All events include form_id, submission_id, and (if set) customer_id and transaction_id.

Adverfly Widgets render personalized popups, banners, countdowns and toast notifications on your storefront. The right variant is picked per visitor in real time by the personalization engine based on the segment they belong to.

How it works

Visitor lands on page
   ↓
Pixel calls /public/personalize with customer_id + session context
   ↓
Engine evaluates active widgets for this trigger + visitor's segment
   ↓
Pixel renders the winning widget (popup / banner / countdown / toast)
   ↓
All interactions (impression, click, dismiss, success) tracked to ClickHouse

You design widgets in the Adverfly app under Widgets. Each widget targets one segment (or "Everyone") and is auto-rendered when its trigger fires.

Installation

The widget pixel ships as part of the standard Adverfly tracking pixel — if you already have preset-pixel-adv.js (v3) installed, widgets work automatically with no extra code.

Shopify

Install the Adverfly Widgets custom app and enable the Adverfly Widgets App Embed Block in the theme editor under Online Store → Themes → Customize → App Embeds. The block's Workspace ID setting wires the pixel to your account.

For inline placements, drag the Adverfly Inline Widget App Block into any section.

Other platforms (theme.liquid, GTM, manual)

If you already have the Adverfly pixel on your site, enable widgets per workspace by setting window.adverfly.activate_widgets = true before advPxl("init", ...). Without this flag, the pixel does not call /personalize automatically — manual advWidgets.fetchAndRender(...) calls still work.

window.adverfly = window.adverfly || [];
window.adverfly.activate_widgets = true;
advPxl("init", 8397799);

Auto-Triggers

Once activate_widgets = true is set, widgets fire automatically based on their trigger_type:

Manual Rendering

If you want to trigger a widget yourself (e.g. after a custom event in your app), call advWidgets.fetchAndRender:

/* Trigger a custom widget configured for trigger="custom_event" */
window.advWidgets.fetchAndRender("custom_event");

/* Pass extra context that's added to the engine evaluation */
window.advWidgets.fetchAndRender("post_purchase", {
  transaction_id: "order_123",
  cart_value: 49.9,
});

Inline Widgets

Inline widgets render at a specific spot in your page rather than as overlays. Drop a <div> with data-adv-inline into your theme:

<div
  data-adv-inline
  data-adv-trigger="pdp_above_cta"
  data-adv-workspace="WORKSPACE_ID"
  style="min-height: 80px"
></div>

Configure a widget in Adverfly with trigger_type = "inline" and a matching trigger value (e.g. pdp_above_cta). The pixel mounts the personalized variant inside that div on page load.

Tracked Events

Every widget interaction is logged to ClickHouse pixel_events automatically — same pipeline as survey events, joinable by customer_id.

Common payload fields

Every widget event carries these top-level fields (matches the survey schema for easy joining):

Tracking Goal Completion (Success API)

When a visitor completes the goal of a widget — submits an email, claims a discount, signs up — call the success API. This fires a widget_success event you can query later for conversion analytics.

window.advWidgets.success("widget-variant-id", {
  email: "user@example.com",   // auto-hashed → email_hashed (SHA-256, lowercased)
  value: 19.9,
  source: "newsletter_form",
});

The raw email is never transmitted — the pixel hashes it client-side before sending. Pass email_hashed directly if you've already hashed elsewhere.

Manual Click Tracking

For inline widgets that render custom HTML, attribute clicks manually:

window.advWidgets.trackClick("widget-variant-id", {
  cta_url: "/checkout",
  source: "custom_cta",
});

Joining Widgets to Conversions

Widget events live in pixel_events and conversions in pixel_conversions. Join by customer_id (hashed) or by visitor_id for anonymous attribution.

-- Click-through rate per widget, last 30 days
SELECT
  form_id AS widget_id,
  countIf(name = 'widget_impression')      AS impressions,
  countIf(name = 'widget_click')           AS clicks,
  countIf(name = 'widget_success')         AS successes,
  clicks / nullIf(impressions, 0)          AS ctr
FROM pixel_events
WHERE store_id = {workspace_id:String}
  AND name LIKE 'widget_%'
  AND dt >= today() - 30
GROUP BY form_id;

-- Attribute conversions to a widget impression (24h window, visitor_id link)
SELECT
  e.form_id AS widget_id,
  sum(c.transaction_gross_revenue / 100) AS attributed_revenue
FROM pixel_events AS e
INNER JOIN pixel_conversions AS c
  ON e.visitor_id = c.visitor_id
 AND e.store_id   = c.store_id
 AND c.dt BETWEEN e.dt AND e.dt + INTERVAL 1 DAY
WHERE e.store_id = {workspace_id:String}
  AND e.name = 'widget_impression'
GROUP BY e.form_id;

Manual-Only Mode

If activate_widgets = true is not set, no auto-triggers fire — but window.advWidgets.fetchAndRender(trigger, extra) still works for fully manual rendering. Use this if you want full control over when /personalize is called.

See Also

• Tracking Events — base event API the widget events ride on
• Surveys — sister product, same event pipeline, similar embed pattern
• Pixel Installation — how the pixel boots and the window.adverfly queue

The @adverfly/sdk JavaScript package lets you fetch the right personalized variant for the current visitor and render it however you want — your own React/Vue/Svelte components, server-rendered HTML, or even mobile apps.

The standard tracking pixel still works as a no-code option. Use the SDK when you need:

• Pixel-perfect brand control — no iframe, no CSS overrides
• Server-side / Edge personalization — Cloudflare Workers, Vercel Edge, Next.js Server Components
• Custom UI — inline blocks, mobile screens, anything beyond popup/banner/toast/countdown
• Strict typing — your config shape becomes a TypeScript generic

Install

Three formats, same code — pick whichever fits your stack.

Vanilla <script> (no build step)

<script src="https://cdn.jsdelivr.net/npm/@adverfly/sdk/dist/adverfly.iife.js"></script>
<script>
  const adv = new Adverfly({ workspaceId: 188334 });
  /* `Adverfly` is now a global class — no module system required. */
</script>

Pin a version in production: @adverfly/sdk@0.1.0/dist/adverfly.iife.js.

ES modules in the browser

<script type="module">
  import { Adverfly } from "https://cdn.jsdelivr.net/npm/@adverfly/sdk/dist/index.mjs";
  const adv = new Adverfly({ workspaceId: 188334 });
</script>

npm (build pipelines, Node, SSR)

npm install @adverfly/sdk

import { Adverfly } from "@adverfly/sdk";

Works in browsers and Node 18+. Zero peer dependencies. Bundle is ~6 KB minified for the IIFE build, ~12 KB for the ESM build.

Quick start

import { Adverfly } from "@adverfly/sdk";

const adv = new Adverfly({ workspaceId: 188334 });

await adv.identify({ email: "user@example.com" });

adv.setContext({
  cart_value: 49.9,
  last_viewed_creatives: ["sku_a", "sku_b"],
});

const variant = await adv.personalize({ trigger: "exit_intent" });

if (variant) {
  showMyPopup({
    title: variant.config.title,
    copy: variant.config.copy,
    onCtaClick: () => adv.click(variant.id),
    onDismiss: () => adv.dismiss(variant.id),
  });
  await adv.trackImpression(variant.id);
}

Constructor

Identity

await adv.identify({
  email: "user@example.com",   // hashed (SHA-256, lowercased) → never sent raw
  transactionId: "order_123",  // optional, for post-purchase triggers
});

To reset identity (e.g. on logout):

adv.reset();

Personalize

const variant = await adv.personalize<MyConfigShape>({
  trigger: "exit_intent",
  surface: "widget",  // optional, defaults to "widget"
  context: { device_battery_low: true },  // merged on top of session context
});
// { id, config, reason } | null

Strongly-typed config:

interface PopupConfig {
  title: string;
  copy: string;
  cta?: string;
  cta_url?: string;
  image_url?: string;
}

const variant = await adv.personalize<PopupConfig>({ trigger: "exit_intent" });
if (variant) {
  console.log(variant.config.title); // typed!
}

Tracking

All tracking events are written to the same ClickHouse pixel_events table the standard pixel uses — joinable by customer_id (hashed) for conversion attribution.

Events

Subscribe to the lifecycle for analytics, debugging, or custom rendering hooks.

const off = adv.on("decision", ({ trigger, variant }) => {
  console.log(`[${trigger}] →`, variant?.id ?? "no match");
});

/* Returns an unsubscribe function */
off();

Available events: decision, impression, click, dismiss, auto_dismissed, success, error.

React

A first-class @adverfly/react package is planned. For now you can wrap the core SDK in a hook:

import { Adverfly, type Variant } from "@adverfly/sdk";

const AdverflyContext = createContext<Adverfly | null>(null);

export function usePersonalization<T>(trigger: string) {
  const adv = useContext(AdverflyContext)!;
  const [variant, setVariant] = useState<Variant<T> | null>(null);

  useEffect(() => {
    adv.personalize<T>({ trigger }).then((v) => {
      setVariant(v);
      if (v) adv.trackImpression(v.id);
    });
  }, [adv, trigger]);

  return {
    variant,
    click: (props?) => variant && adv.click(variant.id, props),
    dismiss: () => variant && adv.dismiss(variant.id),
    success: (props?) => variant && adv.success(variant.id, props),
  };
}

Full example: sdks/javascript/examples/react-hook.tsx.

Server-side / Edge

Works anywhere fetch + crypto.subtle exist (Node 18+, Bun, Cloudflare Workers, Vercel Edge).

/* Cloudflare Worker — server-render a personalized hero block */
export default {
  async fetch(request: Request) {
    const adv = new Adverfly({
      workspaceId: 188334,
      manualIdentity: true,  // we manage identity ourselves
    });
    await adv.identify({ customerId: getCookieUserId(request) });

    const variant = await adv.personalize({
      trigger: "ssr_hero",
      context: { country: request.cf?.country },
    });

    return new Response(renderHero(variant?.config), {
      headers: { "content-type": "text/html" },
    });
  },
};

Privacy

• Emails are hashed client-side (SHA-256, lowercased + trimmed) before any network call.
• No cookies set by the SDK. Anonymous IDs go to localStorage; opt out with manualIdentity: true.
• CORS-clean. POST + JSON, no preflight surprises.

See also

• Widgets — the no-code drop-in pixel option
• Tracking Events — base event schema (the SDK rides on the same beacon)