Mettre à niveau une licence sur place, d'essai à payant
Quand un client convertit un essai en abonnement payant ou passe de Standard à Pro, la chaîne de clé qu'il a déjà activée ne devrait pas changer. Voici comment mettre à niveau une licence côté serveur avec Keyright — en retirant l'indicateur d'essai, en prolongeant l'expiration, en ajoutant des entitlements — pour que l'application déployée avec le SDK adopte la nouvelle concession dès son prochain ValidateAsync, sans friction de réactivation, ainsi que comment régler le rythme de revalidation, garder l'appel de mise à niveau idempotent et auditer chaque changement d'entitlements.
Un client termine son essai et paie. Ou un client Standard passe à Pro. Ou il achète un module complémentaire en cours de période. À chacun de ces moments, l’instinct est de générer une nouvelle clé de licence et de l’envoyer par courriel — et à chacun d’eux c’est le mauvais choix. La clé que le client a déjà activée est une concession signée d’entitlements ; convertir un essai en payant, ou Standard en Pro, est un changement dans ce que dit cette concession, non une raison de la remplacer. Mettez à niveau la licence en place et la chaîne de clé installée chez le client ne change jamais : aucune nouvelle clé à livrer, aucun copier-coller, aucune réactivation, aucun ticket « je n’ai jamais reçu ma clé ».
Voici un guide pratique pour faire exactement cela avec un déploiement Keyright auto-hébergé. Nous allons modifier une licence côté serveur, observer l’application déployée avec le SDK adopter les nouveaux entitlements à sa prochaine validation, puis traiter les parties qui rendent cela instantané et correct : propagation du cache, idempotence, rétrogradations et piste d’audit.
L’application déployée ne change jamais
Commençons par le côté de l’application, car c’est la partie qui ne doit pas bouger. Une application .NET intègre le SDK Keyright, l’initialise une fois et protège les fonctionnalités par des entitlements :
KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-studio",
PublicKeyBase64 = "MCowBQYDK2VwAyEA...", // la clé de vérification de votre déploiement
ServiceUrl = "https://license.acme.example",
});
var result = await client.ValidateAsync();
if (!result.IsValid)
{
// Échec en mode fermé : pas de licence valide → pas de fonctionnalités payantes.
EnterRestrictedMode(result);
return;
}
// Protégez une fonctionnalité payante par un entitlement, pas par un nom de palier.
exportButton.Enabled = client.HasEntitlement("pro.export");
Remarquez ce que l’application ne fait pas : elle ne vérifie pas une chaîne de palier, ne compare pas de dates, ne traite pas « trial » comme un cas particulier. Elle pose une question par fonctionnalité — HasEntitlement("pro.export") — et échoue en mode fermé quand la licence est invalide. Cette seule discipline est ce qui rend possible une mise à niveau en place, car la seule chose qu’une mise à niveau doit faire est de changer les entitlements que porte la licence. Le code de l’application est déjà écrit pour réagir.
Changez la licence, pas la clé
Côté serveur, une mise à niveau est un correctif de l’enregistrement de licence existant. Keyright l’expose via l’API d’administration (et la même action est disponible comme bouton dans le tableau de bord). La licence est adressée par son id — pas par la chaîne de clé, qui reste privée au client :
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
}
Cet unique appel réalise toute la conversion d’essai en payant : il retire l’indicateur trial, repousse l’expiration d’un an et remplace le jeu d’entitlements de l’essai par celui du payant. L’id de la licence est inchangé, donc la chaîne de clé que le client a saisie dans l’application il y a une semaine reste valide et reste la sienne. Rien de sa machine, de son activation ou de ses données ne bouge. La prochaine fois que son application valide, le service d’émission signe une concession fraîche portant pro.export et pro.batch, et HasEntitlement("pro.export") renvoie true.
Une montée de palier (Standard → Pro) a la forme identique — vous envoyez le palier Pro et son jeu d’entitlements plus large. Un module complémentaire en cours de période est encore plus petit : laissez tier et expiresAt tels quels et envoyez la liste d’entitlements avec la capacité supplémentaire ajoutée. Comme l’application protège par des chaînes d’entitlement individuelles, ajouter pro.batch à la liste déverrouille exactement cette fonctionnalité et ne touche à rien d’autre.
Comment l’application l’adopte
La mise à niveau est active sur le serveur dès l’instant où le PATCH est validé. Le moment où l’application la voit dépend du rythme de validation.
Entre les validations, le SDK sert une concession en cache pour que l’application continue de fonctionner hors ligne et ne touche pas le réseau à chaque vérification de fonctionnalité. Si le client a payé pendant cette fenêtre en cache, l’application continue d’afficher l’essai jusqu’à ce que le cache expire et qu’elle revalide. Ce n’est pas un bogue — c’est la tolérance hors ligne qui rend le SDK utilisable — mais c’est ce qui fait qu’une mise à niveau semble cassée.
Trois leviers comblent l’écart :
- Raccourcissez l’intervalle de revalidation pour les produits où les mises à niveau instantanées comptent. Un
RevalidationIntervalplus court signifie que le prochainValidateAsyncen ligne a lieu plus tôt, donc les nouveaux entitlements arrivent plus tôt. Le compromis est davantage de contacts avec le serveur ; réglez-le selon l’expérience souhaitée. - Forcez une validation sur une action de l’utilisateur. Donnez à l’application un élément de menu « Actualiser la licence », ou déclenchez
ValidateAsyncquand l’utilisateur ouvre l’écran de réussite de la mise à niveau après son retour du paiement. Cela transforme l’écart de propagation en un unique aller-retour. - Revalidez à la reprise. Appeler
ValidateAsyncau démarrage de l’application ou au focus de la fenêtre signifie qu’un client qui a payé et rouvert l’application reçoit la mise à niveau immédiatement, ce qui est le chemin de conversion le plus courant.
// Appelé depuis une action « Actualiser la licence » au retour du client depuis le paiement.
async Task RefreshAfterPurchaseAsync()
{
var result = await client.ValidateAsync(force: true); // ignore le cache
if (result.IsValid && client.HasEntitlement("pro.export"))
UnlockProFeatures(result.LicenseInfo); // en direct, même clé
}
result.LicenseInfo porte le palier, le jeu d’entitlements et l’expiration actualisés, de sorte que l’interface peut réétiqueter le plan et retirer la bannière « l’essai se termine dans N jours » dans la même passe.
Rendez la mise à niveau idempotente
Les mises à niveau sont généralement pilotées par un webhook de facturation, et les webhooks sont livrés au moins une fois — le même événement order.paid peut arriver deux fois, et un appel ayant expiré sera réessayé. Si votre logique de mise à niveau était une mutation relative (« ajoute 1 an », « ajoute un entitlement »), un doublon doublerait l’expiration ou empilerait une seconde copie. Modélisez donc la mise à niveau comme une déclaration d’état cible, non comme un delta.
Le PATCH ci-dessus fait cela : il fixe le palier, la liste complète d’entitlements et le expiresAt absolu. Envoyez-le deux fois et la licence converge vers le même enregistrement — palier pro, ces entitlements, cette expiration. L’en-tête Idempotency-Key: order-558120 le rend explicite : Keyright enregistre le résultat sous cette clé, de sorte qu’un réessai rejoue le résultat stocké au lieu de réappliquer le changement. Associez-la à la référence de la commande ou du paiement — quelque chose de stable entre les réessais du même achat et distinct entre des achats réellement différents.
// Gestionnaire du webhook de facturation — sûr à exécuter à chaque livraison de l'événement.
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, // absolu, non relatif
Trial = false,
}, idempotencyKey: e.OrderId);
return Results.Ok();
});
Rétrogradations et expiration
Le même chemin s’exécute à l’envers, et comme l’application protège par des entitlements elle n’a besoin d’aucun code nouveau pour le gérer. Quand un abonnement expire, soit vous laissez passer le expiresAt, soit vous faites un PATCH de la licence vers le palier inférieur avec le jeu d’entitlements réduit. À la prochaine revalidation, la concession signée ne porte plus pro.export, HasEntitlement("pro.export") renvoie false, et l’interface protégée se dégrade. Un plan perpétuel dont la maintenance a expiré est la même idée — vous accordez les entitlements encore dus au client et retirez le reste.
Deux règles gardent cela propre. Échouez en mode fermé : si result.IsValid est false, n’accordez rien — ne tombez jamais sur des fonctionnalités payantes en cas d’erreur. Et dégradez, ne détruisez pas : une rétrogradation doit masquer ou désactiver des fonctionnalités, non supprimer les données du client, afin qu’une éventuelle remontée redéverrouille simplement ce qui était déjà là.
Tenez une piste d’audit
Chacun de ces PATCH est un changement d’entitlements sur une licence précise, et vous voudrez l’historique : quand l’essai est devenu Pro, quel module complémentaire a atterri à quelle date, qui a autorisé une mise à niveau gracieuse. Keyright enregistre chaque mutation d’administration comme un événement sur la licence — l’acteur, le palier et le jeu d’entitlements avant/après, la clé d’idempotence et l’horodatage. Extraire cet historique pour une licence donne une réponse complète à « pourquoi ce client a-t-il pro.batch ? » sans deviner, et c’est l’enregistrement que vous réconciliez face à la facturation quand un litige survient.
Tout le modèle, en une ligne
Une licence est une concession mutable côté serveur derrière une clé immuable. Les mises à niveau, les changements de palier et les modules complémentaires sont des modifications de la concession ; la clé ne bouge jamais ; le SDK reflète la modification à sa prochaine validation ; et vous réglez le rythme de revalidation pour décider à quel point cela paraît instantané. Écrivez l’application pour qu’elle demande HasEntitlement(...) et échoue en mode fermé, et chaque changement commercial — de l’essai au payant, de Standard à Pro, module complémentaire, rétrogradation — devient un unique PATCH idempotent avec une piste d’audit propre derrière lui.
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.