Documentation

Si vous utilisez l'app Provedly pour Shopify, n'installez rien : l'app embed du thème charge tout. Le Extension WordPress continue de fonctionner tel quel.

Le snippet du site couvre presque tous les cas. Chaque widget et chaque barre a aussi sa propre balise, dans Advanced sur son onglet Embed, pour deux situations : une barre intégrée qui doit s'afficher à un endroit précis de la page (elle apparaît là où sa balise est collée), et les constructeurs de pages qui n'acceptent du code que par bloc. Une page qui contient les deux types de balises ne charge jamais un élément deux fois.

L'endpoint de configuration ne répond qu'aux domaines listés sur le site. Les sous-domaines sont inclus : example.com couvre donc shop.example.com. Ajoutez explicitement vos hôtes de préproduction. Une liste vide autorise n'importe quel domaine, ce que nous déconseillons.

1. Le snippet du site fait une seule requête, GET https://provedly.app/api/s/{site key}/manifest, qui renvoie chaque widget et barre actifs avec leurs réglages et jusqu'à 30 enregistrements récents par widget, ainsi que la version actuelle du code.
2. Il charge ensuite le code du widget et celui de la barre, seulement si la page en a besoin. Ce sont deux fichiers versionnés que votre navigateur garde en cache jusqu'à la prochaine version.
3. Le cycle des notifications démarre après le délai initial que vous avez choisi. Chaque affichage envoie une impression à /track.
4. Tant que l'onglet est ouvert, un signal de présence appelle /presence toutes les 30 secondes pour le compteur en direct.

Ajoutez un élément là où le nombre doit apparaître, par exemple sous le titre du produit ou le bouton Ajouter au panier. Sur Shopify, utilisez un bloc Custom liquid dans l'éditeur de thème. Le snippet du site le remplit avec le même nombre réel que la notification (visiteurs vus au cours des 90 dernières secondes) et le masque sous votre minimum.

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

Ajoutez data-style="card" pour une version en carte avec le nombre en grand et un lien Verify vers votre page de vérification, ou data-dot="off" pour retirer le point. Avec plusieurs widgets sur une page, mettez le token d'un widget dans l'attribut (data-provedly-live="pp_…") pour choisir lequel.

Tutoriels vidéo : n'importe quel site ou WordPress et Shopify.

• Les clés commencent par provedly_ et appartiennent à l'espace de travail, pas à un widget précis.
• La clé ne s'affiche qu'une fois, à sa création. Nous n'en gardons qu'un hash : copiez-la tout de suite.
• Révoquez une clé à tout moment depuis la même page. Les requêtes avec une clé révoquée reçoivent un 401.

Les widgets et les barres acceptent leur id (un UUID) ou leur token. Les sites acceptent leur id ou leur domaine.

Les nouvelles barres sont créées en pause. Activez-en une avec PATCH /bars/{bar} {"status": "active"}.

Les lectures renvoient les mêmes champs : vous pouvez lire un widget ou une barre, changer une valeur et la renvoyer. Les règles d'URL acceptent une liste de chemins ou un chemin par ligne. Si la modification place deux éléments actifs au même endroit sur les mêmes pages, la réponse contient une entrée warnings.

Le branding, la page de vérification publique, les enregistrements d'exemple et le design détaillé restent dans le tableau de bord.

Impressions et clics des widgets et des barres, commandes et chiffre d'affaires vérifiés, commandes et chiffre d'affaires assistés par la preuve, et un détail par widget sur le nombre de jours choisi.

