Skip to content
← Alle Beiträge
· Delta1 Labs EntitlementsKeyright

Eine Lizenz direkt von Test auf Bezahlt hochstufen

Wenn ein Kunde einen Test in eine Bezahlversion umwandelt oder von Standard auf Pro wechselt, sollte sich die bereits aktivierte Schlüsselzeichenkette nicht ändern. So aktualisieren Sie eine Lizenz serverseitig mit Keyright — Test-Flag entfernen, Ablauf verlängern, Entitlements hinzufügen — damit die bereitgestellte SDK-App die neue Zusage beim nächsten ValidateAsync übernimmt, ohne Reaktivierungsaufwand, sowie wie Sie das Revalidierungsintervall einstellen, den Upgrade-Aufruf idempotent halten und jede Entitlement-Änderung protokollieren.

Ein Kunde beendet seinen Test und zahlt. Oder ein Standard-Kunde wechselt auf Pro. Oder er kauft mitten in der Laufzeit ein Add-on. In jedem dieser Momente ist der Instinkt, einen frischen Lizenzschlüssel zu erzeugen und per E-Mail zu versenden — und in jedem von ihnen ist das der falsche Zug. Der Schlüssel, den der Kunde bereits aktiviert hat, ist eine signierte Zusage von Entitlements; einen Test in Bezahlt oder Standard in Pro umzuwandeln ist eine Änderung an dem, was diese Zusage besagt, kein Grund, sie zu ersetzen. Aktualisieren Sie die Lizenz an Ort und Stelle, und die installierte Schlüsselzeichenkette des Kunden ändert sich nie: kein neuer Schlüssel zum Ausliefern, kein Kopieren und Einfügen, keine Reaktivierung, kein „Ich habe meinen Schlüssel nie erhalten”-Ticket.

Dies ist eine Anleitung, genau das mit einer selbst gehosteten Keyright-Bereitstellung zu tun. Wir ändern eine Lizenz serverseitig, beobachten, wie die bereitgestellte SDK-App die neuen Entitlements bei ihrer nächsten Validierung übernimmt, und behandeln dann die Teile, die es sofort wirken lassen und korrekt halten: Cache-Verbreitung, Idempotenz, Herabstufungen und die Prüfspur.

Die bereitgestellte App ändert sich nie

Beginnen wir auf der Seite der App, denn das ist der Teil, der sich nicht bewegen darf. Eine .NET-App bettet das Keyright-SDK ein, initialisiert es einmal und schützt Funktionen über Entitlements:

KeyrightClient.Initialize(new KeyrightOptions
{
    Product         = "acme-studio",
    PublicKeyBase64 = "MCowBQYDK2VwAyEA...",   // der Prüfschlüssel Ihrer Bereitstellung
    ServiceUrl      = "https://license.acme.example",
});

var result = await client.ValidateAsync();
if (!result.IsValid)
{
    // Geschlossen scheitern: keine gültige Lizenz → keine kostenpflichtigen Funktionen.
    EnterRestrictedMode(result);
    return;
}

// Schützen Sie eine kostenpflichtige Funktion über ein Entitlement, nicht über einen Stufennamen.
exportButton.Enabled = client.HasEntitlement("pro.export");

Beachten Sie, was die App nicht tut: Sie prüft keine Stufenzeichenkette, vergleicht keine Daten, behandelt „trial” nicht als Sonderfall. Sie stellt eine Frage pro Funktion — HasEntitlement("pro.export") — und scheitert geschlossen, wenn die Lizenz ungültig ist. Diese eine Disziplin macht ein Upgrade an Ort und Stelle möglich, denn das Einzige, was ein Upgrade tun muss, ist zu ändern, welche Entitlements die Lizenz trägt. Der Code der App ist bereits so geschrieben, dass er reagiert.

Ändern Sie die Lizenz, nicht den Schlüssel

Serverseitig ist ein Upgrade ein Patch am bestehenden Lizenzdatensatz. Keyright stellt dies über die Admin-API bereit (und dieselbe Aktion ist als Schaltfläche im Dashboard verfügbar). Die Lizenz wird über ihre id adressiert — nicht über die Schlüsselzeichenkette, die privat beim Kunden bleibt:

PATCH /v1/admin/licenses/lic_7f3a9c2e HTTP/1.1
Host: license.acme.example
Authorization: Bearer {admin_token}
Idempotency-Key: order-558120
Content-Type: application/json

{
  "tier": "pro",
  "entitlements": ["core.use", "pro.export", "pro.batch"],
  "expiresAt": "2027-11-14T00:00:00Z",
  "trial": false
}

