Kampagnen- & Angebotsverwaltung

Uebersicht

Das Kampagnen- und Angebotsverwaltungssystem in TanStack Ship ermoeglicht anspruchsvolle Marketingaktionen, die Conversions steigern und Kunden binden. Das System bietet ein komplettes Werkzeugset fuer die Erstellung zeitgebundener Kampagnen, die Definition mehrerer Angebotstypen, die Generierung von Gutscheincodes und die Verfolgung der Einloesungsleistung — alles verwaltet ueber das Admin-Dashboard.

Als Teil der TanStack Ship Plattform integriert sich das Kampagnensystem in das UTM-Tracking-Modul fuer automatische Angebotszuordnung basierend auf der Verkehrsquelle, die Preis-Engine fuer dynamische Rabattanwendung waehrend des Checkouts und das Abrechnungssystem fuer Stripe-integrierte Gutscheinverarbeitung.

Kampagnen-Lebenszyklus

Jede Kampagne folgt einem strukturierten Lebenszyklus von der Erstellung bis zum Ablauf:

Design-Philosophie

Das Kampagnen- und Angebotssystem basiert auf drei Designprinzipien:

• Komponierbare Rabatt-Engine — Rabatte aus verschiedenen Quellen (prozentual, Festbetrag, Guthabenvergabe) werden in einer definierten Prioritaetskette ausgewertet. Jede Quelle arbeitet unabhaengig und ermoeglicht komplexe Werbestrategien ohne Aenderung der Kernpreislogik. Im Gegensatz zu Voucherify — das externe API-Aufrufe und Webhook-Integrationen fuer die Rabattvalidierung erfordert — wertet unsere integrierte Angebots-Engine Preisregeln serverseitig innerhalb Ihrer eigenen Datenbank aus, wodurch Latenz und Drittanbieterabhaengigkeiten aus dem Checkout-Prozess eliminiert werden.
• UTM-First-Auto-Matching — Angebote werden basierend auf UTM-Parametern automatisch zugeordnet, bevor der Checkout beginnt. Dies schafft ein reibungsloses Rabatterlebnis — Benutzer muessen nie einen Gutscheincode suchen oder eingeben.
• Zeitlich begrenzte Kampagnen — Jede Kampagne hat ein explizites Start- und Enddatum. Das System aktiviert und deaktiviert Angebote automatisch basierend auf diesen Zeitplaenen.

Kernfunktionen

Kampagnenverwaltung

Kampagnen sind uebergeordnete Marketinginitiativen, die Angebote, UTM-Parameter und Zielregeln buendeln. Jede Kampagne umfasst:

• Name & Beschreibung — Interner Name fuer Admin-Referenz und kundenorientierter Werbetext
• Datumsbereich — Start- und Enddatum fuer automatische Aktivierung und Ablauf
• UTM-Parameter — Quelle, Medium und Kampagnenname fuer Attributionsverfolgung
• Aktivstatus — Kampagnen ein- und ausschalten, ohne Konfiguration zu loeschen
• Feiertagsverknuepfung — Kampagnen mit Feiertagsplaenen fuer saisonale Aktionen verknuepfen

Kampagnen koennen vor der Aktivierung in der Vorschau angezeigt werden, um die konfigurierten Angebote und UTM-Links zu ueberpruefen.

Angebotstypen

Drei Angebotstypen werden unterstuetzt, jeweils mit unterschiedlichen Anwendungsfaellen:

Angebote koennen gestapelt oder einzeln angewendet werden, gesteuert durch die Prioritaetslogik der Preis-Engine.

Gutscheincode-System

Jedes Angebot kann einen oder mehrere Gutscheincodes mit granularer Konfiguration haben:

• Benutzerdefinierte Codes — Markenbezogene Codes definieren (z. B. LAUNCH2024, SOMMER20)
• Automatisch generierte Codes — Systemgenerierte eindeutige Codes fuer individuelle Verteilung
• Oeffentlich vs. Privat — Oeffentliche Codes werden auf der Preisseite aufgelistet; private Codes erfordern direkte Weitergabe
• Tarifspezifische Eingrenzung — Angebote auf bestimmte Abonnementplaene beschraenken (monatlich, jaehrlich oder beide)
• Nutzungslimits — Maximale Einloesungsanzahl pro Code festlegen
• Ablauf — Individueller Code-Ablauf unabhaengig vom uebergeordneten Kampagnenzeitraum

