Mahabatlary we bonuslary backend derejesinde dolandyrmak

Makalanyň doly teksti

💡 18+. Platformalar/operatorlar we üpjün edijiler üçin in engineeringenerçilik-amaly material. Oýnamaga çagyryş ýok. "Gapjyk" diýlende ACID-kepillikleri bolan "Ledger/Wallet", "bonuslar" diýlende oýnuň balansyna we şertlerine täsir edýän mahabatlandyryjylara düşünýäris.

1) Näme üçin mahabaty aýratyn backend-e geçirmeli?

Pul üýtgemeleri. Bonus ≠ "balans goşuldy": bu şertler bilen baglaşylan şertnama (wakjer, oýunlar boýunça goýum, iň ýokary stawka/ýeňiş).

Üýtgeşmeleriň tizligi. Marketing toparlary her gün kampaniýalary çykarýarlar - düzgünleriň deklaratiw hereketlendirijisi we yza gaýdyp gelmek zerurdyr.

Anti-hyýanat/gabat gelmek. KYC/RG/AML, velocity, segmentasiýa, gymmat bahaly offerlere "dört gözüň" daşlary.

Gözegçilik we hasabat. SLO, mahabatyň bahasy, GGR/NGR/LTV-e täsiri.

Prinsip: mahabat özeni - öz status maşynlary bolan aýratyn hyzmat, pul bolsa diňe gapjyk arkaly, idempotent görnüşinde hereket edýär.

2) Bonuslaryň tipologiýasy we inwariantlar

Deposit match (100% -den X-a çenli): depozit capture-dan soň hasaplanylýar, weyjer X ×.

"Cashback": wagt/oýun penjiresi boýunça hasaplanylýar, sticky/non-sticky bolup biler.

Free Spins/Free Bets: spin/stawka bahasy bolan kuponlar/bellikler, kesgitlenen RTP howzy.

Gözlegler/missiýalar: wezipe → ösüş → baýrak.

Ýaryşlar/reýs-wakalar: wakalaryň goşantlary, reýting, baýraklar.

Üýtgeşik:

Sticky: Şertleri ýerine ýetirmezden çykaryp bolmaz.
Max bet/Max win: bonus serişdelerinden stawka/töleg çäkleri.
Contribution: oýunlar boýunça goşant (mysal üçin slots = 100%, live = 10%).
Expiry: Bonus möhleti we Wakjer penjiresi.

3) Bonus hyzmatynyň arhitekturasy


Admin (kampaniýalar/düzgünler) ─ Promo API ─ Rules Engine/Eligibility
│
─ Bonus Ledger (offerleriň ýagdaýy)
─ Wagering Engine (ösüş)
─ Anti-Abuse (çäklendirmeler/frod/velocity)
└─Outbox (events) ─Kafka/Pulsar ─BI/DWH/CRM

Wallet/Ledger── Idempotent Commands ───┘

Rules Engine - deklaratiw şertler (segmentler, geo/ygtyýarnama, kanallar, KYC/RG).

Wagering Engine - 'bet' -den goşant hasaplaýar. settled`/`wallet. debit	credit`.
Bonus Ledger - bonuslaryň/missiýalaryň ýagdaýlary boýunça hakykat çeşmesi.
Outbox/CDC - ygtybarly neşir 'bonus. issued	progress. updated

4) Maglumatlaryň modeli (ýönekeýleşdirilen)

`bonus_grant`

`grant_id, player_id, offer_id, type, currency, amount_minor, sticky, wager_x, max_bet_minor, max_win_minor, contribution_schema_id, status (issued	active	paused	completed	expired	revoked), issued_at, expires_at, brand_id, region, idempotency_key`

`wager_progress`

`grant_id, required_minor, contributed_minor, remaining_minor, last_update_at`

`contribution_schema`

`schema_id, rules: [{game_type:"slot", pct:100},{game_type:"live", pct:10}]`

'bonus _ ledger _ entry' (audit)

`entry_id, grant_id, action (issue	consume	revoke	expire	adjust), amount_minor, reason, occurred_at, trace_id`

5) Status maşynlary we saglar

5. 1 Bermek (issue) - saga

1. eligibility. check (segment, RG/KYC, velocity)

2. grant. create (status=`issued`)

3. wallet. credit [bonus] (idempotent; sticky - bonus alt balansyna)

4. activate (status=`active`)

5. emit `bonus. issued`

Rollback: 3 ädimde düşende → 'grant. cancel '+ waka' bonus. revoked`.

