RevoSurge 文檔

繁體中文

English
简体中文

繁體中文

English
简体中文

Appearance

iGaming 事件 ​

對象： iGaming 產品的工程師、技術整合人員

iGaming 事件（igaming 預設集）涵蓋遊戲垂直領域：擴充的用戶生命週期、KYC 與帳戶狀態、資金、遊戲及獎金生命週期。

IMPORTANT

iGaming 是一個按訂閱啟用的行業預設集。你的產品必須已訂閱（由 RevoSurge 團隊啟用）後，這些事件才會被接受 — 否則它們會被拒絕為 422 EVENT_DISABLED。請參閱事件目錄與驗證。

每個事件也會攜帶基礎屬性（event、timestamp、identity.client_user_id、context.ip_address）。下方表格只列出每個事件特定的欄位。貨幣欄位（amount、bet_result_amount、…）會使用隨附的 currency 及 is_crypto 欄位進行換算。

互動式瀏覽器 ​

選擇一個事件以查看其欄位及一個可直接傳送的信封。切換「僅必填」，然後複製為 JSON 或 cURL。

POST/v3/s2s/eventsession_ended
欄位類型要求說明
eventString必填固定為 `session_ended`，必須是已登記的事件名。
timestampNumber必填UTC 紀元毫秒（13 位）。
identity.client_user_idString必填你系統中用戶的唯一 ID。identity 至少需含 client_user_id / anonymous_id 之一。
identity.click_idString建議用於歸因的廣告點擊 ID。
identity.anonymous_idString可選註冊前的匿名 ID；在 client_user_id 出現前用於 App 生命週期身份縫合。
context.ip_addressString必填終端用戶 IP（IPv4 或 IPv6）。
context.session_idString必填唯一工作階段 ID。
context.session_start_atNumber必填工作階段開始，UTC 毫秒。
context.duration_minutesNumber必填工作階段總時長（分鐘）。
context.total_wageredNumber建議工作階段內總投注額。
context.total_wonNumber建議工作階段內總贏額。
context.bet_countNumber建議工作階段內投注次數。
context.currencyString建議若上報 wagered / won 則必填。
context.is_cryptoBoolean建議加密貨幣為 true。
context.end_reasonString建議工作階段結束原因：user_logout / timeout / forced_logout / unknown。
請求信封
{
  "event": "session_ended",
  "timestamp": 1718280000000,
  "identity": {
    "client_user_id": "user_001",
    "click_id": "RS_clk_998877",
    "anonymous_id": "anon_7f3a"
  },
  "context": {
    "ip_address": "203.0.113.1",
    "session_id": "sess_001",
    "session_start_at": 1718276400000,
    "duration_minutes": 60,
    "total_wagered": 250,
    "total_won": 180,
    "bet_count": 42,
    "currency": "USD",
    "is_crypto": false,
    "end_reason": "user_logout"
  }
}

用戶生命週期 ​

session_ended ​

工作階段時長是一個強烈的玩家層級流失預測指標。

欄位類型要求說明
context.session_idString必填唯一工作階段 ID。
context.session_start_atNumber必填工作階段開始時間，UTC 毫秒。
context.duration_minutesNumber必填工作階段總時長（分鐘）。
context.total_wageredNumber建議工作階段內總投注額。
context.total_wonNumber建議工作階段內總贏額。
context.bet_countNumber建議工作階段內投注次數。
context.currencyString建議若上報 total_wagered / total_won 則必填。
context.is_cryptoBoolean建議加密貨幣計價為 true。
context.end_reasonString建議user_logout · timeout · forced_logout · unknown 其中之一。

vip_tier_changed ​

降級是一個強烈的流失訊號。對於初始等級，使用 direction: upgrade。

欄位類型要求說明
context.new_tierString必填當前等級（例如 gold、vip_1）。
context.previous_tierString建議本次變更前的等級。
context.directionString必填upgrade · downgrade · lateral 其中之一。
context.triggerString建議lifetime_deposits · monthly_wagering · loyalty_points · manual_admin · tier_review · other 其中之一。

