MeterFlow Inizia qui: il quadro generale
MeterFlow risponde a una sola domanda per il tuo prodotto: “chi ha usato quanto, di cosa — e quanto gli costa?” Tutto ciò che vedi nella dashboard esiste per rispondere a questa domanda.
user-842 o un’email).Come si incastrano i pezzi
Perché alcuni pulsanti “Crea” sono disattivati?
Ogni finestra disattiva il pulsante di conferma finché tutti i campi obbligatori (contrassegnati con *) non sono compilati — es. “Create plan” resta disattivato finché il piano non ha un Nome. Se un pulsante sembra bloccato, controlla se c’è un campo obbligatorio vuoto più in alto.
Nuova organizzazione contenitore
Il contenitore più esterno — di solito la tua azienda. Tutto il resto (progetti, meter, piani…) vive dentro un’organizzazione. Ne hai ricevuta una automaticamente al momento della registrazione.
📍 Dashboard → il pulsante “New organization” (proposto anche al primo accesso, quando non ne hai ancora una)
- Name *
Il nome della tua azienda o del tuo team. È solo un’etichetta — puoi cambiarla in seguito.
- Billing email
Dove arriverebbero fatture e comunicazioni di fatturazione per il tuo account MeterFlow. Facoltativa; il formato viene validato, ma non viene inviato nulla per verificarla.
finance@acme.dev. I suoi due prodotti diventeranno due progetti al suo interno.Nuovo progetto contenitore
Un progetto = un prodotto o ambiente da misurare. Ogni meter, piano, chiave API, saldo cliente ed evento di utilizzo appartiene a un solo progetto — i progetti non vedono mai i dati l’uno dell’altro.
📍 Dashboard → il pulsante “New project” nell’intestazione della tabella Projects
- Organization *
A quale organizzazione appartiene il progetto. Pre-selezionata se ne hai già una attiva.
- Name *
Il nome del prodotto, es. “PixelForge AI”. Compare in tutta la dashboard e nel selettore di progetto.
- Description
Testo libero, per tuo riferimento.
Genera chiave API accesso
La credenziale che la tua applicazione usa per parlare con MeterFlow. Il tuo backend la passa all’SDK; ogni evento di utilizzo, operazione sui crediti e chiamata sugli abbonamenti viene autenticata — e limitata a un solo progetto — da questa chiave.
📍 Apri un progetto → API Keys → il pulsante nell’intestazione della tabella
- Key name *
Un’etichetta per ricordarti dove viene usata la chiave — “Backend di produzione”, “Staging”, “Test CI”. Nessun effetto tecnico.
- Environment
Le chiavi Live iniziano con
mf_live_, quelle Test conmf_test_— e accedono a due set di dati completamente separati nello stesso progetto. Abbonamenti, crediti e utilizzo creati con una chiave Test sono invisibili alle chiavi Live (e viceversa), mentre meter e piani sono condivisi: i test girano sempre sulla tua configurazione di fatturazione reale. Usa le chiavi Test per sviluppo, staging e CI; le Live solo per il traffico reale di produzione.
mf_live_a1b2… una sola volta e la metti nelle variabili d’ambiente del tuo server: new MeterFlow({ apiKey: process.env.METERFLOW_KEY }). L’elenco nella dashboard mostrerà per sempre solo il prefisso e le ultime 4 cifre.Nuovo meter concetto chiave
Un meter è la definizione di un contatore con un nome: dichiara una cosa del tuo prodotto che vale la pena misurare, e come gli eventi grezzi vanno trasformati in un numero. Immaginalo come creare una nuova colonna in un report di utilizzo, prima ancora che esistano i dati.
📍 Apri un progetto → Meters → il pulsante nell’intestazione della tabella
- Name *
L’etichetta leggibile mostrata nella dashboard — “Immagini generate”, “Secondi di rendering video”. Serve solo agli occhi umani.
- Event name *
La chiave “per le macchine” — e sì, viene salvata nel database e confrontata alla lettera. Quando la tua applicazione segnala un utilizzo, invia un nome evento; MeterFlow cerca nel progetto il meter attivo il cui
event_namecorrisponde esattamente, maiuscole/minuscole comprese. Se non esiste, l’evento viene rifiutato con un errore 404 (“No active meter found for event …”) e non viene registrato nulla. Ogni nome evento è unico all’interno di un progetto. Convenzione: minuscolo con punti, es.image.generated. - Aggregation type
Come tanti eventi singoli vengono combinati in un unico numero nei riepiloghi di utilizzo. Vedi la tabella qui sotto — è il cuore del meter.
- Aggregation field
Obbligatorio per ogni tipo tranne Count. Indica quale campo numerico dell’evento contiene la quantità da aggregare — risponde alla domanda “somma di cosa?”. In pratica la tua app invia il numero nel campo
valuedell’evento, ed è quello che viene aggregato; l’aggregation field documenta cosa significa quel valore (es.seconds,tokens,megabytes), così chi legge il meter conosce l’unità di misura. Per Count è irrilevante — per contare basta che l’evento esista. - Description
Testo libero per il tuo team.
I tipi di aggregazione, con un esempio
Supponiamo che il cliente user-842 generi 4 eventi questo mese con valori 3, 10, 2, 10. Per ogni meter viene riportato un solo numero — quale, dipende dal tipo di aggregazione:
| Tipo | A quale domanda risponde | Risultato per 3, 10, 2, 10 | Uso tipico |
|---|---|---|---|
| Count | Quante volte è successo? (valori ignorati) | 4 | Immagini generate, chiamate API, esportazioni |
| Sum | Quanto in totale? | 25 | Secondi di rendering, token consumati, GB trasferiti |
| Max | Qual è stato il valore più alto? | 10 | Picco di job simultanei, upload più grande |
| Min | Qual è stato il valore più basso? | 2 | Raramente per fatturare — più che altro diagnostica |
| Unique count | Quanti valori distinti sono comparsi? | 3 (3, 10, 2) | Giorni attivi distinti, documenti distinti toccati |
video.rendered · Aggregazione Sum · Aggregation field seconds.La tua app finisce il rendering di una clip di 42 secondi per
user-842 e segnala l’evento video.rendered con valore 42. Fallo qualche volta e la pagina di utilizzo del cliente mostrerà una riga: Video render seconds — 3 eventi — 117.Il nome evento deve corrispondere a quello che invia la mia app? E se c’è un refuso?
Sì — alla lettera, maiuscole comprese. Il nome evento del meter è salvato nel database e funziona come l’etichetta di indirizzo per gli eventi in arrivo. Se la tua app invia video.render ma il meter dice video.rendered, l’API risponde 404 “No active meter found for event 'video.render' in this project” e l’evento non viene salvato. È voluto: un refuso silenzioso farebbe perdere per sempre utilizzo non fatturato. Prima crea il meter, poi inizia a inviare eventi con lo stesso nome.
Posso cambiare il tipo di aggregazione in seguito?
No — dopo la creazione si possono modificare solo nome, descrizione e stato attivo. L’aggregazione definisce cosa significa lo storico già salvato, quindi cambiarla a posteriori riscriverebbe il passato. Se ti serve un calcolo diverso, crea un nuovo meter con un nuovo nome evento.
Perché “Aggregation field” è facoltativo nel modulo, se è indicato come obbligatorio?
Il modulo lo lascia compilabile a piacere perché è obbligatorio solo per i tipi diversi da Count — è il server a far rispettare la regola. Se scegli Sum/Max/Min/Unique count e lo lasci vuoto, la creazione viene rifiutata con un chiaro errore di validazione; con Count puoi ignorare del tutto il campo.
Nuovo piano concetto chiave
Un piano è una fascia di prezzo — “Free”, “Pro a 29 $/mese”… Abbina un prezzo ricorrente a un insieme di limiti sui meter che dicono quanto di ogni funzione misurata è incluso e cosa succede oltre. I clienti vengono collegati a un piano tramite un abbonamento.
📍 Apri un progetto → Plans → il pulsante nell’intestazione della tabella
- Name *
Il nome della fascia — “Free”, “Pro”, “Enterprise”. Obbligatorio; il pulsante di creazione resta disattivato finché non è compilato.
- Description
Testo libero, es. lo slogan della fascia per il marketing.
- Price / Currency / Billing period
Il canone ricorrente dell’abbonamento: Price è l’importo (0 va benissimo per una fascia gratuita), Currency un codice come
USD, e Billing period la cadenza — mensile, annuale, settimanale o una tantum. Fissi dopo la creazione — modificando il piano in seguito non si possono cambiare (crea piuttosto un nuovo piano, così le condizioni degli abbonati esistenti non cambiano di nascosto). - Trial days
Giorni gratuiti all’inizio di ogni nuovo abbonamento. Con
14, un nuovo abbonato passa 2 settimane in stato “trialing” prima che inizi il periodo a pagamento.0= nessuna prova. - Public
Se il piano è visibile alla tua applicazione tramite l’elenco piani dell’SDK (es. per mostrare la tua pagina prezzi). Non spuntato = interno/nascosto — utile per accordi enterprise su misura o piani ancora in bozza.
Limiti sui meter — la sezione “+ Add limit”
Ogni riga di limite collega questo piano a un meter e risponde: quanto di quella cosa è incluso, e cosa succede oltre?
- Meter *
A quale grandezza misurata si applica il limite. Il menu elenca i meter che hai creato in questo progetto — niente di più, niente di meno. Non è un catalogo fisso: per ogni nuova funzionalità del prodotto basta creare prima un nuovo meter, e compare qui immediatamente.
- Included units
La quantità compresa nel prezzo del piano, per periodo di fatturazione. “Pro include 500 immagini al mese” →
500. - Overage rate
Il prezzo in crediti per unità quando il cliente supera le unità incluse.
0.5significa che ogni unità extra costa mezzo credito dal saldo del cliente. Ha senso solo con il tipo di limite Metered. - Limit type
Hard (blocca) — l’utilizzo oltre le unità incluse va rifiutato; il cliente trova un muro. Soft (avvisa) — l’utilizzo continua, ma vieni avvisato così puoi spingere il cliente verso un upgrade. Metered (addebita) — l’utilizzo continua e ogni unità extra viene addebitata automaticamente dal saldo crediti del cliente alla tariffa di eccedenza. Metered è l’opzione “pay-as-you-go” ed è l’unica che muove denaro (crediti) da sola.
USD · Mensile · 14 giorni di prova · Public ✓Limite 1: meter Immagini generate, incluse 500, tipo Hard → dopo 500 immagini, la generazione si blocca fino al mese successivo o a un upgrade.
Limite 2: meter Secondi di rendering video, inclusi 1 000, eccedenza 0,02, tipo Metered → oltre i 1 000 secondi, ogni secondo extra costa in silenzio 0,02 crediti dal portafoglio del cliente.
Perché “+ Add limit” è disattivato?
Perché il progetto non ha ancora meter — un limite è sempre un tetto su un meter, quindi con zero meter non c’è nulla a cui agganciarlo. La finestra mostra il suggerimento “Create meters first to attach limits to this plan.” Vai su Meters → New meter, creane almeno uno, poi riapri questa finestra.
Perché il menu Meter mostra solo poche opzioni? E se il mio prodotto ha qualcosa di nuovo?
Il menu è semplicemente l’elenco dei tuoi meter nel progetto attualmente selezionato. Nei dati demo sono “Upscales processed”, “Video render seconds” e “Images generated” — ma quella lista è tua e può crescere. Non limita ciò che i clienti possono fare: i clienti non scelgono mai i meter; sei tu a definirli per qualunque cosa faccia il tuo prodotto. Nuova funzionalità domani? Crea un meter apposta e comparirà qui.
Perché non posso modificare prezzo o limiti di un piano esistente?
È voluto: gli abbonati esistenti hanno sottoscritto quelle condizioni, quindi prezzo, valuta, periodo di fatturazione e limiti sui meter vengono congelati alla creazione. Modificando un piano puoi cambiare solo nome, descrizione, giorni di prova, visibilità e stato attivo. Per cambiare i prezzi, crea un nuovo piano (es. “Pro 2026”) e indirizza lì i nuovi clienti.
Nuovo abbonamento collega cliente ⇄ piano
Un abbonamento collega un tuo cliente a un piano. Da quel momento il suo utilizzo viene valutato rispetto ai limiti sui meter di quel piano. In produzione di solito è il tuo backend a crearlo via SDK nell’istante in cui qualcuno sceglie una fascia al checkout — la finestra fa la stessa cosa a mano.
📍 Apri un progetto → Subscriptions → il pulsante nell’intestazione della tabella
- Customer ID *
Il tuo identificativo per il cliente finale — una stringa qualsiasi scelta da te: un ID utente del tuo database (
user-842), un’email, uno slug del tenant. MeterFlow non lo verifica contro nulla; ciò che invii è ciò a cui appartiene l’abbonamento. Usa lo stesso ID ovunque (abbonamenti, crediti, utilizzo), altrimenti i pezzi non si collegano. - Plan *
Su quale fascia di prezzo si trova — il menu elenca i piani di questo progetto. Se il piano ha giorni di prova, l’abbonamento parte in stato “trialing”; altrimenti “active”.
user-842 clicca “Passa a Pro” nella tua app → il tuo backend chiama subscriptions.create({ customer_external_id: 'user-842', plan_id: … }). Da questo momento ogni evento di utilizzo di user-842 viene confrontato con i limiti del piano Pro.E se un cliente non ha un abbonamento — i suoi eventi vanno persi?
No. Gli eventi vengono sempre salvati e compaiono sempre nei riepiloghi di utilizzo. Ma senza un abbonamento attivo non ci sono limiti di piano da applicare, quindi nulla viene bloccato e nulla viene addebitato — l’utilizzo viene semplicemente registrato. La logica di fatturazione si accende nel momento in cui esiste un abbonamento.
Accredita / Detrai crediti il portafoglio
I crediti sono un saldo prepagato per ciascun cliente (per progetto) — pensa a un portafoglio o a una carta ricaricabile. Sei tu a decidere quanto vale un credito nel tuo listino. L’eccedenza “metered” attinge da questo portafoglio automaticamente; le due finestre muovono i crediti a mano.
📍 Apri un progetto → Credits → cerca un cliente → “Grant” / “Deduct”
- Amount *
Quanti crediti aggiungere (Grant) o togliere (Deduct). Deve essere maggiore di zero — la direzione la decide il pulsante che ha aperto la finestra, non il segno meno.
- Description
Una nota facoltativa salvata sulla riga del registro — “Bonus di benvenuto”, “Rimborso per il disservizio”, “Cortesia del supporto”. Il te stesso del futuro ringrazierà.
user-842 riceve un accredito di 100 (“Bonus di benvenuto”). Poi renderizza 2 500 secondi di video su un piano con 1 000 inclusi ed eccedenza metered di 0,02 → 1 500 × 0,02 = 30 crediti detratti automaticamente. Saldo: 70.Registra evento di utilizzo concetto chiave
Un evento di utilizzo = “questo cliente ha appena fatto questa cosa, in questa quantità.” In produzione è la tua applicazione a inviarli via SDK automaticamente, migliaia di volte al giorno; la finestra esiste per inserirne uno a mano, per test e demo.
📍 Apri un progetto → Usage → cerca un cliente → “Record event”
- Event name *
Deve corrispondere esattamente al nome evento di un meter esistente e attivo in questo progetto (maiuscole/minuscole comprese). È grazie a questa corrispondenza che MeterFlow sa quale contatore alimenta l’evento. Nessun meter corrispondente → l’API rifiuta l’evento con un 404 e non viene salvato nulla. Controlla la pagina Meters per la grafia esatta.
- Customer ID *
Quale dei tuoi clienti l’ha fatto — la stessa stringa identificativa libera usata per abbonamenti e crediti. La coerenza è tutto:
user-842eUSER-842sono due clienti diversi. - Value
La quantità, di default
1. Il suo significato dipende dall’aggregazione del meter: per un meter Count il valore viene ignorato (ogni evento conta come una occorrenza); per Sum è la quantità da sommare (42 secondi, 1 300 token); per Max/Min è la misura da confrontare; per Unique count è la cosa di cui si contano i valori distinti.
video.rendered → “Video render seconds”. 2. L’evento viene salvato in modo permanente (grezzo — l’aggregazione avviene dopo, al momento della lettura). 3. In background, MeterFlow controlla se il cliente ha un abbonamento attivo e se quel piano ha un limite su questo meter. 4. Se il limite è Metered con una tariffa di eccedenza, l’addebito (valore × tariffa) viene detratto dal saldo crediti del cliente e viene scritta una riga nel registro. 5. Il riepilogo di utilizzo che vedi in questa pagina viene ricalcolato dagli eventi grezzi usando il tipo di aggregazione del meter.Ho registrato un evento e ho ricevuto un errore — perché?
Quasi sempre è il nome evento: non corrisponde esattamente a nessun meter attivo in questo progetto. L’errore lo dice testualmente — “No active meter found for event '…' in this project.” Copia il nome evento dalla pagina Meters invece di riscriverlo. Ricorda anche che i meter sono per progetto: un meter di un altro progetto non conta.
Se la mia app ritenta una richiesta, l’evento viene conteggiato due volte?
No, se usi l’SDK correttamente: ogni scrittura accetta una chiave di idempotenza — un’etichetta univoca per “questa specifica azione”. Se la stessa chiave arriva due volte (un nuovo tentativo dopo un intoppo di rete), MeterFlow la riconosce e restituisce il risultato originale invece di salvare un duplicato. La finestra manuale non la invia, quindi premere Record due volte a mano crea davvero due eventi.
Invita membro accesso del team
Aggiunge un collega alla tua organizzazione, così può vedere (o gestire) i suoi progetti in questa dashboard. La persona deve già avere un account MeterFlow — prima la registrazione, poi l’invito.
📍 Dashboard → tabella Organizations → azione di riga “Invite member”
- Email *
L’email con cui è registrato il suo account MeterFlow.
- Role
Admin — gestione completa: progetti, meter, piani, chiavi, membri. Member — operatività quotidiana. Viewer — sola lettura. Nota che manca di proposito l’opzione “owner”: la proprietà non si può assegnare tramite invito.
dana@acme.dev come Viewer, così il team finance può osservare utilizzo e saldi senza poter cambiare i prezzi.