5. 2 Wakjeriň ösüşi

Na 'bet. settled 'goýumy hasaplamak =' stake _ minor contribution_pct' (ýa-da win/loss düzgünleri boýunça).

'wager _ progress' ýadro taýdan täzelensin; 100% -e ýetende - 'complete'.

5. 3 Tamamlamak (consume)

complete → `wallet. convert_bonus_to_cash' çäklendirmelerini aýyrmak ýa-da aýyrmak.

emit `bonus. consumed`.

5. 4 Gutarmagy/yzyna alynmagy

'expires _ at' ýa-da frod → 'revoke' düzgüni (idempotent) boýunça syýasata laýyklykda öwezini dolmak mümkindir.

6) Gapjyk bilen şertnamalar (diňe API arkaly, elmydama idempotent)

Bonus hasaplamak


POST /v1/wallet/credit
Headers: X-Idempotency-Key: bonus_grant_123
{
"player_id":"p_001",  "amount":{"minor_units":100000,"currency":"EUR"},  "balance_type":"bonus",  "reference":{"grant_id":"gr_123","offer_id":"of_777"}
}
→ 200 {"status":"credited","entry_id":"e_9001"}

Şertler ýerine ýetirilenden soň kesele öwürmek


POST /v1/wallet/convert
Headers: X-Idempotency-Key: bonus_convert_gr_123
{
"player_id":"p_001",  "from_balance":"bonus",  "to_balance":"cash",  "amount_minor":100000,  "reference":{"grant_id":"gr_123"}
}
→ 200 {"status":"converted","entry_id":"e_9010"}

Barlamak max bet/max win - RGS/Wallet Guard tarapynda:

'bets. authorize 'BONUS _ MAX _ BET _ EXCEEDED' kody bilen ret edilýär.

7) Promo hyzmatynyň API (standartlary)

Täze offer (admin)


POST /v1/offers
{
"name":"Welcome 100% up to 100€",  "type":"deposit_match",  "params":{"match_pct":100,"cap_minor":10000,"wager_x":20,"sticky":true,       "max_bet_minor":200,"max_win_minor":50000,"contribution_schema_id":"c_slot100_live10"},  "eligibility":{"brands":["A"],"regions":["EU"],"segment":"new_depositors"},  "schedule":{"start":"2025-10-20T00:00:00Z","end":"2025-11-30T23:59:59Z"}
}
→ 201 {"offer_id":"of_777"}

Bonus (runtime)


POST /v1/bonus/grants
Headers: X-Idempotency-Key: grant_p001_of777
{
"player_id":"p_001","offer_id":"of_777","trigger":"deposit_captured","amount_minor":10000
}
→ 200 {"grant_id":"gr_123","status":"active"}

Wakjeriň ösüşi (read)


GET /v1/bonus/grants/gr_123/progress
→ 200 {"required_minor":200000,"contributed_minor":45000,"remaining_minor":155000,"pct":0. 225}

Ýatyrmak/yzyna almak


POST /v1/bonus/grants/gr_123/revoke
Headers: X-Idempotency-Key: revoke_gr_123
{ "reason":"fraud_velocity" }
→ 200 {"status":"revoked"}

Write jaňlarynyň hemmesi 'X-Idempotency-Key' we 'X-Trace-Id' -den.

8) Hyýanatçylyga garşy we gabat gelmek

"Velocity" çäkleri: depozit bermek/öwrülişikler/synanyşyklar (Redis counters + TTL + Lua).

Triggerleriň dedupy: bir goýum → düzgün boýunça bir grant.

Segmentasiýa we RG: self-excluded/limit; per brand/region lisenziýasy.

Offerleriň gapma-garşylygy bloky: bir wagtyň özünde diňe bir welcome bonus işjeňdir; ileri tutulýan ugurlar.

Anomaliýa detektory: köp hasaplar/enjamlar/ASN, çalt "nol" wajer.

Uly grantlar we el bilen düzedişler üçin "Dört göz".

WORM-düzgünleriň/grantlaryň/konwersiýalaryň ähli üýtgetmeleriniň barlagy.

9) Gözegçilik, metrika we SLO

SLO:

`grant. issue p95` (issue→credited) ≤ 300–500 мс.
Täzelenme 'wager _ progress p95' ≤ 'bet pursatyndan 200 ms. settled`.
Wakalar 'bonus.' p95 tekerinde bolup geçen wakalardan 2 minut ≤.
"Ýitirilen/köpeldilen grantlar/konwersiýalar" = 0.

