Zum Hauptinhalt springen

API-Referenz - Ereignisaufnahme

Greifen Sie auf die vollständige API-Dokumentation zur Aufnahme von Nutzungsereignissen zu und testen Sie Ereignisaufnahmeanforderungen und -antworten interaktiv.

API-Referenz - Zählererstellung

Erkunden Sie die vollständige API-Dokumentation zur Erstellung von Zählern und testen Sie interaktiv die Anforderungen und Antworten zur Zählererstellung.

​
Einen Zähler erstellen

Zähler definieren, wie Ihre Nutzungsereignisse für Abrechnungszwecke aggregiert und gemessen werden. Bevor Sie einen Zähler erstellen, planen Sie Ihre Strategie zur Nutzungsverfolgung:
  • Bestimmen Sie, welche Nutzungsereignisse Sie verfolgen möchten
  • Legen Sie fest, wie Ereignisse aggregiert werden sollen (Zählung, Summe usw.)
  • Definieren Sie alle Filteranforderungen für spezifische Anwendungsfälle

​
Schritt-für-Schritt-Zählererstellung

Befolgen Sie diese umfassende Anleitung, um Ihren Nutzungszähler einzurichten:
1

Grundlegende Informationen konfigurieren

Richten Sie die grundlegenden Details für Ihren Zähler ein.
​
Zählername
string
required
Wählen Sie einen klaren, beschreibenden Namen, der angibt, was dieser Zähler verfolgt.Beispiele: “Tokens”, “API-Aufrufe”, “Speichernutzung”, “Rechenstunden”
​
Beschreibung
string
Geben Sie eine detaillierte Erklärung an, was dieser Zähler misst.Beispiel: “Zählt jede POST /v1/orders-Anfrage, die vom Kunden gestellt wird”
​
Ereignisname
string
required
Geben Sie die Ereigniskennung an, die diesen Zähler auslösen wird.Beispiele: “token”, “api.call”, “storage.usage”, “compute.session”
Der Ereignisname muss genau mit dem übereinstimmen, was Sie in Ihren Nutzungsereignissen senden. Ereignisnamen sind groß-/kleinschreibungssensitiv.
2

Aggregationsparameter konfigurieren

Definieren Sie, wie der Zähler die Nutzung aus Ihren Ereignissen berechnet.
​
Aggregationsart
string
required
Wählen Sie aus, wie Ereignisse aggregiert werden sollen:
Zählt einfach die Anzahl der empfangenen Ereignisse.Anwendungsfall: API-Aufrufe, Seitenaufrufe, Datei-UploadsBerechnung: Gesamtanzahl der Ereignisse
​
Über Eigenschaft
string
Der Eigenschaftsname aus den Ereignismetadaten, über die aggregiert werden soll.
Dieses Feld ist erforderlich, wenn Sie die Aggregationsarten Summe, Max oder Letzte verwenden.
​
Maßeinheit
string
required
Definieren Sie das Einheitsetikett für die Anzeige in Berichten und Abrechnungen.Beispiele: “Aufrufe”, “GB”, “Stunden”, “Tokens”
3

Ereignisfilterung konfigurieren (optional)

Richten Sie Kriterien ein, um zu steuern, welche Ereignisse im Zähler enthalten sind.
Die Ereignisfilterung ermöglicht es Ihnen, ausgeklügelte Regeln zu erstellen, die bestimmen, welche Ereignisse zu Ihren Nutzungsermittlungen beitragen. Dies ist nützlich, um Testereignisse auszuschließen, nach Benutzertarifen zu filtern oder sich auf bestimmte Aktionen zu konzentrieren.
Ereignisfilterung aktivierenAktivieren Sie Ereignisfilterung aktivieren, um die bedingte Ereignisverarbeitung zu aktivieren.Filterlogik auswählenWählen Sie aus, wie mehrere Bedingungen bewertet werden:
Alle Bedingungen müssen wahr sein, damit ein Ereignis gezählt wird. Verwenden Sie dies, wenn Sie möchten, dass Ereignisse mehrere strenge Kriterien gleichzeitig erfüllen.Beispiel: Zählen Sie API-Aufrufe, bei denen user_tier = "premium" UND endpoint = "/api/v2/users"
Filterbedingungen einrichten
1

Bedingung hinzufügen

Klicken Sie auf Bedingung hinzufügen, um eine neue Filterregel zu erstellen.
2

