Special step for implementing an API hook on IncrementUserStats

Overview

When you add an API hook to the IncrementUserStats API, the hook is actually tied to the shared PlayerStatistics.UPDATE operation, which is used by both IncrementUserStats and IncrementExperiencePoints. Even though the Portal only lets you configure the hook on IncrementUserStats, the underlying server endpoint is the same, so the hook runs for both API calls. This could cause errors when IncrementExperiencePoints triggers the same hook unexpectedly.

Root cause and impact

The Java service routes both incrementExperiencePoints and incrementUserStats through route(SERVICE_NAME, Operations.UPDATE.name(), serviceDataMap), so any hook on PlayerStatistics.UPDATE is invoked by both APIs.
Several apps already rely on PlayerStatistics.UPDATE pre/post hooks for stats, XP, or blocking logic, so splitting these into separate operations now could change existing behaviour in production apps.

That being said, to increment a user’s experience points (XP), invoke the IncrementUserStats method with xp_points specified as an input parameter. This will update the user’s XP value accordingly.

Request payload differences

The PlayerStatistics.UPDATE endpoint accepts flexible data, but each API expects a different field in the request body. For incrementExperiencePoints, the parameter must be xp_points, while for incrementUserStats it must be statistics.

Recommended pre-hook checks

To safely use a pre-hook on incrementUserStats, ensure the script validates which payload is present before proceeding. This avoids errors when IncrementExperiencePoints triggers the same hook unexpectedly.

For statistics: first null-check message.statistics, then run the rest of your logic.
For xp_points: first null-check message.xp_points, then run the rest of your logic.

This prevents situations where you call incrementExperiencePoints, assume there is no hook, but still get errors like Prehook script error: the variable you passed to incrementExperiencePoints not defined.

Post-hook considerations

For post-hooks on incrementUserStats, if the script relies on the original request parameters, always check both callingMessage.statistics and callingMessage.xp_points and use the appropriate one. Also ensure you reference the correct result data for each API so that stats and XP updates are handled as intended.