{ "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

Chaque clé peut faire 120 requêtes par minute.

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.

• Les mêmes limites d'offre s'appliquent que dans le tableau de bord.
• Les barres créées par un assistant démarrent en pause jusqu'à ce que vous demandiez de les activer.
• Une clé en lecture seule ne peut rien modifier.
• Les enregistrements ajoutés via l'API ou MCP ne sont jamais marqués comme vérifiés. Seuls les webhooks signés de Stripe, Shopify et WooCommerce le sont.

• « Combien d'impressions et de commandes vérifiées mes widgets ont-ils eues sur les 7 derniers jours ? »
• « Crée une barre de compte à rebours sur example.com pour les soldes d'hiver qui se terminent le 1er décembre à 9 h, heure de New York. »
• « Mets en pause tous les widgets de mon site de préproduction. »
• « Donne-moi le code d'installation de ma boutique. »

Uniquement les chiffres de cet espace de travail. Le paramètre tz est facultatif.

Les champs de série contiennent today, yesterday, change_pct, last_7d, last_30d, total, trend_24h, trend_7d, trend_30d.

Les chiffres sont recalculés au plus une fois par minute. Chaque clé peut faire 60 requêtes par minute.

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

Le widget affiche les enregistrements de l'API, mais ne les marque jamais comme vérifiés. La mention vérifiée est réservée aux webhooks signés. Voir Webhooks.

• Ligne d'en-tête obligatoire, colonnes dans n'importe quel ordre, colonnes en trop ignorées.
• Dates au format ISO 8601. Sans date, l'heure de l'import est utilisée.
• « Skip duplicates » ignore les lignes dont le nom et la ville correspondent à un enregistrement existant à moins d'une heure d'écart.
• Les lignes importées ont la source csv et ne sont pas vérifiées. Les lignes plus anciennes que votre fenêtre d'affichage sont conservées, mais pas affichées.

1. Dans l'onglet Data du widget, ajoutez une source Stripe. Copiez l'URL de l'endpoint :

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

2. Dans Stripe, allez dans Developers, Webhooks, Add endpoint. Collez l'URL et sélectionnez les événements envoyés par votre checkout : checkout.session.completed pour les paiements Checkout ponctuels, invoice.paid pour les abonnements, et payment_intent.succeeded uniquement si vous encaissez des Payment Intents sans Checkout. Un achat n'est enregistré qu'une fois, même si plusieurs de ces événements se déclenchent.
3. Copiez le secret de signature (whsec_…) dans le champ secret de la source dans Provedly.
4. Envoyez un événement de test depuis Stripe. La source affiche « last event » en quelques secondes.

Nous lisons le nom du client, le pays et la ville de livraison ou de facturation s'ils sont présents, le premier article comme produit et le total formaté comme prix.

1. Installez Provedly depuis le Shopify App Store (fiche bientôt disponible).
2. Sur la page d'accueil de l'app, cliquez sur « Open theme editor », vérifiez que l'app embed Provedly est activé, puis enregistrez. Sans code, sans balise script.
3. Les commandes deviennent automatiquement des enregistrements vérifiés : les 60 derniers jours sont importés à l'installation et chaque nouvelle commande arrive par un webhook signé.

L'app fonctionne dans votre admin Shopify avec les mêmes outils de design, de données et d'analyse que ce tableau de bord. Les offres sont facturées par Shopify sur votre facture Shopify habituelle ; l'offre Free ne demande aucun moyen de paiement. Les noms et villes des acheteurs n'apparaissent qu'une fois que Shopify a approuvé l'accès de l'app aux données clients ; d'ici là, les notifications affichent « Someone just purchased… ».

1. Ajoutez une source Shopify dans l'onglet Data et copiez l'URL :

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

2. Dans l'admin Shopify, Settings, Notifications, Webhooks, créez un webhook pour Order payment (orders/paid), au format JSON, avec cette URL. Order creation fonctionne aussi si vous voulez inclure les commandes non payées ; une même commande n'est jamais enregistrée deux fois.
3. Copiez le secret partagé affiché sous la liste des webhooks dans le champ secret de la source.

Les payloads sont vérifiés grâce à l'en-tête HMAC-SHA256. Un échec est journalisé et l'événement ignoré. Sans secret, les événements sont acceptés mais affichés « No signing secret set » dans votre tableau de bord, et ne sont pas marqués comme vérifiés.

1. Ajoutez une source WooCommerce dans l'onglet Data, copiez l'URL et choisissez un secret de signature (n'importe quelle chaîne d'au moins 8 caractères) :

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

2. Avec le plugin : installez Provedly depuis WordPress.org (Extensions, Ajouter, recherchez « Provedly »), ouvrez Provedly dans le menu d'administration, collez le token du widget, l'URL et le secret, puis enregistrez. Le plugin ajoute les balises script, crée le webhook WooCommerce et transmet l'id du visiteur avec chaque commande pour l'attribution.
3. Manuellement : WooCommerce, Settings, Advanced, Webhooks, Add webhook. Sujet Order updated, l'URL de livraison ci-dessus, le même secret, version d'API WP REST API v3.

WooCommerce signe chaque envoi en HMAC-SHA256 dans X-WC-Webhook-Signature. Seules les commandes en Processing ou Completed deviennent des enregistrements, une fois chacune : les commandes en attente, échouées ou annulées n'apparaissent jamais.

Le tableau de bord ne compte une commande comme assistée par la preuve que si l'acheteur portait un id de visiteur ayant vu une notification du même widget dans les 30 jours précédant l'achat. Rien n'est estimé. Sur les boutiques Shopify qui utilisent l'app, c'est automatique : le widget écrit l'id du visiteur dans le panier sous l'attribut provedly_visitor et le webhook de commande le relit.

Partout ailleurs, transmettez vous-même l'id du visiteur. Le widget le conserve dans le cookie first-party pv_vid et l'expose via window.Provedly.visitorId().

• Stripe : définissez metadata.provedly_visitor sur la Checkout Session ou le PaymentIntent.
• API des enregistrements : envoyez-le dans le champ facultatif visitor.

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

Le nombre d'achats vérifiés sur 24 heures, 7 jours et depuis le début ; la fenêtre et le minimum du compteur en direct ; si des exemples sont affichés ; si seuls les achats vérifiés sont affichés ; chaque source avec ses chiffres et son dernier enregistrement ; les fournisseurs connectés ; les achats vérifiés récents sous forme de hashes ; et les racines SHA-256 nocturnes du registre. Les noms et les villes n'apparaissent jamais. Lisez la page Confiance pour comprendre pourquoi.

Le hash de chaque enregistrement est renvoyé quand vous le créez via l'API. La racine d'un jour est le SHA-256 de la liste triée des hashes des enregistrements de ce jour. Conservez vos hashes et vous pourrez recalculer la racine vous-même.

Si « Verified purchases only » est activé et que le widget n'a encore aucun enregistrement vérifié, il n'a rien à afficher. La page du widget vous le signale. Désactivez ce réglage ou connectez une boutique.

Patientez environ une minute, puis rechargez la page. Avec les snippets par élément, les nouvelles versions du code peuvent prendre quelques minutes.

• Ouvrez la console du navigateur. Un 403 sur /api/w/…/config signifie que le domaine de la page ne fait pas partie des domaines autorisés du site.
• Le widget a besoin d'au moins un enregistrement dans la fenêtre d'affichage. Ajoutez un enregistrement d'exemple pour tester.
• Vérifiez que le statut du widget est « active » et qu'il reste des impressions à l'espace de travail ce mois-ci.
• Ciblage par chemin : une liste d'inclusion qui ne correspond pas au chemin actuel rend le widget muet.

Il est masqué sous le minimum que vous avez fixé (2 par défaut). Ouvrez la page dans deux navigateurs, ou dans une fenêtre privée, et attendez le premier signal de présence. Il faut aussi activer « Enable live counter ».

Le secret de signature est absent ou incorrect. La carte de la source affiche « No signing secret set » ou le nombre d'événements cesse d'augmenter. Collez à nouveau le secret et renvoyez un événement de test.

Augmentez le z-index dans la section Look du widget. La valeur par défaut est 9999.