Compteur de backlinks pour un tableau de bord SaaS, étape par étape
Un compteur fonctionnel nécessite une route serveur et un petit composant. Ce guide construit les deux, en incluant les états d'échec que la plupart des premières versions oublient.
Équipe éditoriale AlfaLinks ·
Périmètre de ce guide
Nous partons du principe d'un backend Node ou Python et de n'importe quel framework front-end. Chaque requête ci-dessous touche l'API documentée, et l'URL de base est la vôtre : alfalinks.net/api.php.
Cinq étapes, dans l'ordre de déploiement recommandé
01
1. Créez la clé et stockez-la comme secret
Connectez-vous avec Google sur /auth/google.php, copiez la clé sk_ depuis la page du compte et placez-la dans l'environnement de votre serveur. Le front-end ne la voit jamais.
02
2. Ajoutez une route proxy
Exposez une route du type /internal/links?domain=... qui valide le domaine, appelle notre API et ne renvoie que les champs utilisés par votre interface. La validation est importante car les utilisateurs peuvent saisir n'importe quoi.
03
3. Commencez par l'action gratuite
L'action overview est gratuite, donc la première version du compteur ne présente aucun risque de facturation. Passez aux actions payantes uniquement lorsqu'un écran en a besoin.
04
4. Affichez trois états
Chargement, données, et indisponible. L'état indisponible couvre les erreurs HTTP 401, HTTP 402 et les échecs réseau, et il ne doit jamais afficher un zéro.
05
5. Ajoutez l'étiquette de fraîcheur
Notre index est actualisé environ mensuellement. Une ligne grise indiquant 'données des liens actualisées mensuellement' évite les tickets de support du type 'J'ai ajouté un lien hier'.
La route proxy, en Node
Assez court pour être lu en un seul écran. Le cache est ici un Map simple ; passez à Redis dès que vous exécutez plusieurs processus.
js
const cache = new Map();
const MONTH = 30 * 24 * 3600 * 1000;
app.get('/internal/links', async (req, res) => {
const domain = String(req.query.domain || '').toLowerCase().trim();
if (!/^[a-z0-9.-]+\.[a-z]{2,}$/.test(domain)) return res.status(400).json({ok:false});
const hit = cache.get(domain);
if (hit && Date.now() - hit.t < MONTH) return res.json(hit.v);
const r = await fetch(`https://alfalinks.net/api.php?action=overview&q=${domain}`);
if (!r.ok) return res.status(502).json({ok:false});
const v = await r.json();
cache.set(domain, {t: Date.now(), v});
res.json(v);
});
Ajout d'un badge DR une fois le compteur fonctionnel
Le compteur est la partie facile. Le badge nécessite un appel supplémentaire.
Pour une liste de domaines clients, envoyez une seule requête bulk_dr avec jusqu'à 2 000 domaines au lieu d'un appel par ligne. Cela coûte 1 crédit quel que soit le nombre de lignes, et la réponse associe chaque domaine à sa valeur 0-100, que vous stockez à côté de l'aperçu mis en cache.
Faites correspondre les domaines sur le nom d'hôte normalisé. Supprimez le schéma, le chemin et un 'www' éventuel, sinon la moitié de vos lignes ne trouveront pas de correspondance et afficheront des vides.
Affichez une valeur d'abord, puis demandez la configuration
Les nouveaux utilisateurs lisent rarement une page de configuration. Ils veulent voir si la fonctionnalité vaut l'effort, et un compteur de backlinks affichant un chiffre réel répond plus vite à cette question que n'importe quel formulaire. Mettez la valeur en premier. La configuration vient ensuite.
Comme l'action gratuite overview ne nécessite pas de clé, votre premier écran peut afficher un chiffre avant même que l'utilisateur n'ait configuré quoi que ce soit.
De quoi a besoin le premier rendu ?
Un seul domaine et un appel gratuit. Imaginez un nouvel utilisateur qui saisit son propre site lors de l'intégration et voit le compteur apparaître dans la même vue de page. Ce seul chiffre fait plus pour lancer la configuration qu'une liste d'étapes, alors gardez le reste de la configuration derrière cette valeur.
L'utilisateur voit ce qu'il obtiendra avant qu'on ne lui demande une carte, une clé ou un deuxième formulaire. Rien dans le premier rendu ne doit ressembler à une barrière.
Où placer l'invite de configuration ?
Juste après la valeur, pas avant. Une courte ligne comme 'Connectez un domaine pour suivre cela chaque mois' s'adapte sous le compteur. Si la même invite est placée au-dessus de la valeur, les utilisateurs la liront comme une barrière et partiront.
Suivez les utilisateurs qui complètent chaque étape de configuration. Un petit entonnoir montre où les utilisateurs s'arrêtent, et un changement de libellé fait souvent bouger ce chiffre plus qu'une nouvelle fonctionnalité.
Tests avant le lancement
Testez d'abord les cas d'erreur. Les cas heureux se testent d'eux-mêmes.
Révoquez la clé en environnement de test et confirmez que la carte affiche 'indisponible' plutôt que zéro. Puis videz un solde de test pour déclencher un 402, et saisissez une entrée malformée telle qu'un domaine avec un schéma et un chemin de fin, pour prouver que le validateur le rejette avant toute dépense de crédit.
Un test rapide de fumée appartient au CI. Un appel gratuit overview sur nytimes.com, exécuté quotidiennement, vous indique si la route et la clé fonctionnent encore.
Qui peut consulter quel domaine, et à quel coût
Un compteur qui accepte n'importe quelle chaîne est une porte ouverte vers votre solde. Décidez qui peut demander quoi avant que la route ne soit mise en production, et écrivez la réponse dans le code plutôt que dans une page wiki que personne n'ouvre.
Trois questions reviennent toujours : quels domaines, quelle limite, et où se trouve la clé.
Quels domaines un utilisateur doit-il pouvoir saisir ?
Uniquement ceux auxquels l'espace de travail a un droit, plus les recherches publiques que vous avez choisi d'offrir. Supposons qu'un espace de travail possède deux sites. La route peut accepter ces deux-là et rejeter tout le reste avec un message clair, ce qui empêche un client de dépenser des crédits sur des domaines qui ne sont pas les siens.
La vérification du nom d'hôte dans la route est le minimum. Elle prouve que l'entrée ressemble à un domaine, pas que l'utilisateur le possède, alors gardez la liste des droits dans votre propre base de données sous forme de table séparée.
Comment empêcher un utilisateur de vider le solde ?
Mettez une limite par espace de travail dans votre propre stockage et comptez les appels là-bas. Le solde de notre côté est un pool prépayé unique, donc il ne peut pas vous dire quel client a dépensé quoi. Les notes sur la page de recherche couvrent le côté public du même problème. Lorsqu'un espace de travail atteint sa limite, renvoyez un message simple et laissez le cache continuer à répondre avec ce qu'il contient déjà.
Choisissez la limite à partir des calculs des notes par siège, pas d'une estimation, et revoyez-la lors d'un changement de plan. Testez la route avec un deuxième espace de travail avant de faire confiance à la limite.
Le navigateur doit-il jamais détenir la clé ?
Non. La clé vit sur votre serveur, et le navigateur appelle votre route. Cette séparation est aussi ce qui rend une limite possible, car chaque appel facturé passe par du code que vous contrôlez. Si une clé apparaît jamais dans un bundle livré, faites-la tourner le jour même et vérifiez le journal des appels pour les appels que vous n'avez pas faits. Certaines équipes stockent la clé dans un fichier de configuration que le front-end lit au moment de la compilation, et ce fichier finit dans le bundle. Gardez la clé hors de tout ce que l'étape de build peut voir, et vérifiez les fichiers livrés une fois avant chaque release.
Les actions gratuites peuvent être appelées depuis une page publique sans clé, et c'est le seul cas où le navigateur peut parler à l'API directement.
Ce que le compteur doit dire, et ce qu'il ne doit pas dire
Dites moins que ce que vous savez. Un compteur étiqueté 'backlinks' invite la question 'pourquoi Ahrefs montre-t-il un chiffre différent ?', et la réponse honnête est que deux crawlers voient deux parties du web.
Étiquetez plutôt la valeur avec sa source et son mois. Quelque chose comme 'Domaines référents, index AlfaLinks, octobre 2026' est plus long, mais cela termine l'argument avant qu'il ne commence et cela se lit bien dans une petite carte.
Arrondissez pour l'affichage. Un utilisateur qui voit 12 481 le lundi et 12 481 le vendredi fait plus confiance à l'outil qu'un utilisateur qui voit des variations, et notre actualisation mensuelle vous donne cette stabilité gratuitement.
Si vous voulez la valeur 0-100 à côté, lisez d'abord les notes sur un score de backlinks. C'est notre propre métrique, donc le nommage est important.
États d'échec et comportement de l'interface
Les codes HTTP sont ceux renvoyés par l'API ; la colonne UI est notre suggestion.
Signal
Signification
Ce que voit l'utilisateur
Ce que vous faites
HTTP 401
Clé manquante ou invalide
'Données des liens indisponibles'
Pagez-vous : bug de déploiement
HTTP 402
Crédits épuisés
'Données des liens indisponibles'
Rechargez avec USDT (TRC-20)
ok: false
Requête rejetée
Lien de retry en ligne
Journalisez le domaine et l'action
Délai d'attente dépassé
Problème réseau
Valeur mise en cache si vous en avez une
Réessayez une fois, puis réduisez la fréquence
Garder le compteur honnête dans le support et les logs
Un compteur échoue plus souvent silencieusement qu'à haute voix. Journalisez suffisamment pour répondre à la question suivante qu'un client pose, et gardez les données personnelles hors du journal entièrement. Les lignes courtes gagnent. Une ligne qui répond à une question de support fait gagner plus de temps que n'importe quelle alerte que vous pourriez écrire.
La plupart des fils de support concernant un compteur sont l'une des trois questions, alors planifiez le journal autour d'elles. Gardez ces trois questions dans votre runbook, à côté des étapes pour faire tourner une clé.
Que doit enregistrer chaque ligne de journal ?
L'action, le domaine, le code de statut, l'âge du cache et le solde de crédit qui est revenu. Ces cinq champs répondent à la plupart des questions de support. Supposons qu'un utilisateur demande pourquoi son compteur affiche une ancienne valeur. L'âge du cache et le mois de l'index vous disent si le problème vient du cache ou de l'étiquette.
Laissez la clé API hors de chaque ligne, y compris les traces d'erreur. Masquez-la au niveau du logger, car une ligne fuitée peut vider tout le compte.
Comment savoir que le compteur est en bonne santé chaque semaine ?
Surveillez trois chiffres : la part des états indisponibles, la tendance du solde de crédits et le taux de hit du cache. Une augmentation soudaine des états indisponibles pointe généralement vers un problème de clé ou de solde. Une baisse lente du solde pointe généralement vers une clé de cache trop spécifique.
Chaque lecture a une correction différente, c'est pourquoi une seule tuile de tableau de bord pour les trois aide rarement quiconque. Mettez les trois lectures sur une ligne dans votre note hebdomadaire, avec la dernière valeur et le changement depuis la semaine précédente. Les nombres lus isolément invitent aux suppositions, tandis qu'une courte tendance maintient la conversation sur les mêmes faits.
