バックエンドレベルでのプロモーションとボーナスの管理

完全な記事

💡 18+.プラットホーム/オペレータおよび提供者のための工学そして実用的な材料。再生する呼び出しではありません。「ウォレット」では、ACID保証付きの元帳/財布を「ボーナス」で意味します。ゲームのバランスと条件に影響を与えるプロモーターです。

1）なぜ別のバックエンドにプロモーションを取る

貨幣的不変量。ボーナス≠「追加バランス」：これは条件（ベーガー、ゲームへの貢献、最大賭け/勝利）との契約です。

変更率。マーケティングチームは毎日キャンペーンをリリースします-宣言的なルールエンジンとロールバックが必要です。

反乱用/コンプライアンス。KYC/RG/AML、速度、セグメンテーション、高価なオファーのための4つの目のタスク。

観測可能性と報告。SLO、プロモーションコスト、GGR/NGR/LTVへの影響。

原則：プロモーションコアは独自のステータスマシンを備えた個別のサービスであり、お金は偶然にも財布を介してのみ移動します。

2）ボーナス型と不変量

デポジットマッチ（Xの100％前）：キャプチャーデポジット、ベガーX ×後に発生します。

キャッシュバック：時間の窓/ゲームによって計算されて、粘着性がある/非粘着性がある場合もあります。

フリースピン/フリーベット：クーポン/トークン、スピン/ベットあたりの価格、固定RTPプール。

クエスト/ミッション：タスク→進行→報酬。

トーナメント/フライトイベント：イベントの貢献、評価、賞金。

不変量：

Sticky：条件が満たされるまで出力できません。
マックスベット/マックスウィン：ボーナスファンドからのベット/ペイアウトの制限。
貢献：ゲームによる貢献（例：スロット=100％、ライブ=10％）。
有効期限：ボーナス有効期間とベーガーウィンドウ。

3）ボーナスサービスアーキテクチャ


管理者─プロモ─ルールエンジンAPI/資格
│
├─Bonus元帳（オファーのステータス）
├─Wageringエンジン（進行状況）
├─Anti-使用（制限/詐欺/速度）
└─Outbox（イベント）─カフカ/パルサー─BI/DWH/CRM

ウォレット/元帳──Idempotentコマンド───┘

ルールエンジン-宣言条件（セグメント、地理/ライセンス、チャンネル、KYC/RG）。

Wagering Engine-'bet。 settled'/'walletからの寄付をカウントします。デビット	「クレジット」
Bonus Ledgerは、ボーナス/ミッションの状態に関する真実の情報源です。
Outbox/CDC-信頼できる出版物のボーナス。発行された	進歩しています。更新しました

4）データモデル（簡略化）

'bonus_grant'

'grant_id、 player_id、 offer_id、タイプ、通貨、amount_minor、 sticky、 wager_x、 max_bet_minor、 max_win_minor、 contribution_schema_id、ステータス（発行済み）	アクティブな状態	一時停止しました	完了しました	期限切れ	取り消された）、issued_at、 expires_at、 brand_id、地域、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'（監査）

'entry_id、 grant_id、 action （issue	消費する	取り消し	期限切れ	調節して下さい）、amount_minor、理由、occurred_at、 trace_id'

5）状態機械およびサガ

5.1問題-Saga

1.応募資格があります。チェック（セグメント、RG/KYC、速度）

2.助成してくれ。create（ステータス='発行'）

3.財布だよ。クレジット［ボーナス］（idempotent；スティッキーで-ボーナスのサブバランスに）

4.activate （status='active'）

5.ボーナスを出して。発行されました'

ロールバック： ステップ3→'grantで落下するとき。'+event'ボーナスをキャンセルします。「取り消された」

5.2 Vagerの進捗状況

Na 'bet。settled 'count contribution='stake_minor contribution_pct'（または勝敗ルールによる）。

'wager_progress'をアトミックに更新します。100％に達したとき-'complete'。

5.3仕上げ（消費）

complete→'wallet。convert_bonus_to_cash'（粘着性がない場合）または出力制限を解除します。

ボーナスを出して。「消費された」

5.4有効期限/リコール

'expires_at'または詐欺ルール→'revoke' （idempotent）により、ポリシーに応じた補償が可能です。

6）財布の契約（APIによってだけ、常にidempotent）

Accrueボーナス


POST/v1/ウォレット/クレジット
ヘッダー：X-Idempotency-Key： bonus_grant_123
{
「player_id":"p_001,」「量」：{「minor_units'： 100000、」 currency「：」EUR「}、」balance_type":"bonus, 「reference」： {「grant_id」： 「gr_123」、 「offer_id」： 「of_777」}
}
→200 {「status「：「credited「、」entry_id」：」 e_9001」}

条件が満たされたときにキャッシュに変換する


POST/v1/ウォレット/変換
ヘッダー：X-Idempotency-Key： bonus_convert_gr_123
{
"player_id":"p_001," "from_balance":"bonus," to_balance":"cash, "amount_minor":100000"、参照"：{"grant_id"："gr_123"}
}
→200 {「status「：「converted「、」entry_id」：」 e_9010」}

RGS/Wallet Guard側のmax bet/max win-を確認します：

ベットをリクエストします。authorizeはコード'BONUS_MAX_BET_EXCEEDED'によって拒否されます。

7）プロモーションサービスのAPI（テンプレート）

オファーを作成する（管理者）


POST/v1/オファー
{
"name"： "Welcome 100％ up 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'：［［］"］"、"segment"："new_depositors'}、 "schedule"： {"start"： "2025-10-20T00： 00Z"、 "end'：" 2025-11-30T23： 59： 59Z"}
}
→201 {「offer_id「：」of_777」}