驗證與授權 ​

kyc_completed ​

對於多級 KYC，每級觸發一次。

欄位類型要求說明
context.kyc_levelString必填basic · enhanced · full 其中之一。
context.jurisdictionString必填ISO 3166-1 國家代碼（例如 BR、IN、PH）。
context.verification_methodString必填id_document · video · sms_otp · address_proof · bank_verification 其中之一。
context.time_to_complete_minutesNumber建議從 register 到此事件的分鐘數。

kyc_rejected ​

kyc_completed 的對應事件；用於 KYC 漏斗／拒絕率診斷。

欄位類型要求說明
context.kyc_levelString必填basic · enhanced · full 其中之一。
context.jurisdictionString必填ISO 3166-1 國家代碼。
context.rejection_reasonString必填document_invalid · face_mismatch · sanctions_hit · underage · duplicate · document_unreadable · document_expired · name_mismatch · age_restriction · suspected_fraud · other 其中之一。
context.verification_methodString建議嘗試的驗證方法。
context.time_to_reject_minutesNumber建議從 register 到此事件的分鐘數。

account_blocked ​

將被封鎖的帳戶從 LTV / 流失模型中排除。

欄位類型要求說明
context.block_reasonString必填fraud · bonus_abuse · multi_account · self_exclusion · compliance · payment_chargeback · other 其中之一。
context.block_durationString建議permanent · temporary · under_review 其中之一。
context.expected_unblock_atNumber建議UTC 毫秒；用於臨時封鎖。

account_unblocked ​

欄位類型要求說明
context.unblock_reasonString必填建議用 review_passed · appeal_approved · cooldown_ended · manual_admin · other。（temporary_expired 仍接受但已棄用。）
context.previous_block_reasonString建議被解除的封鎖原因。

資金 ​

deposit_initiated ​

欄位類型要求說明
context.transaction_idString必填支付訂單 ID（PK；須與後續 deposit / deposit_failed 一致）。
context.amountNumber必填申請充值的金額（貨幣）。
context.currencyString必填ISO 4217（法定貨幣）或加密貨幣代號。
context.is_cryptoBoolean建議加密貨幣為 true。
context.payment_methodString建議用戶所選支付渠道，例如 card_visa · usdt_trc20 · pix。

deposit ​

欄位類型要求說明
context.transaction_idString必填唯一交易 ID（PK）。
context.amountNumber必填充值金額（貨幣）。
context.currencyString必填ISO 4217（法定貨幣）或加密貨幣代號。
context.is_cryptoBoolean建議加密貨幣為 true。
context.payment_methodString建議例如 card_visa · usdt_trc20 · pix。

deposit_failed ​

充值總嘗試次數 = deposit + deposit_failed。

欄位類型要求說明
context.transaction_idString必填嘗試 ID（PK，用於去重）。
context.attempted_amountNumber必填嘗試的充值金額（貨幣）。
context.currencyString必填ISO 4217 或加密貨幣代號。
context.payment_methodString必填嘗試的支付方式。
context.failure_reasonString必填insufficient_funds · declined_by_issuer · network_error · fraud_blocked · amount_limit · unknown 其中之一。
context.is_cryptoBoolean建議加密貨幣嘗試為 true。

withdraw ​

欄位類型要求說明
context.transaction_idString必填唯一交易 ID（PK）。
context.amountNumber必填提現金額（貨幣）。
context.currencyString必填ISO 4217 或加密貨幣代號。
context.is_cryptoBoolean建議加密貨幣為 true。

遊戲 ​

bet ​

一個單一的已結算投注事件 — 注額及其結果透過 bet_result / bet_result_amount 一起回報。

NOTE

對於 bet，context.ip_address 會降級為建議，因為投注通常從遊戲伺服器傳來，沒有終端用戶 IP。

