Цю сторінку ще не перекладено — показано англійську версію.

Catalog & Commerce

Предмети, ціни, гаманці, вітрини, покупки та права володіння. Справжні інтеграції з магазинами там, де платформи це дозволяють (Stripe, App Store, Google Play, Steam, Xbox). Вітрини за розкладом і для обраної аудиторії. Покупка, кожен крок якої можна перехопити хуком.

Коли це потрібно

• Ви щось продаєте: за реальні гроші через Stripe, App Store, Google Play, Steam чи Xbox або за валюту з гаманця.
• Вітрину (storefront) треба формувати під кожного гравця окремо: розклад, аудиторію й ціну обчислює сервер, а клієнт ніколи сам не вирішує, що гравцеві доступно.
• Правила ціноутворення мають жити в одному хуку, який можна протестувати: знижки, зміна ціни й заборона покупки спрацьовують ще до списання коштів.
• Чек не можна використати повторно, а повернення коштів має відкликати право володіння (entitlement) через ті самі події, якими його видали.
• Не знадобиться, якщо ви нічого не продаєте. Нагороди однаково надходять через єдиний Grant модуля Catalog & Commerce із джерелом reward (саме так приходять скрині за цикл у Leaderboards), тож навіть гра без магазину веде один журнал видач, який можна перевірити.

Хто що робить

Коротко

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

Модель

Що оголошує предмет каталогу.

Якою може бути композиція.

Що оголошує вітрина.

Якщо гравець не входить в аудиторію вітрини, для нього ця вітрина не існує.

Стани замовлення.

Кожна точка розширення називає тип, який вона передає хуку: перед покупкою — намір покупки (гравець, пропозиція, провайдер, ціна), після — саму покупку. Нетипізованого набору даних хук не отримує ніколи.

Помилки

• Поза аудиторією — відповідь not found, і повторювати марно. Поза розкладом — теж not found, але запит варто повторити, коли вікно відкриється.
• Провайдер недоступний і провайдер відхилив платіж — навмисно різні відповіді. Перша — unavailable, і запит можна повторити з наростаючою затримкою. Друга — конфлікт, який повтор не виправить.
• Недійсний чек — це відмова валідації. Чек, який уже використало інше замовлення чи інший гравець, — конфлікт: саме тому повторне використання чека нічого не дає.
• Ціна змінилася між читанням вітрини й покупкою — це precondition failure: перечитайте вітрину й вирішіть ще раз, щоб нова ціна не списалася мовчки.
• Брак ігрової валюти — це конфлікт, а не заборона: дозвіл на покупку у гравця є, просто не вистачає балансу. Після поповнення варто повторити.
• Постійне право володіння, яке вже є в гравця, — конфлікт.
• Регіон або вік не дозволяють покупку — відповідь forbidden, і повторювати марно.
• Минув термін замовлення — конфлікт: створіть нове замовлення.
• Вичерпано ліміт витрат — конфлікт або обмеження частоти, залежно від того, який саме ліміт спрацював. У відповіді вказано, коли ліміт оновиться.

Обмеження

Конкретні числа з’являться в розділі про ліміти платформи, а що відбувається на кожній межі, визначено вже зараз.

• Розмір каталогу: публікацію ще одного предмета відхиляють як конфлікт.
• Вітрини на проєкт: створення нової вітрини відхиляють.
• Пропозиції у вітрині: додавання нової відхиляють; вітрину ніколи не обрізають мовчки.
• Час життя замовлення, що чекає оплати: перехід у expired із подією.
• Частота спроб покупки: обмеження частоти з указаним терміном.
• Ліміт витрат за період: конфлікт, у якому вказано, коли ліміт оновиться.
• Зберігання замовлень: після оголошеного періоду замовлення вже не можна прочитати, але воно не зникає без пояснень.
• Права володіння на гравця: нову видачу відхиляють, а вже видане ніколи не витісняють.
• Точність ціни — не ліміт, а тип: ціле число в мінімальних одиницях.