Eigenschaftsschlüssel konfigurieren

Geben Sie den Eigenschaftsnamen aus Ihren Ereignismetadaten an.
3

Vergleichsoperator auswählen

Wählen Sie aus den verfügbaren Operatoren:
  • equals - Exakte Übereinstimmung
  • not equals - Ausschlussfilter
  • greater than - Numerischer Vergleich
  • greater than or equals - Numerischer Vergleich (einschließlich)
  • less than - Numerischer Vergleich
  • less than or equals - Numerischer Vergleich (einschließlich)
  • contains - Zeichenfolge enthält Teilzeichenfolge
  • does not contain - Zeichenfolgen-Ausschlussfilter
4

Vergleichswert festlegen

Legen Sie den Zielwert für den Vergleich fest.
5

Gruppen hinzufügen

Verwenden Sie Gruppe hinzufügen, um zusätzliche Bedingungsgruppen für komplexe Logik zu erstellen.
Gefilterte Eigenschaften müssen in Ihren Ereignismetadaten enthalten sein, damit die Bedingungen ordnungsgemäß funktionieren. Ereignisse, denen erforderliche Eigenschaften fehlen, werden von der Zählung ausgeschlossen.
4

Zähler erstellen

Überprüfen Sie Ihre Zählerkonfiguration und klicken Sie auf Zähler erstellen.
Ihr Zähler ist jetzt bereit, Nutzungsereignisse zu empfangen und zu aggregieren.

​
Zähler in einem Produkt verknüpfen

Nachdem Sie Ihren Zähler erstellt haben, müssen Sie ihn mit einem Produkt verknüpfen, um die nutzungsbasierte Abrechnung zu aktivieren. Dieser Prozess verbindet die Nutzungsdaten Ihres Zählers mit den Preisregeln für die Kundenabrechnung. Die Verknüpfung von Zählern mit Produkten stellt die Verbindung zwischen Nutzungsverfolgung und Abrechnung her:
  • Produkte definieren Preisregeln und Abrechnungsverhalten
  • Zähler liefern Nutzungsdaten für Abrechnungsberechnungen
  • Mehrere Zähler können mit einem einzelnen Produkt für komplexe Abrechnungsszenarien verknüpft werden

​
Produktkonfigurationsprozess

Transformieren Sie Ihre Nutzungsdaten in abrechenbare Gebühren, indem Sie Ihre Produkteinstellungen ordnungsgemäß konfigurieren:
1

Nutzungsbasierten Abrechnungstyp auswählen

Navigieren Sie zu Ihrer Produkt-Erstellungs- oder Bearbeitungsseite und wählen Sie Nutzungsbasiert als Produkttyp aus.
2

Verknüpften Zähler auswählen

Klicken Sie auf Verknüpfter Zähler, um das Zählerauswahlfeld von der Seite zu öffnen.Dieses Feld ermöglicht es Ihnen, zu konfigurieren, welche Zähler die Nutzung für dieses Produkt verfolgen werden.
3

Ihren Zähler hinzufügen

Im Zählerauswahlfeld:
  1. Klicken Sie auf Zähler hinzufügen, um verfügbare Zähler anzuzeigen
  2. Wählen Sie den Zähler aus, den Sie aus der Dropdown-Liste erstellt haben
  3. Der ausgewählte Zähler wird in Ihrer Produktkonfiguration angezeigt
4

Preis pro Einheit konfigurieren

Legen Sie die Preise für jede Einheit der von Ihrem Zähler verfolgten Nutzung fest.
​
Preis pro Einheit
number
required
Definieren Sie, wie viel für jede von Ihrem Zähler gemessene Einheit berechnet werden soll.Beispiel: Festlegung von $0.50 pro Einheit bedeutet:
  • 1.000 Einheiten verbraucht = 1.000 × $0,50 = 500,00 berechnet
  • 500 Einheiten verbraucht = 500 × $0,50 = 250,00 berechnet
  • 100 Einheiten verbraucht = 100 × $0,50 = 50,00 berechnet
5

Kostenlose Schwelle festlegen (optional)

Konfigurieren Sie eine kostenlose Nutzungserlaubnis, bevor die Abrechnung beginnt.
​
Kostenlose Schwelle
number
Anzahl der Einheiten, die Kunden ohne Kosten verbrauchen können, bevor die Berechnung der kostenpflichtigen Nutzung beginnt.So funktioniert es:
  • Kostenlose Schwelle: 100 Einheiten
  • Preis pro Einheit: $0,50
  • Kundenverbrauch: 250 Einheiten
  • Berechnung: (250 - 100) × 0,50=∗∗0,50 = **75,00** berechnet
