Widgets

Adverfly Widgets rendern personalisierte Popups, Banner, Countdowns und Toast-Benachrichtigungen auf deiner Storefront. Welche Variante ein Besucher sieht, entscheidet die Personalization-Engine live in Echtzeit anhand seines Segments.

So funktioniert es

Besucher öffnet die Seite
   ↓
Pixel ruft /public/personalize mit customer_id + Session-Kontext
   ↓
Engine bewertet aktive Widgets für den Trigger und das Segment des Besuchers
   ↓
Pixel rendert die Gewinner-Variante (Popup / Banner / Countdown / Toast)
   ↓
Alle Interaktionen (Impression, Klick, Dismiss, Success) werden in ClickHouse gespeichert

Du gestaltest Widgets in der Adverfly-App unter Widgets. Jedes Widget zielt auf ein Segment (oder „Alle") und wird automatisch ausgespielt sobald sein Trigger feuert.

Installation

Der Widget-Pixel ist Teil des Standard-Tracking-Pixels — wenn preset-pixel-adv.js (v3) bereits eingebaut ist, funktionieren Widgets ohne weiteren Code.

Shopify

Füge das Adverfly-Script-Tag in deine layout/theme.liquid ein (direkt vor </head>) — gleiches Muster wie Google Analytics oder jedes andere Tag. Der Pixel liefert den Widget-Renderer im Storefront-DOM, wo die Shopify-Web-Pixel-Sandbox keinen Zugriff hat.

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

Der Pixel erkennt Shopify automatisch und unterdrückt auto-Pageview- und Vikey-Events, damit nichts doppelt gezählt wird — die laufen über den Shopify-Web-Pixel. Widgets rendern normal.

Inline-Platzierungen: pack ein <div data-adv-inline data-adv-trigger="…" data-adv-workspace="…"> in eine beliebige Section (siehe Inline-Widgets unten).

Andere Plattformen (theme.liquid, GTM, manuell)

Wenn das Adverfly-Pixel bereits auf deiner Seite läuft, aktiviere Widgets pro Workspace mit window.adverfly.activate_widgets = true vor advPxl("init", ...). Ohne dieses Flag ruft das Pixel /personalize nicht automatisch auf — manuelle advWidgets.fetchAndRender(...)-Aufrufe funktionieren weiterhin.

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

Auto-Trigger

Sobald activate_widgets = true gesetzt ist, feuern Widgets automatisch je nach trigger_type:

Manuelles Auslösen

Wenn du ein Widget aus deinem eigenen Code triggern willst (z. B. nach einem Custom-Event), ruf advWidgets.fetchAndRender auf:

/* Triggert ein Widget mit trigger="custom_event" */
window.advWidgets.fetchAndRender("custom_event");

/* Zusätzlichen Kontext übergeben — fließt in die Engine-Bewertung ein */
window.advWidgets.fetchAndRender("post_purchase", {
  transaction_id: "order_123",
  cart_value: 49.9,
});

Inline Widgets

Inline-Widgets erscheinen nicht als Overlay sondern an einer festen Position in deinem Content. Setze ein <div> mit data-adv-inline ein:

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

Lege in Adverfly ein Widget mit trigger_type = "inline" und passendem trigger-Wert an (z. B. pdp_above_cta). Das Pixel mountet die personalisierte Variante beim Laden in dieses Div.

Erfasste Events

Jede Widget-Interaktion wird automatisch in ClickHouse pixel_events gespeichert — gleiche Pipeline wie Survey-Events, joinbar via customer_id.

Gemeinsame Felder pro Event

Jedes Widget-Event trägt diese Felder (passt zum Survey-Schema für einfaches Joinen):

Goal-Tracking (Success-API)

Wenn ein Besucher das Ziel eines Widgets erreicht — Email einträgt, Rabatt-Code annimmt, sich registriert — ruf die Success-API auf. Sie sendet ein widget_success-Event, das du später für Conversion-Analytics auswerten kannst.

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

Die Roh-Email wird nie übertragen — der Pixel hasht sie clientseitig. Übergib email_hashed direkt, wenn du bereits selbst gehasht hast.

Widgets mit Conversions verknüpfen

Widget-Events liegen in pixel_events, Conversions in pixel_conversions. Join via customer_id (gehasht) oder visitor_id für anonyme Attribution.

-- Click-Through-Rate pro Widget, letzte 30 Tage
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;

Nur manueller Modus

Ohne activate_widgets = true feuern keine Auto-Trigger — window.advWidgets.fetchAndRender(trigger, extra) funktioniert aber weiterhin für vollständig manuelles Rendering. Nutze das, wenn du die volle Kontrolle darüber willst, wann /personalize aufgerufen wird.

Siehe auch

• Tracking-Events — Basis-Event-API
• Umfragen — Schwesterprodukt mit gleicher Event-Pipeline
• Pixel-Installation — wie das Pixel bootet