# Nur festgeschriebene Bestellungen zählen

> MIRA FIVE in Convex einrichten: @mirafive/sdk-convex meldet Events und bezahlte Bestellungen aus Mutationen, erst nach dem Commit; eine Wiederholung zählt nur einmal.

URL: https://mirafive.io/de/fuer/convex  
Updated: 2026-09-28

Eine Mutation plant die Zustellung, statt zu senden. Eine zurückgerollte Bestellung erreicht Ihre Zahlen nie.

Paket `@mirafive/sdk-convex`

## In 5 Schritten eingerichtet

1. ### Pakete installieren  
Zugestellt wird über `@mirafive/sdk-server`. Das Paket setzt `convex` 1.25 voraus und läuft in der Standard-Laufzeit von Convex, ohne `"use node"`.  
```  
npm install @mirafive/sdk-convex @mirafive/sdk-server  
```
2. ### Geheimen Schlüssel im Deployment setzen  
Nehmen Sie den geheimen Schlüssel einer Server-Quelle aus **Daten → Quellen**. Er gehört in die Umgebung des Deployments, nie in Code. Fehlt er, läuft das Deployment weiter; Events werden mit einer Warnung verworfen.  
```  
npx convex env set MIRAFIVE_SECRET_KEY mf_…  
```
3. ### Client anlegen  
Exportieren Sie Client und Zustell-Action aus einem Modul. Behalten Sie die Annotation `: MiraConvex`, sonst meldet TypeScript TS7022.  
```  
import { MiraConvex } from '@mirafive/sdk-convex'  
import { internal } from './_generated/api'  
export const mira: MiraConvex = new MiraConvex({  
  key: process.env.MIRAFIVE_SECRET_KEY,  
  deliver: internal.mirafive.deliver,  
})  
export const deliver = mira.deliverAction()  
```
4. ### Bestellung in der Mutation melden  
`track()` plant `deliver` ein, und Convex führt es nur aus, wenn die Mutation festgeschrieben wird. Der Idempotenzschlüssel lässt eine doppelt laufende Mutation einmal zählen. Jeder Aufruf braucht `await`.  
```  
import { v } from 'convex/values'  
import { mutation } from './_generated/server'  
import { mira } from './mirafive'  
export const pay = mutation({  
  args: { orderId: v.id('orders') },  
  handler: async (ctx, { orderId }) => {  
    const order = await ctx.db.get(orderId)  
    if (!order) {  
      throw new Error('order not found')  
    }  
    await ctx.db.patch(orderId, { paidAt: Date.now() })  
    await mira.track(ctx, 'order_paid', {  
      userId: order.customerId,  
      properties: { revenue: 328, currency: 'EUR' },  
      idempotencyKey: `order-${orderId}`,  
    })  
  },  
})  
```
5. ### Zustellung prüfen  
Führen Sie die Action einmal mit einem Test-Event aus, das weder gespeichert noch berechnet wird. Sie gibt `null` aus, wenn MIRA FIVE den Batch angenommen hat. Danach finden Sie ein echtes Event unter **Daten → Live**.  
```  
npx convex run mirafive:deliver '{"events":"[{\"name\":\"$install_check\"}]","idempotencyKey":"install-check"}'  
```

MIRA FIVE ist Analyse rund um die Person. `@mirafive/sdk-convex` meldet Events aus Mutationen und Actions und stellt sie über `@mirafive/sdk-server` zu. Ein Kauf zählt dort, wo Ihre App die Bestellung als bezahlt speichert, und nur wenn dieses Speichern gelingt.

## Wie kommt eine Bestellung zu ihrem Kanal?

Über die Person. Im Browser nutzt Ihre App das [Browser-SDK](https://mirafive.io/de/fuer/javascript) oder das Paket Ihres Frameworks, etwa [React](https://mirafive.io/de/fuer/react). Mit Einwilligung führt der Browser eine Kennung. Übergeben Sie sie an eine Mutation, und `identify` verknüpft die früheren Events mit Ihrer Nutzer-ID:

```ts
await mira.identify(ctx, userId, { plan: 'pro' }, { anonymousId })
```

Nehmen Sie Ihre interne ID, nie eine E-Mail-Adresse. Die Bestellung trägt dieselbe `userId` und landet bei dieser Person, neben dem Kanal ihres ersten Besuchs. Mit einem Kaufziel auf `order_paid` zeigt Herkunft Käufer und Umsatz je Kanal.

## Wie zählen Wiederholungen?

Jede Zustellung trägt einen Idempotenzschlüssel, der beim Einplanen feststeht: Ihren oder eine neue UUID. Läuft die Action erneut, sendet sie den byte-gleichen Batch, und MIRA FIVE speichert ihn einmal. Mehrere Events einer Mutation gehen mit `trackMany()` in einer Zustellung raus:

```ts
await mira.trackMany(ctx, [
  { name: 'order_paid', userId, properties: { revenue: 328, currency: 'EUR' } },
  { name: 'invoice_created', userId, properties: { invoiceId } },
])
```

Server-Events gehen standardmäßig im vollen Modus raus; die Rechtsgrundlage für die IDs liegt bei Ihrer App.

Im Tab **Einbauen** der Quelle steht **Von Ihrem Coding-Agent einbauen lassen**: ein Prompt für Claude Code, Cursor oder Codex mit allen Schritten und der Prüfung, nie mit dem geheimen Schlüssel. Outbox und Workpool beschreibt die [Dokumentation](https://docs.mirafive.io/sdks/convex), die Aufgabenteilung die [Einrichtungsseite](https://mirafive.io/de/einrichtung).

## Andere Einrichtungen

Dieselben Zahlen, egal wie Ihre Website gebaut ist.

- [Next.js](https://mirafive.io/de/fuer/nextjs)
- [React](https://mirafive.io/de/fuer/react)
- [Astro](https://mirafive.io/de/fuer/astro)
- [Laravel](https://mirafive.io/de/fuer/laravel)
- [Nuxt](https://mirafive.io/de/fuer/nuxt)
- [Symfony](https://mirafive.io/de/fuer/symfony)
- [PHP](https://mirafive.io/de/fuer/php)
- [Vue](https://mirafive.io/de/fuer/vue)
- [TanStack Start](https://mirafive.io/de/fuer/tanstack-start)
- [Node.js](https://mirafive.io/de/fuer/nodejs)
- [JavaScript](https://mirafive.io/de/fuer/javascript)
- [jede Website](https://mirafive.io/de/fuer/website)

[Zur Dokumentation](https://docs.mirafive.io)

## Fragen und Antworten

### Kann eine zurückgerollte Mutation eine Bestellung zählen?

Nein. Eine Mutation erreicht kein Netz; `track()` plant die Zustellung, und Convex führt geplante Funktionen nur nach dem Commit aus.

### Wann lohnt sich die Outbox?

Ab etwa einem Event pro Sekunde. Mit `outbox` schreiben Mutationen in die Tabelle `miraOutbox`, ein Cron sendet Batches von bis zu 1.000 Events. Das spart Action-Zeit in Convex; MIRA FIVE zählt weiter jedes Event.

### Wiederholt der Scheduler eine fehlgeschlagene Zustellung?

Nein. Dafür übergeben Sie Zustellungen per Option `enqueue` an einen Convex-Workpool. Der Idempotenzschlüssel steht beim Einplanen fest, eine Wiederholung wird einmal gespeichert.

## Sehen Sie, welcher Kanal Käufer bringt

Kostenlos bis 25.000 Events im Monat. Ohne Kreditkarte.

[Kostenlos starten](https://app.mirafive.io/register)[Zu den Preisen](https://mirafive.io/de/preise)