Hiro Live-Ops API Reference¶

Complete API reference for the Hiro module providing server-authoritative metagame systems via Nakama RPCs.

IVXHiroCoordinator¶

Singleton entry point that creates, initializes, and provides access to all 33 Hiro sub-systems.

Properties¶

Methods¶

InitializeSystems¶

public void InitializeSystems(IClient client, ISession session)

Creates all 33 system instances and injects the shared RPC client. Call once after Nakama authentication.

Parameters: - client - Nakama IClient - session - Authenticated Nakama ISession

Example:

IVXHiroCoordinator.Instance.InitializeSystems(nakamaClient, nakamaSession);

RefreshSession¶

public void RefreshSession(ISession newSession)

Propagates a refreshed Nakama session to all systems after token renewal.

Parameters: - newSession - New authenticated ISession

Events¶

IVXHiroRpcClient¶

Low-level RPC wrapper around IClient.RpcAsync with typed JSON serialization and error handling.

Properties¶

Methods¶

CallAsync¶

public async Task<HiroRpcResponse<T>> CallAsync<T>(string rpcId, object payload = null)

Typed RPC call with automatic serialization and deserialization.

Parameters: - rpcId - Server RPC identifier - payload - Request payload (serialized to JSON)

Returns: HiroRpcResponse<T> containing success, data, and error

Example:

var response = await rpcClient.CallAsync<IVXSpinWheelResult>("hiro_spin_wheel_spin", new { spinType = "free" });
if (response.success)
    ShowResult(response.data);

CallVoidAsync¶

public async Task<bool> CallVoidAsync(string rpcId, object payload = null)

Fire-and-forget RPC returning success status.

Parameters: - rpcId - Server RPC identifier - payload - Request payload (optional)

Returns: bool indicating success

UpdateSession¶

public void UpdateSession(ISession session)

Swaps the session after token refresh.

Parameters: - session - New authenticated session

IVXSpinWheelSystem¶

Server-authoritative lucky wheel with free, ad-gated, and currency spins.

Methods¶

GetAsync¶

public async Task<IVXSpinWheelConfig> GetAsync(string wheelId = null)

Fetches wheel configuration including segments, free spin counts, and costs.

Parameters: - wheelId - Wheel identifier (optional, uses default)

Returns: IVXSpinWheelConfig

SpinAsync¶

public async Task<IVXSpinWheelResult> SpinAsync(string spinType, string wheelId = null)

Executes a spin and receives the server-determined winning segment.

Parameters: - spinType - "free", "ad", or "currency" - wheelId - Wheel identifier (optional)

Returns: IVXSpinWheelResult

Example:

var result = await IVXHiroCoordinator.Instance.SpinWheel.SpinAsync("free");
if (result != null)
    ShowRewardPopup(result.reward);

IVXStreaksSystem¶

Daily engagement streaks with configurable milestone rewards.

Methods¶

GetAsync¶

public async Task<IVXStreaksGetResponse> GetAsync(string gameId = null)

Fetches all streaks with current and best counts.

Returns: IVXStreaksGetResponse

UpdateAsync¶

public async Task<IVXStreak> UpdateAsync(string streakId, string gameId = null)

Increments or maintains a streak.

Parameters: - streakId - Streak identifier (e.g. "daily_login")

Returns: Updated IVXStreak

ClaimMilestoneAsync¶

public async Task<IVXStreakClaimResponse> ClaimMilestoneAsync(string streakId, int milestone, string gameId = null)

Claims a milestone reward for a streak.

Parameters: - streakId - Streak identifier - milestone - Milestone day number

Returns: IVXStreakClaimResponse

IVXRetentionSystem¶

Tracks session depth, churn risk, onboarding progress, and comeback bonuses.

Methods¶

GetAsync¶

public async Task<IVXRetentionState> GetAsync()

Fetches the full retention state for the player.

Returns: IVXRetentionState

HeartbeatAsync¶

public async Task<IVXRetentionHeartbeatResponse> HeartbeatAsync()

Sends a session heartbeat; may return time-gated rewards.

Returns: IVXRetentionHeartbeatResponse

Example:

var heartbeat = await IVXHiroCoordinator.Instance.Retention.HeartbeatAsync();
if (heartbeat?.reward != null)
    ShowRewardPopup(heartbeat.reward);

CompleteOnboardingStepAsync¶