欄位類型要求說明
context.transaction_idString必填唯一投注／票券 ID（PK）。
context.game_typeString必填規範遊戲類型 — 見下方取值。
context.game_providerString必填例如 Pragmatic Play、Evolution Gaming。
context.game_nameString建議特定遊戲名稱（例如 Sweet Bonanza）。
context.amountNumber必填總注額（貨幣）。
context.currencyString必填ISO 4217 或加密貨幣代號。
context.cash_bet_amountNumber建議注額中的現金部分（用於 NGR / 獎金濫用）。
context.bonus_bet_amountNumber建議注額中的獎金部分。
context.bet_resultString必填win · loss 其中之一。
context.bet_result_amountNumber必填淨結果 — 正數 = 贏，負數 = 輸（貨幣）。
context.ticket_typeString建議Sportsbook：single · multi · system。
context.is_liveBoolean建議Sportsbook 滾球投注。
context.is_freeBoolean建議免費投注 token（從 LTV 中排除）。
context.is_cryptoBoolean建議加密貨幣為 true。

game_type 規範值 ​

context.game_type（String，必填）會正規化為下表中的規範類型。可以發送規範鍵本身，也可以發送它對應的任意別名，兩者都會正規化為同一個規範類型。

game_type可接受的別名（Aliases）
slotslot（老虎機）· pachinko（彈珠機）
live_casinolive（真人）· gameshow（真人遊戲秀）
sportsbooksport（體育）· cockfight（鬥雞）
fishingfish（捕魚）· arcade（街機）
table_gamesbaccarat（百家樂）· blackjack（二十一點）· roulette（輪盤）· dice（骰寶）· card（紙牌）· table（桌檯）
pokerpoker（德州撲克）
lotterylottery（彩票）· bingo（賓果）· instant（即開彩／刮刮樂）
esportsesport（電競）
crashcrash · aviator（崩盤／墜機遊戲）

game_type 為受校驗的欄位——只能發送規範鍵或其所列別名，未登記的值會被拒收。

獎金生命週期 ​

四個獎金事件必須共用一個一致的 bonus_id，並按順序觸發：bonus_offered → bonus_claimed → bonus_completed → bonus_cashed_out。

bonus_offered ​

欄位類型要求說明
context.bonus_idString必填唯一獎金實例 ID（PK；在整個生命週期內保持一致）。
context.bonus_typeString必填welcome · reload · cashback · freespin · promo_code · tournament · value_voucher（優惠券發放）· promo_cash（優惠金發放）· other 其中之一。
context.bonus_value_maxNumber必填最大可授予金額。
context.currencyString必填貨幣。
context.wagering_multiplierNumber必填投注倍數（30 = 30x；0 = 無）。
context.valid_untilNumber必填UTC 毫秒，優惠到期時間。
context.delivery_channelString必填auto_grant · email · in_app · push · promo_code · sms 其中之一。
context.is_cryptoBoolean建議加密貨幣為 true。

bonus_claimed ​

對於 auto_grant，在 bonus_offered 後立即觸發。

欄位類型要求說明
context.bonus_idString必填匹配 bonus_offered（FK）。
context.bonus_value_grantedNumber必填實際授予的金額（≤ bonus_value_max）。
context.currencyString必填必須與所提供的相符。
context.wagering_requirementNumber必填= bonus_value_granted × wagering_multiplier。
context.is_cryptoBoolean建議加密貨幣為 true。

bonus_completed ​

欄位類型要求說明
context.bonus_idString必填FK。
context.total_wageredNumber必填完成時的最終投注額。
context.wagering_requirementNumber必填與領取時相同。
context.currencyString必填必須與領取時相符。
context.time_to_complete_minutesNumber必填從 bonus_claimed 起的分鐘數。
context.is_cryptoBoolean建議加密貨幣為 true。

bonus_cashed_out ​

每個 bonus_id 可能觸發多次；DataPulse 會將其加總。

欄位類型要求說明
context.bonus_idString必填FK。
context.cashout_amountNumber必填轉移到真錢錢包的金額。
context.original_bonus_valueNumber必填領取時的 bonus_value_granted。
context.currencyString必填必須與領取時相符。
context.time_to_cashout_minutesNumber必填從 bonus_claimed 起的分鐘數。
context.is_cryptoBoolean建議加密貨幣為 true。