Dokumentation

Wenn du die Provedly-App für Shopify nutzt, musst du nichts installieren: Das App-Embed im Theme lädt alles. Das WordPress-Plugin funktioniert unverändert weiter.

Das Website-Snippet deckt fast jeden Fall ab. Jedes Widget und jede Leiste hat zusätzlich ein eigenes Tag, unter Advanced im Tab Embed, für zwei Situationen: eine Inline-Leiste, die an einer genauen Stelle der Seite erscheinen muss (sie erscheint dort, wo ihr Tag eingefügt ist), und Page-Builder, die Code nur pro Block erlauben. Eine Seite mit beiden Arten von Tags lädt ein Element nie doppelt.

Der Konfigurations-Endpoint antwortet nur für Domains, die bei der Website eingetragen sind. Subdomains sind eingeschlossen, example.com deckt also auch shop.example.com ab. Staging-Hosts trägst du ausdrücklich ein. Eine leere Liste erlaubt jede Domain, was wir nicht empfehlen.

1. Das Website-Snippet stellt eine einzige Anfrage, GET https://provedly.app/api/s/{site key}/manifest. Sie liefert jedes aktive Widget und jede aktive Leiste mit Einstellungen und bis zu 30 aktuellen Datensätzen pro Widget sowie die aktuelle Codeversion.
2. Danach lädt es den Widget-Code und den Leisten-Code, aber nur, wenn die Seite sie braucht. Beides sind versionierte Dateien, die dein Browser bis zum nächsten Release im Cache behält.
3. Der Benachrichtigungszyklus startet nach deiner Startverzögerung. Jede Anzeige sendet eine Impression an /track.
4. Solange der Tab offen ist, ruft ein Heartbeat alle 30 Sekunden /presence für den Live-Zähler auf.

Füge ein Element dort ein, wo die Zahl erscheinen soll, zum Beispiel unter dem Produkttitel oder dem In-den-Warenkorb-Button. Auf Shopify nutzt du dafür einen Custom-liquid-Block im Theme-Editor. Das Website-Snippet füllt ihn mit derselben echten Zahl wie die Benachrichtigung (Besucher der letzten 90 Sekunden) und blendet ihn unter deinem Minimum aus.

<div data-provedly-live data-template="{n} people are viewing this product right now"></div>

Füge data-style="card" hinzu für eine Kartenversion mit großer Zahl und einem Verify-Link zu deiner Verifizierungsseite, oder data-dot="off", um den Punkt auszublenden. Bei mehreren Widgets auf einer Seite gibst du im Attribut (data-provedly-live="pp_…") ein Widget-Token an, um eins auszuwählen.

Video-Anleitungen: beliebige Website oder WordPress und Shopify.

• Schlüssel beginnen mit provedly_ und gehören zum Workspace, nicht zu einem einzelnen Widget.
• Der Schlüssel wird nur einmal angezeigt, beim Anlegen. Wir speichern nur einen Hash, also kopiere ihn sofort.
• Du kannst einen Schlüssel jederzeit auf derselben Seite widerrufen. Anfragen mit einem widerrufenen Schlüssel erhalten 401.

Widgets und Leisten akzeptieren ihre ID (eine UUID) oder ihr Token. Websites akzeptieren ihre ID oder ihre Domain.

Neue Leisten werden pausiert angelegt. Aktiviere eine mit PATCH /bars/{bar} {"status": "active"}.

Lesezugriffe liefern dieselben Felder, du kannst also ein Widget oder eine Leiste lesen, einen Wert ändern und alles zurückschicken. URL-Regeln akzeptieren eine Liste von Pfaden oder einen Pfad pro Zeile. Wenn die Änderung zwei aktive Elemente an dieselbe Stelle derselben Seiten setzt, enthält die Antwort einen warnings-Eintrag.

Branding, die öffentliche Verifizierungsseite, Beispieldatensätze und das detaillierte Design bleiben im Dashboard.

Impressionen und Klicks von Widgets und Leisten, verifizierte Bestellungen und Umsatz, durch Proof unterstützte Bestellungen und Umsatz sowie eine Aufschlüsselung pro Widget für die gewählte Anzahl Tage.

{ "error": "...", "message": "..." }

401  missing or invalid key
403  read-only key used for a change
404  not in this workspace
422  refused: validation, plan limit, or an ended or archived bar

Jeder Schlüssel kann 120 Anfragen pro Minute stellen.

get_account, list_sites, list_widgets, list_bars, get_stats, set_widget_status, update_widget, set_bar_status, create_bar, update_bar, add_record, get_install_snippet.