public async Task<IVXRetentionState> CompleteOnboardingStepAsync(int step)

Advances onboarding and awards step rewards.

Parameters: - step - Onboarding step index

Returns: Updated IVXRetentionState

ClaimComebackBonusAsync¶

public async Task<IVXRetentionHeartbeatResponse> ClaimComebackBonusAsync()

Claims the absence bonus if the player is eligible.

Returns: IVXRetentionHeartbeatResponse

IVXStreakShieldSystem¶

Consumable shields that protect daily streaks from breaking.

Methods¶

GetAsync¶

public async Task<IVXStreakShieldState> GetAsync()

Returns shield count, active status, and expiry.

ActivateAsync¶

public async Task<IVXStreakShieldActivateResponse> ActivateAsync()

Consumes one shield to protect the current streak.

ReplenishAsync¶

public async Task<IVXStreakShieldReplenishResponse> ReplenishAsync(string source, string receiptOrId = null)

Adds shields via "ad", "iap", or "currency".

Parameters: - source - Replenish source - receiptOrId - Receipt data or item ID (optional)

IVXSessionBoosterSystem¶

Time-limited multiplier bonuses that incentivize longer play sessions.

Methods¶

GetAsync¶

public async Task<IVXSessionBoosterState> GetAsync()

Returns active and available boosters.

ActivateAsync¶

public async Task<IVXSessionBoosterActivateResponse> ActivateAsync(string boosterId, string source = null)

Activates a booster from "inventory", "ad", or "iap".

Parameters: - boosterId - Booster identifier - source - Activation source (optional)

ClaimFreeAsync¶

public async Task<IVXSessionBoosterActivateResponse> ClaimFreeAsync()

Claims the next free time-gated booster.

IVXAppointmentSystem¶

Scheduled reward windows that create habitual return behavior.

Methods¶

GetAsync¶

public async Task<IVXAppointmentState> GetAsync()

Returns all appointments (active, upcoming, expired).

ClaimAsync¶

public async Task<IVXAppointmentClaimResponse> ClaimAsync(string appointmentId)

Claims a reward within the active window.

Parameters: - appointmentId - Appointment identifier

IVXLimitedDailyContentSystem¶

Rotating daily content slots with server-controlled reset cadence.

Methods¶

GetAsync¶

public async Task<IVXDailyContentState> GetAsync()

Returns all slots with claimed and locked states.

ClaimAsync¶

public async Task<IVXDailyContentClaimResponse> ClaimAsync(string slotId, string actionPayload = null)

Claims a slot, optionally passing proof-of-action.

Parameters: - slotId - Content slot identifier - actionPayload - Proof-of-action JSON (optional)

IVXIAPTriggerSystem¶

Context-aware purchase offer triggers based on player behavior signals.

Methods¶

EvaluateAsync¶

public async Task<IVXIAPTriggerEvalResponse> EvaluateAsync(string context, string contextValue = null)

Evaluates context and returns triggered offers.

Parameters: - context - Context type ("post_game", "store_visit", "low_currency", "win_streak", "level_up") - contextValue - Optional context value

Returns: IVXIAPTriggerEvalResponse

DismissAsync¶

public async Task<IVXIAPTriggerDismissResponse> DismissAsync(string triggerId)

Records offer dismissal and updates cooldown timers.

RecordConversionAsync¶

public async Task<bool> RecordConversionAsync(string triggerId, string receipt)

Records a successful IAP conversion with receipt validation.

Parameters: - triggerId - Trigger identifier - receipt - IAP receipt data

Returns: bool indicating success

IVXSmartAdTimerSystem¶

Manages interstitial cooldowns, rewarded ad caps, and banner eligibility.

Methods¶

GetAsync¶

public async Task<IVXSmartAdTimerState> GetAsync()

Returns cooldowns, daily caps, and banner status.

CanShowAsync¶

public async Task<IVXSmartAdTimerState> CanShowAsync(string adType)

Checks if an ad type can be shown now.

Parameters: - adType - "interstitial", "rewarded", or "banner"

RecordImpressionAsync¶

public async Task<IVXSmartAdTimerRecordResponse> RecordImpressionAsync(string adType, string placementId = null)

Records an ad impression; returns associated reward for rewarded ads.

Parameters: - adType - Ad type - placementId - Placement identifier (optional)

IVXAdRevenueOptimizerSystem¶

