Documentazione
Come funziona Harku — il widget di feedback leggero che porta un'idea dal suggerimento fino al lancio, da un unico script.
Cos'è Harku
Harku è un widget di feedback incorporabile per indie dev e micro-SaaS. Incolla una riga di script nel tuo sito — come installare un widget di chat — e i tuoi utenti possono proporre idee, votarle, seguire una roadmap pubblica e leggere il tuo changelog.
Gestisci tutto dal dashboard di Harku: filtra i suggerimenti per voti, spostali lungo il loro ciclo di vita e pubblica annunci. Questo chiude il ciclo — un utente propone → tu prioritizzi → costruisci → annunci.
Il widget
Il widget è un piccolo pulsante flottante Feedback che si carica da un unico script asincrono. Cliccandolo si apre un pannello dentro un iframe isolato, così gli stili del tuo sito e quelli del widget non interferiscono mai tra loro.
- Suggerimenti — la lista delle idee, ordinata per voti, con upvote in un clic.
- Nuovo suggerimento — un modulo breve (un titolo, più una descrizione opzionale).
- Roadmap — cosa è pianificato, in corso e consegnato.
- Novità — i tuoi annunci pubblicati, con un badge non letto.
Il widget è di sola lettura tranne per due azioni: creare un suggerimento e votare. Tutto il resto riflette semplicemente ciò che gestisci nel dashboard.
Voto anonimo
Non è richiesto alcun login per votare o suggerire. Al primo caricamento il widget genera un id casuale e lo conserva nel browser del visitatore, usandolo solo per impedire i doppi voti — il database impone un voto per id per post. I voti sono ottimistici (il conteggio si aggiorna istantaneamente) e reversibili.
Poiché l'id vive nel browser, non è legato a nessuna identità e può essere cancellato. Previene i doppi voti casuali, non gli abusi deliberati.
Il ciclo di vita
Ogni suggerimento passa attraverso uno stato che controlli dal dashboard:
- Aperto — appena suggerito, raccoglie voti.
- Pianificato — hai deciso di costruirlo.
- In corso — in lavorazione.
- Consegnato — fatto. Non viene mai eliminato, quindi rimane visibile, e può essere collegato a una voce del changelog.
- Rifiutato — non pianificato; tenuto fuori dalla roadmap.
Chiudere il ciclo
La roadmap pubblica mostra Pianificato, In corso e Consegnato. Il changelog è dove annunci ciò che è arrivato — opzionalmente collegato al suggerimento che lo aveva richiesto, così le persone che hanno votato vedono la loro idea prendere vita.
Il dashboard
Accedi con email e password, crea un progetto per ogni sito che possiedi, e ottieni:
- Progetti — uno per sito, ognuno con la propria chiave pubblica e aspetto (colore principale, posizione del pulsante, chiaro/scuro).
- Suggerimenti — ordinati per voti; sposta ognuno tra gli stati o nascondi lo spam.
- Board della roadmap — una board drag-and-drop dove puoi anche aggiungere i tuoi elementi.
- Editor delle novità — scrivi annunci, opzionalmente collegati a un suggerimento consegnato.
Sotto il cofano
Il widget non parla mai direttamente con il tuo database. Chiama una piccola API pubblica — validata dalla chiave pubblica del tuo progetto — per tutto ciò che fa: leggere suggerimenti, crearne uno, votare e recuperare la config e il changelog. I dati del proprietario sono protetti dalla row-level security; solo le operazioni sicure e pubbliche vengono mai esposte.
Pronto ad aggiungerlo? Vedi la guida all'installazione.