• Es gelten dieselben Tariflimits wie im Dashboard.
• Leisten, die ein Assistent anlegt, starten pausiert, bis du sie aktivieren lässt.
• Ein Nur-Lesen-Schlüssel kann nichts ändern.
• Datensätze, die über die API oder MCP hinzugefügt werden, werden nie als verifiziert markiert. Das gilt nur für signierte Webhooks von Stripe, Shopify und WooCommerce.

• „Wie viele Impressionen und verifizierte Bestellungen hatten meine Widgets in den letzten 7 Tagen?“
• „Leg auf example.com eine Countdown-Leiste für den Winter-Sale an, der am 1. Dezember um 9 Uhr New Yorker Zeit endet.“
• „Pausiere alle Widgets auf meiner Staging-Website.“
• „Gib mir den Installationscode für meinen Shop.“

Nur die Zahlen dieses Workspaces. Der Parameter tz ist optional.

Reihenfelder enthalten today, yesterday, change_pct, last_7d, last_30d, total, trend_24h, trend_7d, trend_30d.

Die Zahlen werden höchstens einmal pro Minute neu berechnet. Jeder Schlüssel kann 60 Anfragen pro Minute stellen.

201 Created
{ "id": 812, "hash": "9c1e0b7a…", "verified": false, "occurred_at": "2026-10-15T14:03:00+00:00" }

401 Unauthorized   wrong or missing bearer key
422 Unprocessable  validation errors, including a duplicate external_id

Das Widget zeigt API-Datensätze an, markiert sie aber nie als verifiziert. Die Verifiziert-Markierung ist signierten Webhooks vorbehalten. Siehe Webhooks.

• Kopfzeile erforderlich, Spalten in beliebiger Reihenfolge, zusätzliche Spalten werden ignoriert.
• Datumsangaben in ISO 8601. Fehlt ein Datum, gilt der Zeitpunkt des Imports.
• „Skip duplicates“ überspringt Zeilen, deren Name und Stadt innerhalb einer Stunde mit einem vorhandenen Datensatz übereinstimmen.
• Importierte Zeilen haben die Quelle csv und sind nicht verifiziert. Zeilen, die älter als dein Anzeigezeitraum sind, werden gespeichert, aber nicht angezeigt.

1. Füge im Tab Data des Widgets eine Stripe-Quelle hinzu. Kopiere die Endpoint-URL:

https://provedly.app/api/hooks/stripe/pp_your_widget_token

2. Gehe in Stripe zu Developers, Webhooks, Add endpoint. Füge die URL ein und wähle die Events, die dein Checkout sendet: checkout.session.completed für einmalige Checkout-Zahlungen, invoice.paid für Abos und payment_intent.succeeded nur, wenn du Payment Intents ohne Checkout belastest. Ein Kauf wird nur einmal erfasst, auch wenn mehrere davon ausgelöst werden.
3. Kopiere das Signing Secret (whsec_…) in das Secret-Feld der Quelle in Provedly.
4. Sende ein Test-Event aus Stripe. Die Quelle zeigt innerhalb weniger Sekunden „last event“ an.

Wir lesen den Namen des Kunden, Land und Stadt aus Liefer- oder Rechnungsadresse (falls vorhanden), die erste Position als Produkt und den formatierten Gesamtbetrag als Preis.

1. Installiere Provedly aus dem Shopify App Store (Eintrag folgt in Kürze).
2. Klicke auf der Startseite der App auf „Open theme editor“, prüfe, dass das Provedly-App-Embed aktiviert ist, und speichere. Kein Code, kein Script-Tag.
3. Bestellungen werden automatisch zu verifizierten Datensätzen: Die letzten 60 Tage werden bei der Installation importiert, und jede neue Bestellung kommt über einen signierten Webhook.

Die App läuft in deinem Shopify-Admin mit denselben Design-, Daten- und Analyse-Tools wie dieses Dashboard. Tarife werden über Shopify auf deiner normalen Shopify-Rechnung abgerechnet; der Free-Tarif braucht keine Zahlungsmethode. Namen und Städte von Käufern erscheinen erst, wenn Shopify der App den Zugriff auf Kundendaten genehmigt hat; bis dahin lauten die Benachrichtigungen „Someone just purchased…“.

1. Füge im Tab Data eine Shopify-Quelle hinzu und kopiere die URL:

https://provedly.app/api/hooks/shopify/pp_your_widget_token

2. Lege im Shopify-Admin unter Settings, Notifications, Webhooks einen Webhook für Order payment (orders/paid) im JSON-Format mit dieser URL an. Order creation funktioniert auch, wenn du unbezahlte Bestellungen einbeziehen willst; dieselbe Bestellung wird nie doppelt erfasst.
3. Kopiere das unter der Webhook-Liste angezeigte Shared Secret in das Secret-Feld der Quelle.