Kostenlose Schwellenwerte sind ideal für Freemium-Modelle, Testzeiträume oder um Kunden eine Basiszulage in ihrem Plan zu gewähren.
Die kostenlose Schwelle gilt für jeden Abrechnungszyklus und gewährt den Kunden monatlich oder gemäß Ihrem Abrechnungszeitplan neue Zulagen.
6

Konfiguration speichern

Überprüfen Sie Ihre Zähler- und Preisgestaltungskonfiguration und klicken Sie dann auf Änderungen speichern, um die Einrichtung abzuschließen.
Ihr Produkt ist jetzt für die nutzungsbasierte Abrechnung konfiguriert und berechnet automatisch die Gebühren der Kunden basierend auf ihrem gemessenen Verbrauch.
Was als Nächstes passiert:
  • Nutzungsereignisse, die an Ihren Zähler gesendet werden, werden verfolgt und aggregiert
  • Abrechnungsberechnungen wenden automatisch Ihre Preisregeln an
  • Kunden werden basierend auf dem tatsächlichen Verbrauch während jedes Abrechnungszyklus belastet
Denken Sie daran, dass Sie bis zu 10 Zähler pro Produkt hinzufügen können, um eine ausgeklügelte Nutzungsverfolgung über mehrere Dimensionen wie API-Aufrufe, Speicher, Rechenzeit und benutzerdefinierte Metriken zu ermöglichen.

​
Nutzungsereignisse senden

Sobald Ihr Zähler konfiguriert ist, können Sie beginnen, Nutzungsereignisse von Ihrer Anwendung zu senden, um den Kundenverbrauch zu verfolgen.

​
Ereignisstruktur

Jedes Nutzungsereignis muss diese erforderlichen Felder enthalten:
​
event_id
string
required
Eindeutige Kennung für dieses spezifische Ereignis. Muss einzigartig für alle Ereignisse sein.
​
customer_id
string
required
Die Dodo Payments-Kunden-ID, der diese Nutzung zugeordnet werden soll.
​
event_name
string
required
Der Ereignisname, der mit Ihrer Zählerkonfiguration übereinstimmt. Ereignisnamen lösen den entsprechenden Zähler aus.
​
timestamp
string
ISO 8601-Zeitstempel, wann das Ereignis aufgetreten ist. Standardmäßig wird die aktuelle Zeit verwendet, wenn kein Wert angegeben ist.
​
metadata
object
Zusätzliche Eigenschaften für Filterung und Aggregation. Fügen Sie alle Werte hinzu, die in der “Über Eigenschaft” oder den Filterbedingungen Ihres Zählers referenziert werden.

​
Beispiele für Nutzungsereignis-API

Senden Sie Nutzungsereignisse an Ihre konfigurierten Zähler über die Ereignis-API: 
const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "api_call_1234",
        customer_id: "cus_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

​
Analytik zur nutzungsbasierten Abrechnung

Überwachen und analysieren Sie Ihre Daten zur nutzungsbasierten Abrechnung mit einem umfassenden Analyse-Dashboard. Verfolgen Sie die Verbrauchsmuster der Kunden, die Leistung der Zähler und die Abrechnungstrends, um Ihre Preisstrategie zu optimieren und das Nutzungsverhalten zu verstehen.

​
Übersicht über Analytik

Der Tab Übersicht bietet einen umfassenden Überblick über Ihre Leistung bei der nutzungsbasierten Abrechnung:

​
Aktivitätsmetriken

Verfolgen Sie wichtige Nutzungsstatistiken über verschiedene Zeiträume:
​
Aktueller Monat
metric
Zeigt die Nutzungsaktivität für den aktuellen Abrechnungszeitraum an und hilft Ihnen, die monatlichen Verbrauchsmuster zu verstehen.
​
Alle Zeiten
metric
Zeigt kumulierte Nutzungsstatistiken seit Beginn der Verfolgung an und bietet Einblicke in das langfristige Wachstum.
Verwenden Sie den Zeitraumauswähler, um die Nutzung über verschiedene Monate zu vergleichen und saisonale Trends oder Wachstumsmuster zu identifizieren.

