Cette page n’est pas encore traduite : la version anglaise est affichée.

Catalog & Commerce

Objets, prix, portefeuilles, boutiques, achats et droits d’usage. De vraies intégrations avec les stores, là où les plateformes les permettent (Stripe, App Store, Google Play, Steam, Xbox) ; des boutiques programmées et ciblées par audience ; un parcours d’achat dont chaque étape accepte un hook.

Quand l’utiliser

• Vous vendez des choses : contre de l’argent réel via Stripe, App Store, Google Play, Steam ou Xbox, ou contre la monnaie du portefeuille (wallet).
• Chaque boutique (storefront) doit être résolue pour chaque joueur : le serveur calcule le calendrier, l’audience et le prix, et le client ne calcule jamais qui y a droit.
• Les règles de prix tiennent dans un seul hook que vous pouvez tester : remises, changements de prix et vetos s’exécutent avant tout débit.
• Un reçu (receipt) ne doit pas pouvoir être rejoué, et un remboursement doit révoquer le droit d’usage (entitlement) par les mêmes événements que ceux qui l’ont accordé.
• Inutile si vous ne vendez jamais rien. Les récompenses arrivent tout de même par l’unique Grant du commerce, avec l’origine reward (c’est ainsi que les coffres de fin de cycle de Leaderboards sont remis) : même un jeu sans boutique garde un seul registre d’attributions, auditable.

Qui fait quoi

En bref

// client — the storefront arrives already resolved for this player
var front = await playserv.Commerce.Storefront("main");
var order = await playserv.Commerce.Purchase(front.Items.First(), pay: Pay.Wallet("gems"));

// client — the storefront arrives already resolved for this player
const front = await playserv.commerce.storefront('main');
const order = await playserv.commerce.purchase(front.items[0], { pay: Pay.wallet('gems') });

# client — the storefront arrives already resolved for this player
front = await playserv.commerce.storefront("main")
order = await playserv.commerce.purchase(front.items[0], pay=Pay.wallet("gems"))

// client — the storefront arrives already resolved for this player
Client->Commerce->Storefronts->Select().Then(
    TPSOnResult<TPSPage<FPSStorefront>>::CreateWeakLambda(this, [this](const TPSResult<TPSPage<FPSStorefront>>& Result)
    {
        if (!Result.HasValue()) { return; }
        const FPSStorefront& Front = Result.Value().Rows[0];
        Client->Commerce->Orders->Create(FPSIdempotencyKey(CartId), Front.Items[0], FPSPay::Wallet(TEXT("gems")));
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// client — the storefront arrives already resolved for this player
var front = await playserv.Commerce.Storefront("main");
var order = await playserv.Commerce.Purchase(front.Items.First(), pay: Pay.Wallet("gems"));

[Before(Commerce.Purchase)]                    // veto or reprice
public static Verdict FirstBuyDiscount(PurchaseIntent p) =>
    p.Player.Purchases == 0 ? Hook.Continue(p.WithPrice(p.Price * 0.5m)) : Hook.Continue(p);

[After(Commerce.Purchase)]                     // grant — side effects only
public static Task Grant(Purchase done) =>
    done.Player.Inventory.Grant(done.Item, done.Count);

// veto or reprice
export const firstBuyDiscount = before(Commerce.purchase, (p: PurchaseIntent) =>
  p.player.purchases === 0 ? Hook.continue(p.withPrice(p.price * 0.5)) : Hook.continue(p));

// grant — side effects only
export const grant = after(Commerce.purchase, (done: Purchase) =>
  done.player.inventory.grant(done.item, done.count));

@before(commerce.purchase)                     # veto or reprice
def first_buy_discount(p: PurchaseIntent) -> Verdict:
    return Hook.continue_(p.with_price(p.price * 0.5)) if p.player.purchases == 0 else Hook.continue_(p)

@after(commerce.purchase)                      # grant — side effects only
async def grant(done: Purchase):
    await done.player.inventory.grant(done.item, done.count)

Le modèle

Ce que déclare un objet du catalogue.

Ce qu’une composition a le droit d’être.

Ce que déclare une boutique.

Une boutique dont un joueur ne fait pas partie de l’audience n’existe pas pour ce joueur.

Les états d’une commande.

Chaque point d’extension nomme le type qu’il transmet au hook : avant l’achat, une intention d’achat (joueur, offre, fournisseur, prix) ; après, l’achat lui-même. Un hook ne reçoit jamais un sac de valeurs non typé.

Erreurs

• Hors de l’audience répond not found, et réessayer ne sert à rien. Hors du calendrier répond aussi not found, mais vaut la peine d’être retenté une fois la fenêtre ouverte.
• Le fournisseur est indisponible et le fournisseur a refusé le paiement sont volontairement deux réponses différentes : la première est unavailable et se retente avec un délai croissant ; la seconde est un conflit qu’un nouvel essai ne résoudra pas.
• Un reçu invalide est un refus de validation ; un reçu déjà consommé par une autre commande ou un autre joueur est un conflit, et c’est ce qui rend le rejeu inutile.
• Le prix a changé entre la lecture de la boutique et l’achat : c’est une precondition failure. Relisez et décidez à nouveau, plutôt que de payer le nouveau prix sans le savoir.
• Une monnaie de jeu insuffisante est un conflit, pas forbidden : la permission d’acheter est acquise, c’est le solde qui ne suffit pas. Cela vaut la peine de réessayer après avoir rechargé.
• Un droit d’usage durable déjà détenu est un conflit.
• La région ou l’âge n’autorise pas l’achat répond forbidden, et réessayer ne sert à rien.
• L’échéance de la commande est dépassée : c’est un conflit, créez une nouvelle commande.
• Le plafond de dépenses est atteint : selon le plafond en cause, la réponse est un conflit ou une limite de débit, et elle indique quand le plafond se réinitialise.

Limites

Les chiffres arriveront avec le chapitre sur les limites de la plateforme ; ce qui se passe à chaque plafond est déjà fixé.

• La taille du catalogue : la publication d’un objet supplémentaire est refusée comme conflit.
• Les boutiques par projet : la création est refusée.
• Les offres d’une boutique : l’ajout est refusé ; la boutique n’est jamais tronquée en silence.
• La durée de vie d’une commande en attente de paiement : passage à expired, avec un événement.
• La fréquence des tentatives d’achat : une limite de débit, avec un délai.
• Le plafond de dépenses par période : un conflit qui indique quand le plafond se réinitialise.
• La rétention des commandes : au-delà de la durée déclarée, une commande n’est plus lisible, au lieu de disparaître sans explication.
• Les droits d’usage par joueur : l’attribution est refusée, et ceux déjà attribués ne sont jamais évincés.
• La précision d’un prix n’est pas une limite mais un type : un entier en unités mineures.