Dieser eine Aufruf erledigt die gesamte Test-zu-Bezahlt-Umwandlung: Er entfernt das trial-Flag, schiebt den Ablauf um ein Jahr hinaus und tauscht das Entitlement-Set des Tests gegen das bezahlte aus. Die id der Lizenz ist unverändert, also bleibt die Schlüsselzeichenkette, die der Kunde vor einer Woche in die App eingegeben hat, gültig und bleibt seine. Nichts an seiner Maschine, seiner Aktivierung oder seinen Daten bewegt sich. Beim nächsten Validieren seiner App signiert der ausstellende Dienst eine frische Zusage mit pro.export und pro.batch, und HasEntitlement("pro.export") gibt true zurück.

Ein Stufen-Upgrade (Standard → Pro) hat die identische Form — Sie senden die Pro-Stufe und ihr größeres Entitlement-Set. Ein Add-on mitten in der Laufzeit ist noch kleiner: Lassen Sie tier und expiresAt unverändert und senden Sie die Entitlement-Liste mit der zusätzlichen Fähigkeit angehängt. Da die App über einzelne Entitlement-Zeichenketten schützt, schaltet das Hinzufügen von pro.batch zur Liste genau diese Funktion frei und berührt sonst nichts.

Wie die App es übernimmt

Das Upgrade ist in dem Moment auf dem Server aktiv, in dem das PATCH übernommen wird. Wann die App es sieht, hängt vom Validierungstakt ab.

Zeitstrahl der App ValidateAsync Test-Zusage zwischengespeichert Cache-Intervall — App liefert den Test Anbieter PATCHt → Pro nächstes ValidateAsync Pro-Zusage · pro.export wird freigeschaltet Verbreitungslücke = Zeit bis zur nächsten Revalidierung Kürzeres Intervall schaltet fast sofort frei kleine Lücke

Zwischen Validierungen liefert das SDK eine zwischengespeicherte Zusage, damit die App offline weiterarbeitet und nicht bei jeder Funktionsprüfung das Netz berührt. Hat der Kunde während dieses Cache-Fensters gezahlt, zeigt die App weiter den Test an, bis der Cache abläuft und sie revalidiert. Das ist kein Fehler — es ist die Offline-Toleranz, die das SDK nutzbar macht — aber es ist das, was ein Upgrade kaputt aussehen lässt.

Drei Hebel schließen die Lücke:

  • Verkürzen Sie das Revalidierungsintervall für Produkte, bei denen sofortige Upgrades zählen. Ein kürzeres RevalidationInterval bedeutet, dass das nächste Online-ValidateAsync früher stattfindet, also kommen die neuen Entitlements früher an. Der Kompromiss ist mehr Server-Kontakte; stellen Sie es auf das gewünschte Erlebnis ein.
  • Erzwingen Sie eine Validierung bei einer Benutzeraktion. Geben Sie der App einen Menüpunkt „Lizenz aktualisieren” oder lösen Sie ValidateAsync aus, wenn der Benutzer nach der Rückkehr vom Bezahlvorgang den Upgrade-Erfolgsbildschirm öffnet. Das verwandelt die Verbreitungslücke in einen einzigen Hin- und Rückweg.
  • Revalidieren Sie beim Fortsetzen. ValidateAsync beim App-Start oder beim Fensterfokus aufzurufen bedeutet, dass ein Kunde, der gezahlt und die App wieder geöffnet hat, das Upgrade sofort erhält — der häufigste Konversionspfad.
// Aufgerufen aus einer „Lizenz aktualisieren"-Aktion, nachdem der Kunde vom Bezahlvorgang zurückkehrt.
async Task RefreshAfterPurchaseAsync()
{
    var result = await client.ValidateAsync(force: true);   // Cache überspringen
    if (result.IsValid && client.HasEntitlement("pro.export"))
        UnlockProFeatures(result.LicenseInfo);              // live, derselbe Schlüssel
}

result.LicenseInfo trägt die aktualisierte Stufe, das Entitlement-Set und den Ablauf, sodass die Oberfläche den Plan neu beschriften und das Banner „Test endet in N Tagen” im selben Durchgang entfernen kann.

Machen Sie das Upgrade idempotent