​
Zählerquantitätsdiagramm

Zählerquantitätsdiagramm, das Nutzungstrends über die Zeit mit lila Farbverlauf visualisiert
Das Zählerquantitätsdiagramm visualisiert Nutzungstrends über die Zeit mit folgenden Funktionen:
  • Zeitreihenvisualisierung: Verfolgen Sie Nutzungsmuster über Tage, Wochen oder Monate
  • Unterstützung mehrerer Zähler: Sehen Sie Daten von verschiedenen Zählern gleichzeitig
  • Trendanalysen: Identifizieren Sie Nutzungsspitzen, Muster und Wachstumstrends
Das Diagramm passt sich automatisch an Ihr Nutzungsvolumen und den ausgewählten Zeitraum an und bietet eine klare Sicht auf sowohl kleine Schwankungen als auch große Nutzungsänderungen.

​
Ereignisanalyse

Ereignistabelle, die Ereignisnamen, IDs und Paginierungssteuerungen für eine detaillierte Ereignisanalyse zeigt
Der Tab Ereignisse bietet eine detaillierte Sicht auf einzelne Nutzungsereignisse:

​
Anzeige von Ereignisinformationen

Die Ereignistabelle bietet eine klare Sicht auf einzelne Nutzungsereignisse mit folgenden Spalten:
  • Ereignisname: Die spezifische Aktion oder der Auslöser, der das Nutzungsereignis erzeugt hat
  • Ereignis-ID: Eindeutige Kennung für jede Ereignisinstanz
  • Kunden-ID: Der Kunde, der mit dem Ereignis verbunden ist
  • Zeitstempel: Wann das Ereignis aufgetreten ist
Diese Ansicht ermöglicht es Ihnen, einzelne Nutzungsereignisse über Ihre Kundenbasis hinweg zu verfolgen und zu überwachen, was Transparenz in die Abrechnungsberechnungen und Nutzungsmuster bringt.

​
Kundenanalyse

Der Tab Kunden bietet eine detaillierte Tabellenansicht der Nutzungsdaten der Kunden mit folgenden Informationen:

​
Verfügbare Datenfelder

​
Kunden-E-Mail
string
E-Mail-Adresse des Kunden zur Identifizierung.
​
Abonnement-ID
string
Eindeutige Kennung für das Abonnement des Kunden.
​
Kostenlose Schwelle
number
Anzahl der kostenlosen Einheiten, die im Plan des Kunden enthalten sind, bevor Gebühren anfallen.
​
Preis pro Einheit
currency
Die Kosten pro Einheit für die Nutzung über die kostenlose Schwelle hinaus.
​
Letztes Ereignis
timestamp
Zeitstempel des zuletzt verwendeten Ereignisses des Kunden.
​
Gesamtpreis
currency
Gesamtbetrag, der dem Kunden für die nutzungsbasierte Abrechnung in Rechnung gestellt wurde.
​
Verbrauchte Einheiten
number
Gesamtanzahl der Einheiten, die der Kunde verbraucht hat.
​
Abrechenbare Einheiten
number
Anzahl der Einheiten, die die kostenlose Schwelle überschreiten und berechnet werden.

​
Tabellenfunktionen

  • Spaltenfilterung: Verwenden Sie die Funktion “Spalten bearbeiten”, um bestimmte Datenfelder anzuzeigen/auszublenden
  • Echtzeit-Updates: Die Nutzungsdaten spiegeln die aktuellsten Verbrauchsmetriken wider

​
Aggregationsbeispiele

Hier sind praktische Beispiele, wie verschiedene Aggregationstypen funktionieren:

​
Aggregationstypen verstehen

Verschiedene Aggregationstypen dienen unterschiedlichen Abrechnungsszenarien. Wählen Sie den richtigen Typ basierend darauf, wie Sie die Nutzung messen und berechnen möchten.

​
Praktische Implementierungsbeispiele

Diese Beispiele zeigen reale Anwendungen jedes Aggregationstyps mit Beispielereignissen und erwarteten Ergebnissen.
Szenario: Verfolgen Sie die Gesamtzahl der API-AnfragenZählerkonfiguration:
  • Ereignisname: api.call
  • Aggregationsart: Zählen
  • Maßeinheit: calls