Clientseitiges Gutschein-Validierungsbeispiel:

import { useMutation } from '@tanstack/react-query'
import { useState } from 'react'

export function CouponInput() {
  const [code, setCode] = useState('')

  const validate = useMutation({
    mutationFn: async (couponCode: string) => {
      const res = await fetch('/api/offers/validate', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ code: couponCode }),
      })
      if (!res.ok) throw new Error('Gutschein ungueltig oder abgelaufen')
      return res.json() as Promise<{
        valid: boolean
        discount: { type: string; value: number }
        description: string
      }>
    },
  })

  return (
    <div className="rounded-lg border p-4">
      <label className="mb-2 block text-sm font-medium">Gutscheincode</label>
      <div className="flex gap-2">
        <input
          className="flex-1 rounded-md border px-3 py-2"
          value={code}
          onChange={(e) => setCode(e.target.value)}
          placeholder="Code eingeben"
        />
        <button
          className="rounded-md bg-primary px-4 py-2 text-white"
          onClick={() => validate.mutate(code)}
        >
          Anwenden
        </button>
      </div>
      {validate.isPending && <p className="mt-2 text-sm">Wird validiert...</p>}
      {validate.isError && (
        <p className="mt-2 text-sm text-red-600">{validate.error.message}</p>
      )}
      {validate.isSuccess && (
        <p className="mt-2 text-sm text-green-600">
          {validate.data.description} — {validate.data.discount.value}{validate.data.discount.type === 'percentage' ? '%' : '€'} Rabatt
        </p>
      )}
    </div>
  )
}

UTM-basierte automatische Zuordnung

Wenn Benutzer ueber eine UTM-getaggte URL kommen, ordnet das System automatisch passende Angebote zu. Dies ermoeglicht anspruchsvolle Marketingstrategien:

• Werbepreisgestaltung — Spezielle Preise fuer Benutzer von bestimmten Werbeplattformen (Google Ads, Facebook, LinkedIn)
• Partner-Empfehlungen — Benutzerdefinierte UTM-Codes pro Partner fuer verfolgbare Empfehlungsangebote
• A/B-Tests — Verschiedene Angebote fuer verschiedene Verkehrsquellen zur Messung der Konversionsleistung
• Content-Marketing — Exklusive Angebote fuer Blogleser oder Newsletter-Abonnenten ueber eindeutige UTM-Links

Die Zuordnungslogik wertet UTM-Quelle, Medium und Kampagnenfelder gegen konfigurierte Kampagnenregeln aus.

Feiertagsspezifische Kampagnen

Kampagnen koennen mit dem Feiertagsverwaltungssystem fuer automatische saisonale Aktivierung verknuepft werden:

• Kampagnen erstellen, die an konfigurierten Feiertagen automatisch aktiviert werden
• Verschiedene Angebote fuer verschiedene Feiertage festlegen (z. B. Weihnachten vs. Black Friday)
• Feiertagskampagnen pro Markt lokalisieren (Deutschland, China, USA)

Best Practices

Kampagnen-Benennungskonventionen

Verwenden Sie konsistente Namensmuster fuer Kampagnen, z. B. {TYP}_{ZIEL}_{JAHR} — WELCOME_NEWUSER_2024, SALE_SUMMER_2024. Dies erleichtert das Filtern und die Berichterstattung im Admin-Dashboard erheblich.

Zeitlich begrenzte Angebote

Legen Sie immer explizite Start- und Enddaten fuer Kampagnen fest. Zeitlich begrenzte Angebote schaffen Dringlichkeit und verbessern die Konversionsraten. Das System deaktiviert abgelaufene Kampagnen automatisch.

Testen der UTM-Zuordnung

Testen Sie vor dem Start einer Kampagne Ihre UTM-Links, indem Sie einen Besuch mit den konfigurierten UTM-Parametern simulieren. Ueberpruefen Sie, ob das richtige Angebot waehrend des Checkouts angewendet wird.

