Система предметов и платная торговая площадка платформы

Данная система предоставляет унифицированное решение для управления платными предметами игровой платформы, поддерживает функции покупки, распределения и статистики предметов для одиночных игр, реализует функции покупки, запроса, добавления/уменьшения предметов и их распределения по триггеру процесса игры.

• Основные функции: Покупка предметов, Запрос владения, Операции добавления/уменьшения, Мониторинг изменений, Распределение по триггеру игрового процесса

1. Функции управления в бэкенде для разработчиков

• Разработчики могут вручную создавать данные предметов через бэкенд, поддерживается загрузка таблиц (таблица единиц предметов) и иконок предметов.
• Платные предметы магазина в настоящее время поддерживают только ручное создание.
• Поддерживается создание до 5000 записей данных предметов.
• Временно поддерживаются только игры типа "разовая покупка" и "внутриигровые покупки".
• После создания предметы должны пройти проверку; после одобрения они по умолчанию переходят в статус "включено".

Функции управления предметами:

‌ID предмета‌: Уникальный идентификатор, нельзя изменить после создания
‌Название и иконка предмета‌: Используются для отображения во фронтенде
‌Иконка предмета‌: Поддерживает ручную замену изображения иконки
‌Правила создания предметов: Поддерживает выбор между Игровым предметом и Платным предметом магазина
Ограничения предмета: Поддерживает установку ограничений для распределения игрокам через платформу, таких как дневное ограничение количества распределения, общее ограничение количества или без ограничений
‌Запас предметов‌: Можно выбрать ввод количества или не устанавливать ограничений
Настройки стоимости предмета:
Бесплатный предмет (Platform activities): Поддерживает распределение через мероприятия платформы.
Платная покупка (Paid purchase): Поддерживает платную покупку в магазине предметов.
Ценообразование по умолчанию в долларах США
Цена за единицу предмета поддерживает точность до 0,0001 USD
Минимальное значение ввода для платных предметов магазина составляет 1 USD

Предложение

• Сначала зарегистрируйте единицы предметов, затем вручную введите предметы для платной покупки в магазине; поддерживает выбор одного или нескольких предметов для формирования комплектного товара для продажи.
• Когда предмет установлен как бесплатный, платформа может выбрать его распределение игрокам согласно операционным планам; он будет доставлен игровому персонажу игрока при входе в игру.

2. Интеграция SDK предметов

Описание основных интерфейсов

Название интерфейса	Сигнатура метода	Описание функции
Открыть окно покупки	openBuyGameItemsDialog(level: number)	Открывает диалоговое окно покупки предметов магазина через функциональный UI внутри игры.
Получить имеющиеся предметы	getUserGameItems(): GameItem[]	Запрашивает текущий список предметов игрока при входе в игру (включает ID и количество).
Добавить предмет	addGameItem(itemId: string, amount: number)	Распределяет предметы во время игрового процесса (поддерживает сценарии покупок, наград за уровень, завершения миссий и т.д.).
Уменьшить предмет	subtractGameItem(itemId: string, amount: number)	Потребляет предметы (сценарии использования или потребления во время игрового процесса, количество после вычета неотрицательное).
Подписаться на уведомления об изменениях	subscribeGameItemChange(callback: (res: GameItemChange) => void)	Метод обратного вызова, выполняемый при завершении оплаты платного предмета магазина.

Ключевые форматы данных

• ​**GameItem (Информация о предмете)**​: { itemId: string, amount: number }
• ​**GameItemChange (Информация об изменении)**​: { itemId: string, amount: number, changeType: 'add'|'subtract', total: number }

2.1 Получить список имеющихся предметов

// Получить список предметов, имеющихся у игрока (вызывается во время инициализации игры)
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('Имеющиеся предметы:', items);

2.2 Открыть окно покупки предметов

// Открыть окно покупки предметов
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);

2.3 Добавить предмет

// Добавить предмет (ID: 3232addasdda3aa2, количество: 10)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);

2.4 Уменьшить предмет

// Уменьшить предмет (ID: 3232addasdda3aa2, количество: 5)
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);

2.5 Подписаться на уведомления об изменении предметов

// Подписаться на уведомления об изменении предметов
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
  console.log('Изменение предмета:', res);
});

2.6 Полный процесс покупки платного предмета

// 1. Начать покупку платного предмета (ID товара: item_gold_100, соответствует предмету 100 золотых монет)
async function buyGoldItem() {
  try {
    const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
    console.log('Заказ успешно создан, номер заказа:', orderNo);
  } catch (err) {
    console.error('Ошибка создания заказа:', err);
    alert('Не удалось начать покупку, попробуйте позже');
  }
}

// 2. Подписаться на уведомление об успешной оплате (вызывается во время инициализации игры)
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
  console.log('Оплата прошла успешно, детали заказа:', order);
  if (order.status === 'success') {
    // 3. Распределить соответствующий предмет (ID товара: item_gold_100 соответствует ID предмета: 3232addasdda3aa2)
    window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
    // 4. Уведомить платформу о доставке (должен быть вызван, иначе статус заказа будет аномальным)
    await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
    alert('100 золотых монет успешно куплены, доставлены в рюкзак!');
  }
});

// 3. Сценарий исключения: Запросить детали заказа (например, если предмет не получен после оплаты)
async function checkOrder(orderNo) {
  try {
    const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
    console.log('Запрос деталей заказа:', order);
    if (order.status === 'success') {
      // Перераспределить предмет
      window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
      await window.JOGOS_SDK.payment.deliverGoods(orderNo);
    }
  } catch (err) {
    console.error('Ошибка запроса заказа:', err);
  }
}

2.7 Распределение предметов по триггеру игрового процесса (Пример: Награда за прохождение уровня)

// Прохождение уровня 10 запускает распределение предметов (включает логику дедупликации для избежания повторного получения)
function onLevel10Clear() {
  // Одиночная игра: использовать локальное хранилище для записи статуса распределения
  const hasIssued = localStorage.getItem('level10_award_issued');
  if (hasIssued) {
    alert('Награда за этот уровень уже получена, нельзя получить повторно');
    return;
  }

  // Распределить предмет (ID: 3232addasdda3aa2, количество: 10)
  window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
  // Записать статус распределения
  localStorage.setItem('level10_award_issued', 'true');
  alert('Уровень 10 успешно пройден! Получено 10 наград-предметов');
}