Sobald der Pixel installiert ist, kannst du Custom-Events tracken, um Nutzer-Interaktionen zu erfassen.

Grundlegendes Event-Tracking

Verwende die advPxl-Funktion, um Events zu tracken:

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

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

Standard-Events

Autocapture

Das v3-Pixel kann Nutzer-Interaktionen automatisch erfassen — Klicks, Form-Submits, Input-Änderungen, Rage-Clicks und Copy/Cut-Aktionen — ohne manuelle advPxl-Aufrufe. Standardmäßig deaktiviert: aktiviere es pro Workspace mit window.adverfly.activate_autocapture = true vor dem init.

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

Erfasste Events

Privacy

Autocapture ist so designt, dass keine sensiblen Daten geleakt werden. Folgendes wird clientseitig erzwungen, bevor etwas gesendet wird:

• Niemals erfasste Input-Typen: password, hidden, file.
• Über Name/Autocomplete blockierte Felder: Kreditkarte (cc-*, card-num, card-no), CVC/CVV, Ablaufdatum, SSN, Sozialversicherung, Passwort, API-Keys, Auth-Tokens, Einmal-Codes.
• Werte von Freitext-Inputs werden nie gelesen: <input type="text|email|tel|..."> und <textarea> werden nie erfasst. Nur <select>-Optionen sowie Checkbox-/Radio-Status.
• Text-Scrubbing: Jeder Token in sichtbarem Text, der wie eine Kreditkartennummer, SSN oder eine Folge von 13+ Ziffern aussieht, wird vor dem Senden entfernt. Das Ergebnis wird auf 200 Zeichen gekürzt.
• Opt-out-Selektoren: Elemente (und Kinder) mit Klasse adv-no-capture oder Attribut data-adv-no-capture werden komplett übersprungen.

Elemente ausschließen

Ein bestimmtes Element (und alle Kinder) ausschließen:

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

<!-- via Attribut -->
<section data-adv-no-capture>
  <button>Interne Aktion</button>
</section>

Konfiguration

Feinsteuerung via window.adverfly.autocapture_config (vor init setzen):

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

Eingebaute Limits schützen deine Seite und dein Event-Kontingent:

• Global: max. 30 Autocapture-Events pro Sekunde.
• Pro Element: mindestens 500 ms zwischen Events am selben Element.
• Rage-Click: 1 s Cooldown pro Element nach einem $rageclick.

Du kannst den Adverfly-Pixel über Google Tag Manager installieren — leichter zu pflegen.

Installations-Schritte

1. Öffne deinen GTM-Container
2. Erstelle ein neues Tag
3. Wähle Custom HTML
4. Füge folgenden Code ein:

<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", DEINE_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. Setze den Trigger auf All Pages
6. Speichern und veröffentlichen

Konfiguration

Conversions via Data Layer tracken

Wenn du den Data Layer für E-Commerce-Events nutzt:

<script>
  // Dieses Tag sollte auf der Bestätigungs-Seite feuern
  advPxl("conversion", "purchase", {
    transaction_id: {{DL - Transaction ID}},
    transaction_gross_revenue: {{DL - Revenue}} * 100,
    transaction_currency: {{DL - Currency}}
  });
</script>

Custom-Events tracken

Lege weitere Tags für eigene Events an:

<script>
  // Add-to-Cart-Tag — Trigger auf add_to_cart-Event
  advPxl("event", "add_to_cart");
</script>

<script>
  // Initiated-Checkout-Tag — Trigger auf Checkout-Start
  advPxl("event", "initiated_checkout");
</script>

Empfohlene Trigger

Adverfly integriert sich nativ über Shopifys Customer-Events-API für genaues Tracking. Wenn du zusätzlich Personalisierungs-Widgets (Popups, Banner, Countdowns, Toasts) auf deinem Storefront ausspielen willst, ist ein zweiter winziger Schritt nötig — siehe „Optional: Widgets aktivieren" unten auf der Seite.

Installations-Schritte

1. Gehe zum Shopify-Admin
2. Navigiere zu Settings → Customer events
3. Klicke auf Add custom pixel
4. Nenne ihn „Adverfly“
5. Füge folgenden Code ein:

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", DEINE_WORKSPACE_ID);
  window.adverfly.store_currency = "EUR";
  window.adverfly.store_timezone = "Europe/Berlin";

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

Ersetze DEINE_WORKSPACE_ID mit deiner Workspace-ID und setze Währung sowie Zeitzone deines Shops.

Konfiguration

Getrackte Events

Die Shopify-Integration trackt automatisch alle Standard-E-Commerce-Events:

Optional: Widgets aktivieren

