Esta página aún no está traducida: se muestra la versión en inglés.

Catalog & Commerce

Artículos, precios, billeteras, tiendas, compras y derechos de uso. Integraciones reales con las tiendas de las plataformas que lo permiten (Stripe, App Store, Google Play, Steam, Xbox), tiendas con horario y segmentadas por audiencia, y un flujo de compra en el que cada paso admite un hook.

Cuándo usarlo

• Vendes cosas: por dinero real a través de Stripe, App Store, Google Play, Steam o Xbox, o por moneda de la billetera.
• Cada tienda (storefront) debe resolverse para cada jugador: el servidor calcula el horario, la audiencia y el precio, y el cliente nunca calcula quién cumple los requisitos.
• Las reglas de precios viven en un solo hook que puedes probar: los descuentos, los cambios de precio y los vetos se ejecutan antes de cualquier cobro.
• Un recibo no debe poder reutilizarse, y un reembolso debe revocar el derecho de uso (entitlement) con los mismos eventos con los que se otorgó.
• No lo necesitas si nunca vendes artículos (item). Las recompensas igual llegan por el único Grant del módulo de comercio, con origen reward (así llegan los cofres de fin de ciclo de Leaderboards), de modo que incluso un juego sin tienda conserva un único registro auditable de todo lo otorgado.

Quién hace qué

En resumen

// 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)

El modelo

Qué declara un artículo del catálogo.

Qué composiciones se permiten.

Qué declara una tienda.

Si un jugador no pertenece a la audiencia de una tienda, para él esa tienda no existe.

Los estados de un pedido.

Cada punto de extensión indica el tipo que le entrega al hook: antes de la compra, una intención de compra —jugador, oferta, proveedor, precio—, y después, la compra misma. Un hook nunca recibe un conjunto de datos sin tipo.

Errores

• Fuera de la audiencia responde not found, y repetir no sirve de nada. Fuera del horario también responde not found, pero vale la pena repetir cuando se abra la ventana.
• El proveedor no está disponible y el proveedor rechazó el pago son respuestas distintas a propósito: la primera es unavailable y se puede reintentar con backoff; la segunda es un conflicto que reintentar no resuelve.
• Un recibo inválido es un rechazo de validación; un recibo ya consumido por otro pedido o por otro jugador es un conflicto, y por eso reutilizarlo no sirve de nada.
• El precio cambió entre la lectura de la tienda y la compra: es una precondition failure. Vuelve a leer y decide de nuevo, en lugar de que te cobren el precio nuevo sin avisarte.
• Si no alcanza la moneda del juego, es un conflicto, no forbidden: el permiso para comprar existe, pero el saldo no alcanza. Vale la pena repetir después de recargar.
• Un derecho de uso durable que el jugador ya tiene es un conflicto.
• La región o la edad no permiten la compra: responde forbidden, y repetir no sirve de nada.
• Venció el plazo del pedido: es un conflicto; crea un pedido nuevo.
• Se agotó el límite de gasto: responde como conflicto o como límite de frecuencia, según el límite de que se trate, e indica cuándo se reinicia.

Límites

Las cifras llegarán con el capítulo sobre los límites de la plataforma; lo que pasa al alcanzar cada tope ya está definido.

• Tamaño del catálogo: publicar otro artículo se rechaza como conflicto.
• Tiendas por proyecto: se rechaza la creación.
• Ofertas en una tienda: se rechaza la oferta que se agrega; la tienda nunca se recorta en silencio.
• Vida útil de un pedido que espera el pago: pasa a expired y se emite un evento.
• Frecuencia de intentos de compra: un límite de frecuencia que indica cuándo volver a intentar.
• Límite de gasto por período: un conflicto que indica cuándo se reinicia el límite.
• Retención de pedidos: pasado el período declarado, un pedido deja de poder leerse, en lugar de desaparecer sin explicación.
• Derechos de uso por jugador: se rechaza el nuevo otorgamiento, y los ya otorgados nunca se eliminan para hacer lugar.
• La precisión de un precio no es un límite, sino un tipo: un entero en unidades menores.