Программа лояльности
Связанные разделы: VIP-программа в кабинете игрока и управление программой.
Полная программа игрока
loyaltyProgram
Операция возвращает me.loyaltyProgram: рассчитанный прогресс текущего игрока и полную опубликованную структуру проекта. Названия и описания возвращаются массивами displayNames и descriptions, поэтому клиент выбирает точное совпадение locale, затем основной язык проекта.
Пример обмена
{
"documentId": "loyaltyProgram",
"variables": {}
}
{
"data": {
"me": {
"loyaltyProgram": {
"progress": {
"active": true,
"programEnabled": true,
"progressMode": "rolling_window",
"progressState": "active",
"currentProgress": "7619.000000",
"pendingProgress": "1500.000000",
"lifetimeProgress": "7619.000000",
"currentLevelId": "01910000-0000-7000-8000-000000000105",
"nextLevelId": "01910000-0000-7000-8000-000000000106",
"cycle": {
"id": "01910000-0000-7000-8000-000000000201",
"startsAt": "2026-08-01T00:00:00.000000Z",
"endsAt": "2026-08-31T23:59:59.999999Z",
"frozenUntil": null
},
"forecast": {
"projectedProgress": "1119.000000",
"projectedLevelId": "01910000-0000-7000-8000-000000000102",
"requiredToRetain": "4881.000000",
"downgradeAt": "2026-09-04T18:00:00.000000Z",
"frozenUntil": null,
"expiringContributions": [
{
"ledgerEntryId": "01910000-0000-7000-8000-000000000301",
"progress": "6500.000000",
"expiresAt": "2026-09-04T18:00:00.000000Z"
}
]
}
},
"displayMode": "grouped",
"colors": [
{
"id": "01910000-0000-7000-8000-000000000401",
"displayNames": [
{
"locale": "ru",
"text": "Сапфир"
},
{
"locale": "en",
"text": "Sapphire"
}
],
"hexColor": "#4680FF",
"cssClass": null,
"sortOrder": 10
}
],
"tiers": [
{
"id": "01910000-0000-7000-8000-000000000501",
"code": "knight",
"displayNames": [
{
"locale": "ru",
"text": "Рыцарь"
},
{
"locale": "en",
"text": "Knight"
}
],
"descriptions": [
{
"locale": "ru",
"text": "Вторая категория программы"
}
],
"imageReference": "/data/project/1/vip/knight.webp",
"colorId": "01910000-0000-7000-8000-000000000401",
"sortOrder": 20,
"enabled": true
}
],
"levels": [
{
"id": "01910000-0000-7000-8000-000000000105",
"tierId": "01910000-0000-7000-8000-000000000501",
"colorId": "01910000-0000-7000-8000-000000000401",
"code": "knight-2",
"displayNames": [
{
"locale": "ru",
"text": "Рыцарь II"
},
{
"locale": "en",
"text": "Knight II"
}
],
"descriptions": [],
"imageReference": "/data/project/1/vip/knight-2.webp",
"minimumProgress": "6000.000000",
"stageOrder": 2,
"rewardsEnabled": true,
"enabled": true,
"benefits": [
{
"key": "top-up-bonus",
"benefitKind": "TOP_UP_BONUS",
"valueKind": "PERCENTAGE",
"numericValue": "7.000000",
"aggregation": "MAX",
"scopeMode": "PROJECT",
"displayNames": [
{
"locale": "ru",
"text": "Бонус к пополнению"
}
],
"descriptions": [],
"gameServerIds": [],
"resourceCategories": [],
"icon": {
"kind": "CSS_CLASS",
"reference": "ti ti-sparkles"
},
"configuration": {},
"enabled": true,
"sortOrder": 10,
"availability": "AVAILABLE"
}
],
"rewards": [
{
"key": "knight-2-items",
"rewardKind": "GAME_ITEM_BUNDLE",
"displayNames": [
{
"locale": "ru",
"text": "Набор Рыцаря"
}
],
"descriptions": [],
"imageReference": "/data/project/1/vip/rewards/knight-2.webp",
"serverScope": "SELECTED_GAME_SERVERS",
"gameServerIds": [
1
],
"enabled": true,
"sortOrder": 10,
"availability": "AVAILABLE",
"components": [
{
"componentKind": "GAME_ITEM",
"resourceReference": "57",
"quantity": "250000",
"enchantLevel": 0,
"payload": {},
"sortOrder": 10
}
]
}
]
}
],
"currentLevel": {
"id": "01910000-0000-7000-8000-000000000105"
},
"nextLevel": {
"id": "01910000-0000-7000-8000-000000000106"
}
}
}
}
}
Прогресс и прогноз
LoyaltyProgress содержит:
| Поле | Тип | Описание |
|---|---|---|
active | Boolean! | Игрок сейчас получает эффекты программы |
programEnabled | Boolean! | Программа опубликована и включена |
progressMode | LoyaltyProgressMode! | Способ расчёта периода |
progressState | LoyaltyProgressState! | Текущее состояние прогресса |
currentProgress | String! | Подтверждённый прогресс активного периода |
pendingProgress | String! | Сумма, ожидающая подтверждения |
lifetimeProgress | String! | Параллельный бессрочный прогресс |
currentLevelId | ID | Текущий уровень |
nextLevelId | ID | Следующий уровень |
cycle | LoyaltyProgressCycle | Границы активного цикла и заморозки |
forecast | LoyaltyProgressForecast! | Прогноз понижения и выходящих вкладов |
Режимы: lifetime, personal_cycle, calendar_month, rolling_window, season. Состояния: inactive, active, frozen, grace. Значение unspecified является защитным контрактным состоянием и не должно использоваться как пользовательская подпись.
В forecast.expiringContributions каждая запись содержит идентификатор записи прогресса, точную сумму и дату выхода из расчёта. requiredToRetain показывает сумму, необходимую для сохранения текущего уровня после прогнозируемого изменения.
Структура программы
displayMode = groupedгруппирует уровни поtiers.displayMode = flatпоказываетlevelsкак самостоятельные ранги.colorsявляется опубликованной палитрой, на которую ссылаются уровни и категории.currentLevelиnextLevelсодержат идентификаторы объектов изlevels; клиент не строит уровень по порогу самостоятельно.minimumProgress,numericValue, суммы прогресса и количества возвращаются строками для точного десятичного представления.
Преимущества
LoyaltyProgramBenefit описывает отображаемое правило уровня:
| Поле | Назначение |
|---|---|
benefitKind | Тип поддерживаемого эффекта |
valueKind | PERCENTAGE, MULTIPLIER, WHOLE_NUMBER или CONFIGURATION |
numericValue | Точное числовое значение либо null для конфигурационного типа |
aggregation | MAX, SUM или REPLACE |
scopeMode | PROJECT, ALL_GAME_SERVERS или SELECTED_GAME_SERVERS |
gameServerIds | Серверы для выбранной области |
resourceCategories | Дополнительное ограничение по категории операции |
availability | Фактическая доступность подключённого эффекта |
Типы преимуществ: TOP_UP_BONUS, SHOP_DISCOUNT, REFERRAL_REWARD_MULTIPLIER, MARKET_FEE_DISCOUNT, GAME_ACCOUNT_LIMIT, LINKED_ACCOUNT_LIMIT, PROMO_ATTEMPTS, BONUS_CODE_BALANCE_MULTIPLIER, SUPPORT_PRIORITY, PROFILE_COSMETIC, CUSTOM.
availability принимает AVAILABLE, DISABLED, NOT_CONFIGURED или UNAVAILABLE. Недоступное преимущество остаётся видимым в структуре и сравнении, но клиент не должен обещать его применение.
Используйте опубликованные значения для отображения преимуществ текущего уровня.
Награды
LoyaltyProgramReward задаёт правило и состояние отображения награды уровня. Поддерживаются GAME_ITEM, GAME_ITEM_BUNDLE, ENTITLEMENT и CUSTOM_DELIVERY.
components содержит типизированный состав:
GAME_ITEM- идентификатор предмета, количество и необязательный уровень заточки;ENTITLEMENT- зарегистрированное право;CUSTOM_RESOURCE- ресурс подключённой интеграции с типизированным payload.
Область выдачи равна ALL_GAME_SERVERS или SELECTED_GAME_SERVERS. Повтор обработки одного достижения не создаёт вторую выдачу в том же цикле.
Ошибки
Для поля me требуется авторизованная сессия. При временной недоступности расчёта возвращается ошибка GraphQL; предложите повторить запрос позже.