Der Shopify-Web-Pixel oben läuft in einer Sandbox und kann zwar Events tracken, aber kein UI im Storefront rendern. Um Adverfly-Personalisierungs-Widgets (Popups, Banner, Countdowns, Toasts) zu aktivieren, ergänzt du ein zweites kleines Snippet in deinem Theme — gleiches Muster wie Google Analytics oder jedes andere Tag.

1. Gehe in deinem Shopify-Admin auf Online Store → Themes → ⋯ → Edit code
2. Öffne layout/theme.liquid
3. Füge das Folgende direkt vor </head> ein:

<script async src="https://cdn.adverfly.com/preset-pixel-adv.js"></script>
<script>
  window.adverfly = window.adverfly || [];
  window.adverfly.activate_widgets = true;
  advPxl("init", YOUR_WORKSPACE_ID);
</script>

Der Theme-Pixel erkennt automatisch dass er auf Shopify läuft und feuert keine Pageview-/Vikey-Events — dafür ist der Web-Pixel oben zuständig. Der Theme-Pixel existiert nur, um Widgets im Storefront-DOM zu rendern. Keine doppelten Events.

Wer nur Tracking will (keine Widgets), kann diesen Abschnitt überspringen. Der Web-Pixel deckt Tracking allein ab.

Das @adverfly/sdk JavaScript-Paket holt für jeden Besucher die passende Variante und du renderst sie wie du willst — eigene React/Vue/Svelte-Komponenten, server-gerenderte HTML, sogar Mobile-Apps.

Der Standard-Pixel funktioniert weiterhin als No-Code-Lösung. Das SDK ist für:

• Pixelgenaue Brand-Kontrolle — kein iframe, keine CSS-Overrides
• Server-Side / Edge — Cloudflare Workers, Vercel Edge, Next.js Server Components
• Custom UI — Inline-Blocks, Mobile Screens, alles jenseits von Popup/Banner/Toast/Countdown
• Strikte Typen — dein config-Shape wird zum TypeScript-Generic

Installation

Drei Wege, gleicher Code — wähle was zu deinem Stack passt.

Vanilla <script> (kein Build-Schritt)

<script src="https://cdn.jsdelivr.net/npm/@adverfly/sdk/dist/adverfly.iife.js"></script>
<script>
  const adv = new Adverfly({ workspaceId: 188334 });
  /* `Adverfly` ist jetzt eine globale Klasse — kein Module-System nötig. */
</script>

In Production die Version pinnen: @adverfly/sdk@0.1.0/dist/adverfly.iife.js.

ES-Module im 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";

Funktioniert in Browsern und Node 18+. Keine Peer-Dependencies. Bundle ~6 KB minified im IIFE-Build, ~12 KB als 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) {
  zeigeMeinPopup({
    title: variant.config.title,
    copy: variant.config.copy,
    onCtaClick: () => adv.click(variant.id),
    onDismiss: () => adv.dismiss(variant.id),
  });
  await adv.trackImpression(variant.id);
}

Konstruktor

Identität

await adv.identify({
  email: "user@example.com",   // SHA-256 gehasht (lowercase) — nie roh übertragen
  transactionId: "order_123",  // optional, für Post-Purchase-Trigger
});

Identität zurücksetzen (z. B. bei Logout):

adv.reset();

Personalize

const variant = await adv.personalize<MyConfigShape>({
  trigger: "exit_intent",
  surface: "widget",  // optional, default: "widget"
  context: { device_battery_low: true },  // wird oben auf den Session-Context gemerged
});
// { id, config, reason } | null

Stark typisierter 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); // typisiert!
}

Tracking

Alle Tracking-Events landen in ClickHouse pixel_events — gleiche Tabelle wie der Standard-Pixel, joinbar via customer_id (gehasht) für Conversion-Attribution.

Events

Subscriben für Analytics, Debugging oder Custom-Render-Hooks.

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

/* Returns Unsubscribe-Funktion */
off();

Verfügbare Events: decision, impression, click, dismiss, auto_dismissed, success, error.

Server-Side / Edge

Funktioniert überall wo fetch + crypto.subtle existieren (Node 18+, Bun, Cloudflare Workers, Vercel Edge).

/* Cloudflare Worker — server-render einen personalisierten Hero-Block */
export default {
  async fetch(request: Request) {
    const adv = new Adverfly({
      workspaceId: 188334,
      manualIdentity: true,  // wir verwalten Identität selbst
    });
    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 werden clientseitig gehasht (SHA-256, lowercase + getrimmt) bevor irgendein Network-Call passiert.
• Keine Cookies vom SDK gesetzt. Anonymous-IDs in localStorage; Opt-out via manualIdentity: true.
• CORS-clean. POST + JSON, keine Preflight-Überraschungen.

Siehe auch

• Widgets — die No-Code-Pixel-Variante
• Tracking-Events — Basis-Event-Schema