Angebotsstapelstrategie

Entscheiden Sie, ob Angebote gestapelt werden koennen (mehrere Rabatte gleichzeitig) oder sich gegenseitig ausschliessen. Die Preis-Engine unterstuetzt beide Modi, aber das Stapeln sollte begrenzt werden, um Margenverlust zu vermeiden.

Haeufig gestellte Fragen

Wie erstelle ich eine neue Kampagne? Navigieren Sie zu /dashboard/admin/campaigns und klicken Sie auf "Neue Kampagne". Fuellen Sie Name, Beschreibung, Datumsbereich und optionale UTM-Parameter aus. Erstellen Sie dann Angebote und verknuepfen Sie sie mit der Kampagne.

Kann ich mehrere Angebote in einer Kampagne haben? Ja. Eine Kampagne kann mehrere Angebote verschiedener Typen enthalten. Beispielsweise kann eine Sommeraktion sowohl einen Prozentrabatt als auch eine Guthabenvergabe umfassen.

Wie werden Angebote waehrend des Checkouts angewendet? Die Preis-Engine wertet alle aktiven Angebote aus, die auf den Benutzer und den Plan zutreffen. Wenn eine UTM-gematchte Kampagne erkannt wird, hat deren Angebot Vorrang. Andernfalls wird das wertvollste allgemeine Angebot angewendet.

Kann ich ein Angebot nur auf neue Benutzer beschraenken? Ja. Angebote koennen durch Konfiguration der Berechtigungsregeln auf neue Benutzer eingeschraenkt werden. Das System ueberprueft das Registrierungsdatum und die Abonnementhistorie des Benutzers bei der Bewertung der Angebotsgueltigkeit.

Wie verfolge ich die Kampagnenleistung? Das Admin-Dashboard bietet eine Kampagnenanalyse-Ansicht mit Kennzahlen wie Angebotseinloesungen, Konversionsraten, Umsatzauswirkungen und UTM-Attributionsdaten.

Was passiert, wenn eine Kampagne ablaeuft? Abgelaufene Kampagnen werden automatisch deaktiviert. Aktive Angebote innerhalb der Kampagne werden waehrend des Checkouts nicht mehr angewendet. Historische Einloesungsdaten bleiben erhalten.

Kann ich denselben Gutscheincode in mehreren Kampagnen verwenden? Nein, jeder Gutscheincode gehoert zu einem einzelnen Angebot innerhalb einer einzelnen Kampagne. Dies verhindert Mehrdeutigkeiten bei der Attributionsverfolgung.

Konfiguration

Kampagnen und Angebote werden vollstaendig ueber das Admin-Dashboard verwaltet:

• Kampagnenverwaltung: /dashboard/admin/campaigns
• Angebotsverwaltung: /dashboard/admin/offers
• Gutscheincodes: Innerhalb jedes Angebots erstellt

Es werden keine spezifischen Umgebungsvariablen fuer Kampagnen benoetigt. Das System verwendet die vorhandene Abrechnungs- und UTM-Konfiguration.

Integrationspunkte

Das Kampagnensystem integriert sich mit den folgenden TanStack Ship Plattformmodulen:

• Preis-Engine — Angebote passen Preise waehrend des Checkouts dynamisch an ueber src/lib/pricing-engine.ts
• UTM-Tracking — Kampagnen verknuepfen UTM-Parameter fuer automatische Angebotszuordnung und Attribution
• Abrechnung — Rabatte werden beim Stripe Checkout ueber Gutscheincode-Integration angewendet
• Analyse-Dashboard — Verfolgen Sie Angebotseinloesungsraten, Kampagnen-ROI und Konversionskennzahlen
• Kurzlinks — Erstellen Sie verfolgbare Kurzlinks fuer die Kampagnenverteilung in sozialen Medien und E-Mails
• Feiertagssystem — Verknuepfen Sie Kampagnen mit Feiertagsplaenen fuer automatisierte saisonale Aktionen
• Guthabensystem — Guthabenangebote gewaehren Punkte auf Benutzerguthaben bei qualifizierenden Kaeufen