Metrikler:

Rate/latency по `issue/convert/revoke`, error-rate (business/4xx/5xx), `IDEMPOTENCY_MISMATCH`.
Weýjeriň öwrülişigi, ortaça 'time-to-complete', möhleti geçen paýy.
Mahabatyň bahasy: 'promo _ cost' (minor) we 'promo _ roi' kogortlarda.
Hyýanatçylyga garşy: velocity, ret edilen max bet/win.

Trace: OpenTelemetry 'trigger → grant → wallet. credit → progress. update → convert`.

10) RGS/oýunlar bilen integrasiýa

"Free Spins/Free Bets" kuponlary - 'entitlements' API arkaly: tokenleri bermek, rentaýmda hasapdan çykarmak, ulanmak boýunça telemetriýa.

Max bet/win - 'bets. authorize` и `bets. settle`; kodlary yzyna gaýtarmak 'BONUS _ RULE _ VIOLATION'.

Contribution - 'bet' derejesindäki shema. settled '(' game _ type/provider _ id '), shemalaryň wersiýasy.

11) DWH/BI we hasabatlar

Outbox wakalar → Lake (bronze) → Kümüş (dedup, SCD2) → Altyn penjireler:

`fact_bonus_grants`, `fact_wager_progress`, `fact_bonus_cost`, `fact_promo_roi`.
Tazelik SLA: Kümüş ≤ 15 minut, Altyn ≤ 30-60 minut.
Paneller: offerler/segmentler boýunça öwrülişik, time-to-complete, oýunlar boýunça goşant, hyýanatçylykly hadysalar.

12) Howpsuzlyk we rezidentlik

mTLS + OAuth2 CC; scope’ы `promo:issue`, `promo:convert`, `promo:revoke`.

Açarlar/bellikler - per brand/region, gysgaça; Vault/HSM-de syrlar.

PII-izolýasiýa: 'player _ id' - lakam; RLS по `brand/region`.

Rate limits we bermek üçin kwotalar; retraý tupanlaryndan goramak.

13) Çek-listler

Platforma/operator

Ähli pul amallary 'Idempotency-Key' bilen Wallet arkaly amala aşyrylýar.
Rules/Eligibility wersiýalary; Migrasiýa wakalarynyň "goşa haty".
Contribution shemalary merkezleşdirildi, synaglar bilen örtüldi.
Velocity we anti-frod goşuldy; Uly mukdarda "dört göz".
Outbox/CDC, DLQ we 'bonus' üçin dolandyrylýan replay.
SLO-daşbordlar, OpenTelemetry, WORM-audit.
ROI we laýyklyk üçin DWH-vitrinler (RG/AML).

Integrasiýa (RGS/gapjyk/CRM)

Barlaýaryn max bet/win; iş ýalňyşlygynyň koduny yzyna gaýtarýaryn.
'trace _ id' we 'idempotency _ key'.
Tetikler we gowşuryş kepillikleri (webhooks gol çekdi).

14) Gyzyl baýdaklar (anti-patternler)

Bonusy "el bilen" göni balansyna hasaplamak, Walletden aýlanyp geçmek.

Biperwaýlygyň ýoklugy → goşa grantlar/konwersiýalar.

Weiger 'bet' hasaplanýar. placed ', bet jemleri boýunça däl. settled`.

Hiç hili contribution shemalary ýok ýa-da üpjün edijileriň kodunda "tikilen".

Gapma-garşylykly offerler bir wagtda işjeňleşdirilýär.

Velocity/anti-frod we WORM auditi ýok.

'Bonus' wakalary outbox/CDC-den geçip çap edilýär.

Mahabatyň görkezijileri Ledger/BI bilen gabat gelmeýär (ROI vitrinleri ýok).

15) Jemleýji

Ygtybarly backend mahabaty "balans goşmak" däl-de, şertnamalar we üýtgeşmeler. Ol düzgünleri puldan tapawutlandyrýar, hakyky netijeler boýunça öňegidişligi hasaplaýar, idempotentligi we gözegçilik edilýänligi kepillendirýär, hyýanatçylykdan goraýar we barlagy üpjün edýär. Şeýle ýadro bilen marketing çalt hereket edýär, oýunçy adalatly şertleri görýär we maliýe we düzgünleşdirijiler her bir offeriň bahasynyň we täsiriniň takyk suratyny alýarlar.