Beispielereignisse:
{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}
Ergebnis: 3 Anrufe dem Kunden in Rechnung gestellt
Szenario: Abrechnung basierend auf der Gesamtzahl der übertragenen BytesZählerkonfiguration:
  • Ereignisname: data.transfer
  • Aggregationsart: Summe
  • Über Eigenschaft: bytes
  • Maßeinheit: GB
Beispielereignisse:
{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123", 
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer", 
      "metadata": {"bytes": 536870912}
    }
  ]
}
Ergebnis: 1,5 GB Gesamtübertragung dem Kunden in Rechnung gestellt
Szenario: Abrechnung basierend auf der höchsten Anzahl gleichzeitiger BenutzerZählerkonfiguration:
  • Ereignisname: concurrent.users
  • Aggregationsart: Max
  • Über Eigenschaft: count
  • Maßeinheit: users
Beispielereignisse:
{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users", 
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}
Ergebnis: 23 Höchstzahl gleichzeitiger Benutzer dem Kunden in Rechnung gestellt

​
Beispiele für Ereignisfilterung

Zählen Sie nur API-Aufrufe zu bestimmten Endpunkten:Filterkonfiguration:
  • Eigenschaft: endpoint
  • Vergleichsoperator: equals
  • Wert: /v1/orders
Beispielereignis:
{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}
Ergebnis: Ereignisse, die den Filterkriterien entsprechen, würden gezählt. Ereignisse mit anderen Endpunkten würden ignoriert.

​
Fehlersuche

Lösen Sie häufige Probleme bei der Implementierung der nutzungsbasierten Abrechnung und stellen Sie eine genaue Verfolgung und Abrechnung sicher.

​
Häufige Probleme

Die meisten Probleme bei der nutzungsbasierten Abrechnung fallen in diese Kategorien:
  • Probleme mit der Ereignislieferung und -verarbeitung
  • Probleme mit der Zählerkonfiguration
  • Fehler bei Datentypen und Formatierungen
  • Kunden-ID- und Authentifizierungsprobleme

​
Debugging-Schritte

Bei der Fehlersuche zur nutzungsbasierten Abrechnung:
  1. Überprüfen Sie die Ereignislieferung im Tab Ereignisanalyse
  2. Stellen Sie sicher, dass die Zählerkonfiguration mit Ihrer Ereignisstruktur übereinstimmt
  3. Validieren Sie die Kunden-IDs und die API-Authentifizierung
  4. Überprüfen Sie die Filterbedingungen und Aggregationseinstellungen

​
Lösungen und Fehlerbehebungen

Häufige Ursachen:
  • Der Ereignisname stimmt nicht genau mit der Zählerkonfiguration überein
  • Die Filterbedingungen schließen Ihre Ereignisse aus
  • Die Kunden-ID existiert nicht in Ihrem Dodo Payments-Konto
  • Der Zeitstempel des Ereignisses liegt außerhalb des aktuellen Abrechnungszeitraums
Lösungen:
  • Überprüfen Sie die Schreibweise und Groß-/Kleinschreibung des Ereignisnamens
  • Überprüfen und testen Sie Ihre Filterbedingungen
  • Bestätigen Sie, dass die Kunden-ID gültig und aktiv ist
  • Überprüfen Sie, ob die Zeitstempel der Ereignisse aktuell und korrekt formatiert sind
Häufige Ursachen:
  • Der Name der Über-Eigenschaft stimmt nicht mit den Schlüsseln der Ereignismetadaten überein
  • Die Metadatenwerte haben den falschen Datentyp (String vs. Zahl)
  • Fehlende erforderliche Metadaten-Eigenschaften
Lösungen:
  • Stellen Sie sicher, dass die Metadatenschlüssel genau mit Ihrer Über-Eigenschaftseinstellung übereinstimmen
  • Konvertieren Sie String-Zahlen in tatsächliche Zahlen in Ihren Ereignissen
  • Fügen Sie alle erforderlichen Eigenschaften in jedes Ereignis ein
Häufige Ursachen:
  • Die Filtereigenschaftsnamen stimmen nicht mit den Ereignismetadaten überein
  • Falscher Vergleichsoperator für den Datentyp (String vs. Zahl)
  • Groß-/Kleinschreibung bei String-Vergleichen
Lösungen:
  • Überprüfen Sie, ob die Eigenschaftsnamen genau übereinstimmen
  • Verwenden Sie geeignete Vergleichsoperatoren für Ihre Datentypen
  • Berücksichtigen Sie die Groß-/Kleinschreibung bei der Filterung von Strings