Upgrades werden meist von einem Abrechnungs-Webhook angestoßen, und Webhooks werden mindestens einmal zugestellt — dasselbe order.paid-Ereignis kann zweimal eintreffen, und ein abgelaufener Aufruf wird erneut versucht. Wäre Ihre Upgrade-Logik eine relative Mutation („füge 1 Jahr hinzu”, „hänge ein Entitlement an”), würde ein Duplikat den Ablauf verdoppeln oder eine zweite Kopie stapeln. Modellieren Sie das Upgrade daher als eine Erklärung eines Zielzustands, nicht als Delta.

Das obige PATCH tut dies: Es setzt die Stufe, die vollständige Entitlement-Liste und das absolute expiresAt. Senden Sie es zweimal, und die Lizenz konvergiert zum selben Datensatz — Stufe pro, diese Entitlements, dieser Ablauf. Der Header Idempotency-Key: order-558120 macht es explizit: Keyright zeichnet das Ergebnis unter diesem Schlüssel auf, sodass ein erneuter Versuch das gespeicherte Ergebnis wiedergibt, statt die Änderung erneut anzuwenden. Binden Sie ihn an die Bestell- oder Zahlungsreferenz — etwas, das über erneute Versuche desselben Kaufs stabil und über wirklich verschiedene Käufe hinweg unterschiedlich ist.

// Abrechnungs-Webhook-Handler — sicher bei jeder Zustellung des Ereignisses auszuführen.
app.MapPost("/webhooks/billing", async (BillingEvent e) =>
{
    if (e.Type != "order.paid") return Results.Ok();

    await adminApi.PatchLicenseAsync(e.LicenseId, new LicensePatch
    {
        Tier         = e.PlanTier,              // "pro"
        Entitlements = EntitlementsForPlan(e.PlanTier),
        ExpiresAt    = e.CurrentPeriodEnd,      // absolut, nicht relativ
        Trial        = false,
    }, idempotencyKey: e.OrderId);

    return Results.Ok();
});

Herabstufungen und Ablauf

Derselbe Pfad läuft rückwärts, und da die App über Entitlements schützt, braucht sie keinen neuen Code, um damit umzugehen. Wenn ein Abonnement ausläuft, lassen Sie entweder das expiresAt verstreichen oder PATCHen die Lizenz auf die niedrigere Stufe mit dem reduzierten Entitlement-Set. Bei der nächsten Revalidierung trägt die signierte Zusage kein pro.export mehr, HasEntitlement("pro.export") gibt false zurück, und die geschützte Oberfläche degradiert. Ein unbefristeter Plan mit abgelaufener Wartung ist dieselbe Idee — Sie gewähren die Entitlements, die dem Kunden noch zustehen, und entfernen den Rest.

Zwei Regeln halten das sauber. Scheitern Sie geschlossen: Ist result.IsValid false, gewähren Sie nichts — fallen Sie bei einem Fehler niemals in kostenpflichtige Funktionen durch. Und degradieren Sie, zerstören Sie nicht: Eine Herabstufung sollte Funktionen ausblenden oder deaktivieren, nicht die Daten des Kunden löschen, sodass ein späteres erneutes Upgrade einfach wieder freischaltet, was schon da war.

Führen Sie eine Prüfspur

Jedes dieser PATCHes ist eine Entitlement-Änderung an einer bestimmten Lizenz, und Sie werden die Historie wollen: wann der Test zu Pro wurde, welches Add-on an welchem Datum landete, wer ein Kulanz-Upgrade autorisierte. Keyright zeichnet jede Admin-Mutation als Ereignis an der Lizenz auf — den Akteur, Stufe und Entitlement-Set vor/nach, den Idempotenzschlüssel und den Zeitstempel. Diese Historie für eine Lizenz abzurufen gibt eine vollständige Antwort auf „Warum hat dieser Kunde pro.batch?” ohne zu raten, und es ist der Datensatz, den Sie mit der Abrechnung abgleichen, wenn ein Streitfall eintrifft.

Das ganze Modell, in einer Zeile

Eine Lizenz ist eine veränderliche serverseitige Zusage hinter einem unveränderlichen Schlüssel. Upgrades, Stufenwechsel und Add-ons sind Bearbeitungen der Zusage; der Schlüssel bewegt sich nie; das SDK spiegelt die Bearbeitung bei seiner nächsten Validierung; und Sie stellen den Revalidierungstakt ein, um zu entscheiden, wie sofort sich das anfühlt. Schreiben Sie die App so, dass sie HasEntitlement(...) fragt und geschlossen scheitert, und jede kommerzielle Änderung — Test zu Bezahlt, Standard zu Pro, Add-on, Herabstufung — wird zu einem einzigen idempotenten PATCH mit einer sauberen Prüfspur dahinter.

Nebula.NET testen

Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.