Per-segment placement configurations with remote-configurable settings.

Methods¶

GetConfigAsync¶

public async Task<IVXAdRevenueConfig> GetConfigAsync()

Returns personalized ad placement config for the player.

RecordImpressionAsync¶

public async Task<IVXAdImpressionResponse> RecordImpressionAsync(string placementId, string adNetwork = null, float? revenue = null)

Records an impression with optional revenue attribution.

Parameters: - placementId - Placement identifier - adNetwork - Ad network name (optional) - revenue - Revenue amount (optional)

IVXOfferwallSystem¶

Server-authoritative offerwall integration with reward validation and deduplication.

Methods¶

GetAsync¶

public async Task<IVXOfferwallState> GetAsync()

Returns available, pending, and completed offers.

CompleteOfferAsync¶

public async Task<IVXOfferwallCompleteResponse> CompleteOfferAsync(string offerId, string provider, string transactionId)

Records offer completion from a provider callback.

Parameters: - offerId - Offer identifier - provider - Provider name (e.g. "tapjoy") - transactionId - Provider transaction ID

ClaimPendingAsync¶

public async Task<IVXOfferwallCompleteResponse> ClaimPendingAsync()

Credits pending offerwall rewards to the player wallet.

IVXSocialPressureSystem¶

Social proof feeds and online counters.

Methods¶

GetAsync¶

public async Task<IVXSocialPressureState> GetAsync()

Returns social pressure data including friends online count and activity feeds.

IVXFriendQuestSystem¶

Cooperative quests between friends with shared progress tracking.

Methods¶

GetAsync¶

public async Task<IVXFriendQuestState> GetAsync()

Returns active, available, and completed quests.

AcceptAsync¶

public async Task<IVXFriendQuestAcceptResponse> AcceptAsync(string questId, string partnerId)

Accepts a quest with a friend (both must accept).

Parameters: - questId - Quest identifier - partnerId - Friend's user ID

ReportProgressAsync¶

public async Task<IVXFriendQuestProgressResponse> ReportProgressAsync(string questId, int amount)

Reports progress; server aggregates both players.

Parameters: - questId - Quest identifier - amount - Progress increment

IVXFriendStreakSystem¶

Bilateral daily interaction streaks where both friends contribute each day.

Methods¶

GetAsync¶

public async Task<IVXFriendStreakState> GetAsync()

Returns all friend streaks for the player.

InteractAsync¶

public async Task<IVXFriendStreakInteractResponse> InteractAsync(string friendId)

Records a daily interaction to maintain or advance the streak.

Parameters: - friendId - Friend's user ID

ClaimMilestoneAsync¶

public async Task<IVXFriendStreakInteractResponse> ClaimMilestoneAsync(string streakId, int day)

Claims a milestone reward (e.g. day 3, 7, 14, 30).

Parameters: - streakId - Streak identifier - day - Milestone day number

IVXFriendBattleSystem¶

Asynchronous 1v1 challenges with optional wagers and server-validated scoring.

Methods¶

GetAsync¶

public async Task<IVXFriendBattleState> GetAsync()

Returns pending, active, and recent battles.

SendChallengeAsync¶

public async Task<IVXFriendBattleSendResponse> SendChallengeAsync(string friendId, string gameMode, int? score = null)

Sends a challenge to a friend.

Parameters: - friendId - Friend's user ID - gameMode - Game mode identifier - score - Optional initial score (if challenger plays first)

AcceptChallengeAsync¶

public async Task<IVXFriendBattleSendResponse> AcceptChallengeAsync(string challengeId)

Accepts a pending challenge.

Parameters: - challengeId - Challenge identifier

SubmitScoreAsync¶

public async Task<IVXFriendBattleSubmitResponse> SubmitScoreAsync(string challengeId, int score)

Submits a score; the winner is determined when both players submit.

Parameters: - challengeId - Challenge identifier - score - Player's score

Data Models¶

HiroRpcResponse¶

IVXReward¶

Shared reward container used across all systems.

IVXSpinWheelConfig¶

IVXSpinWheelSegment¶

IVXStreak¶

IVXRetentionState¶

IVXIAPTrigger¶

IVXSmartAdTimerState¶

IVXFriendQuest¶

IVXFriendStreak¶

IVXFriendBattleChallenge¶

See Also¶

• Hiro Module Guide
• Backend Module
• Social Module
• Monetization Module