ボーナス（ランタイム）を発行する)


POST/v1/ボーナス/助成金
ヘッダー：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」}

賭けの進捗状況（読む）


GET/ v1/bonus/grants/gr_123/progress
→200 {「required_minor「：200000、 「contributed_minor」： 45000、」 remaining_minor」： 155000、」 pct」： 0。225}

Void/Revoke


POST/ v1/bonus/grants/gr_123/revoke
ヘッダー：X-Idempotency-Key： revoke_gr_123
{「reason「：「fraud_velocity」}
→200 {「status「：」revoked」}

すべての書き込みコールは'X-Idempotency-Key'と'X-Trace-Id'である。

8）乱用防止とコンプライアンス

速度制限：issues/conversions/deposit試行（Redis counters+TTL+Lua）。

トリガーデダップ：1つのデポジット→ルールによる1つの助成金。

セグメンテーションとRG：自己除外/制限を除外します。ブランド/地域ライセンスごとに。

オファーの競合のブロック：一度に1つのウェルカムボーナスだけがアクティブです。優先順位。

異常検出器：複数のアカウント/デバイス/ASN、ベーガーの高速「ゼロ」。

大規模な助成金と手動調整に「4つの目」。

すべてのルール/助成/変換のWORM監査。

9）観測可能性、メトリックおよびSLO

SLO（ランドマーク）：

「助かりました」issue p95 '（issue→credited） ≤ 300-500 mm。
'bet。 settled'以降の'wager_progress p95' ≤ 200msに更新します。
イベントのボーナス。'P95バスで≤何が起こったから2分。
"Lost/duplicated grants/conversions'=0。

メトリクス：

レート/レイテンシィ'issue/convert/revoke'、 error-rate （business/4xx/5xx）、 'IDEMPOTENCY_MISMATCH'。
Vager変換、平均'time-to-complete'、割合overdue。
プロモーションコスト：'promo_cost'（マイナー）と'promo_roi'コホート上。
反乱用：最大ベット/勝利によって拒否されるベロシティトリガー。

トラッキング：チェーン上のOpenTelemetry 'trigger→grant→wallet。クレジット→進捗状況。update→convert'。

10） RGS/ゲームとの統合

フリースピン/フリーベットクーポン-'entilements' API経由：トークンの発行、ランタイムでのスクラップ、使用によるテレメトリー。

マックスベット/ウィン-ベットのルール。ベットを許可します。settle'；return codes 'BONUS_RULE_VIOLATION'。

貢献-ベットレベルでのスキーム。settled' （'game_type/provider_id'による）、スキーマバージョン。

11） DWH/BIおよびレポート

アウトボックスイベント→レイク（ブロンズ）→シルバー（デダップ、SCD2）→ゴールドショーケース：

'fact_bonus_grants'、 'fact_wager_progress'、 'fact_bonus_cost'、 'fact_promo_roi'。
SLA鮮度：シルバー≤ 15分、ゴールド≤ 30〜60分。
パネル：オファー/セグメントによる変換、完了までの時間、ゲームによる貢献、虐待事件。

12）安全性と居住

mTLS+OAuth2 CC；スコープ'-'promo： issue'、'promo： convert'、'promo： revoke'。

キー/トークン-ブランド/地域ごと、短命；Vault/HSMの秘密。

PII分離：'player_id'-エイリアス；「ブランド/地域」のRLS。

レート制限と発行クォータ；リトレイ嵐からの保護。

13）チェックリスト

プラットフォーム/オペレーター

すべての通貨取引は「Idempotency-Key」でウォレットを通過します。
規則/適格性はバージョン管理されています。移行上のイベントの「二重文字」。
貢献スキームは一元化され、テストでカバーされます。
速度と不正防止が有効になっています。「4つの目」の大和。
Outbox/CDC、 DLQ、マネージドリプレイのボーナス。'.
SLOダッシュボード、OpenTelemetry、 WORM監査。
ROIとコンプライアンス（RG/AML）のためのDWHストアフロント。

統合（RGS/ウォレット/CRM）

最高の賭け/勝利を点検すること；ビジネスエラーコードを返します。
'trace_id'と'idempotency_key'を投げます。
デッドアップトリガーと配信保証（Webhook署名済み）。

14）赤旗（アンチパターン）

ボーナスを「手動で」直接バランスに充電し、ウォレットをバイパスします。

idempotency→double grants/conversionsの欠如。

賭け金は'bet。 placed'によって考慮され、'bet。 settled'の結果に従ってではありません。

貢献スキームがないか、プロバイダのコードに「保護」されています。

競合するオファーは同時にアクティブ化されます。

velocity/anti-fraudとWORM監査はありません。

「ボーナス」'eventsはoutbox/CDCをバイパスして投稿されます。

プロモーションメトリックはLedger/BIに追加されません（ROIショーケースはありません）。

15）ボトムライン

信頼性の高いバックエンドプロモーションは、契約と不変量であり「、バランスを追加」ではありません。"ルールをお金から分離し、実際の結果に応じて進捗を考慮し、独自性と観察可能性を保証し、虐待から保護し、コンプライアンスを確実にします。このようなコアで、マーケティングはすぐに動き、プレーヤーは正直な状態を見て、財政と規制当局は、各オファーのコストと効果の正確な画像を取得します。