Payloads werden über den HMAC-SHA256-Header geprüft. Eine fehlgeschlagene Prüfung wird protokolliert und verworfen. Ohne Secret werden Events angenommen, aber in deinem Dashboard als „No signing secret set“ angezeigt und nicht als verifiziert markiert.

1. Füge im Tab Data eine WooCommerce-Quelle hinzu, kopiere die URL und wähle ein Signing Secret (eine beliebige Zeichenfolge mit mindestens 8 Zeichen):

https://provedly.app/api/hooks/woocommerce/pp_your_widget_token

2. Mit dem Plugin: Installiere Provedly von WordPress.org (Plugins, Installieren, nach „Provedly“ suchen), öffne Provedly im Admin-Menü, füge Widget-Token, URL und Secret ein und speichere. Das Plugin gibt die Script-Tags aus, legt den WooCommerce-Webhook an und übergibt für die Attribution die Besucher-ID an jede Bestellung.
3. Manuell: WooCommerce, Settings, Advanced, Webhooks, Add webhook. Thema Order updated, die Zustell-URL von oben, dasselbe Secret, API-Version WP REST API v3.

WooCommerce signiert jede Zustellung mit HMAC-SHA256 in X-WC-Webhook-Signature. Nur Bestellungen im Status Processing oder Completed werden zu Datensätzen, jeweils einmal. Ausstehende, fehlgeschlagene und stornierte Bestellungen erscheinen nie.

Das Dashboard zählt eine Bestellung nur dann als durch Proof unterstützt, wenn der Käufer eine Besucher-ID hatte, die in den 30 Tagen vor dem Kauf eine Benachrichtigung desselben Widgets gesehen hat. Nichts wird geschätzt. In Shopify-Shops mit der App passiert das automatisch: Das Widget schreibt die Besucher-ID als Attribut provedly_visitor in den Warenkorb, und der Bestell-Webhook liest sie wieder aus.

Überall sonst gibst du die Besucher-ID selbst weiter. Das Widget speichert sie im First-Party-Cookie pv_vid und stellt sie als window.Provedly.visitorId() bereit.

• Stripe: Setze metadata.provedly_visitor auf der Checkout Session oder dem PaymentIntent.
• Records-API: Sende sie im optionalen Feld visitor.

// at checkout time, on your site
const visitor = window.Provedly?.visitorId();
// Stripe: pass it as metadata.provedly_visitor
// Records API: POST { ..., "visitor": visitor }

Anzahl verifizierter Käufe für 24 Stunden, 7 Tage und insgesamt; Zeitfenster und Minimum des Live-Zählers; ob Beispiele angezeigt werden; ob nur verifizierte Käufe angezeigt werden; jede Quelle mit Zahlen und letztem Datensatz; verbundene Anbieter; aktuelle verifizierte Käufe als Hashes; und die nächtlichen SHA-256-Ledger-Roots. Namen und Städte erscheinen nie. Die Begründung findest du auf der Vertrauensseite.

Der Hash jedes Datensatzes wird zurückgegeben, wenn du ihn über die API anlegst. Der Root eines Tages ist der SHA-256 der sortierten Liste der Datensatz-Hashes dieses Tages. Bewahre deine Hashes auf, dann kannst du den Root selbst nachrechnen.

Wenn „Verified purchases only“ aktiviert ist und das Widget noch keine verifizierten Datensätze hat, gibt es nichts anzuzeigen. Die Widget-Seite weist darauf hin. Schalte die Einstellung aus oder verbinde einen Shop.

Warte etwa eine Minute und lade die Seite neu. Mit den Snippets pro Element können neue Codeversionen ein paar Minuten dauern.

• Öffne die Browser-Konsole. Ein 403 bei /api/w/…/config bedeutet, dass die Domain der Seite nicht zu den erlaubten Domains der Website gehört.
• Das Widget braucht mindestens einen Datensatz innerhalb des Anzeigezeitraums. Füge zum Testen einen Beispieldatensatz hinzu.
• Prüfe, ob der Widget-Status „active“ ist und der Workspace diesen Monat noch Impressionen übrig hat.
• Pfad-Targeting: Eine Einschlussliste, die nicht zum aktuellen Pfad passt, lässt das Widget stumm.

Er bleibt unter dem eingestellten Minimum ausgeblendet (Standard 2). Öffne die Seite in zwei Browsern oder in einem privaten Fenster und warte auf den ersten Heartbeat. Außerdem muss „Enable live counter“ aktiviert sein.

Das Signing Secret fehlt oder ist falsch. Die Karte der Quelle zeigt „No signing secret set“ oder die Zahl der Events steigt nicht mehr. Füge das Secret erneut ein und sende ein Test-Event.

Erhöhe den z-index im Abschnitt Look des Widgets. Der Standard ist 9999.