# Server event reference

**URL:** https://heroiclabs.com/docs/hiro/concepts/analytics/event-reference/
**Summary:** The complete list of analytics event names Hiro server systems emit, with the value and metadata each one carries.
**Keywords:** publisher events, event names, analytics events, server events, PublisherEvent, event metadata
**Categories:** hiro, publishers, reference

---


# Hiro server event reference

Hiro's systems emit an analytics event whenever something notable happens in your game, like currency being granted or an achievement claimed. This guide lists every event along with what it puts in its `Value` and `Metadata` fields.

To see the exact shape of each event object, refer to [events_satori.go](https://github.com/heroiclabs/hiro/blob/main/events_satori.go).

{{< note "important" "Events are opt-in" >}}
Events are only sent for systems you opt into when you construct `SatoriPersonalizer`. For example, `SatoriPersonalizerPublishEconomyEvents()` enables the economy events, and `SatoriPersonalizerPublishAllEvents()` enables every event. See [Publishers](../../publishers/#satoripersonalizer).
{{< /note >}}

## Currency, item, and energy events

| Event name              | Value           | Metadata                                                        |
| ----------------------- | --------------- | --------------------------------------------------------------- |
| `currencyGranted`       | Amount granted  | `currencyId`, `source`                                          |
| `currencySpent`         | Amount spent    | `currencyId`, `source`                                          |
| `itemsGranted`          | Amount granted  | `itemId`, `source`                                              |
| `itemSpent`             | Amount spent    | `itemId`, `source`                                              |
| `itemsConsumed`         | Amount consumed | `itemId`                                                        |
| `itemUpdated`           | Not set         | `itemId`, `stringProperties`, `numericProperties`               |
| `energyGranted`         | Amount granted  | `energyId`, `source`                                            |
| `energySpent`           | Amount spent    | `energyId`                                                      |
| `energyModifierGranted` | Modifier value  | `energyModifierId`, `operator`, `durationSec`, `source`         |
| `rewardModifierGranted` | Modifier value  | `rewardModifierId`, `type`, `operator`, `durationSec`, `source` |

See: [Economy](../../economy/), [Inventory](../../inventory/), and [Energy](../../energy/).

## Purchase and ad events

| Event name             | Value               | Metadata                                        |
| ---------------------- | ------------------- | ----------------------------------------------- |
| `purchaseIntent`       | Not set             | `storeItemId`, `storeType`                      |
| `purchaseCompleted`    | Amount in USD cents | `id`, `test`, `currency`, `amount`, `storeType` |
| `adPlacementStarted`   | Not set             | `placementId`                                   |
| `adPlacementSucceeded` | Not set             | `placementId`, `maxRetries`                     |
| `adPlacementFailed`    | Not set             | `placementId`                                   |

See: [Virtual store](../../economy/virtual-store/) and [Rewarded video](../../economy/rewarded-video/).

## Achievement events

| Event name               | Value          | Metadata                  |
| ------------------------ | -------------- | ------------------------- |
| `achievementUpdated`     | Progress count | `achievementId`           |
| `achievementClaimed`     | Not set        | `achievementId`           |
| `teamAchievementClaimed` | Not set        | `teamId`, `achievementId` |

See: [Achievements](../../achievements/).

## Progression events

| Event name             | Value         | Metadata                   |
| ---------------------- | ------------- | -------------------------- |
| `progressionPurchased` | Not set       | `progressionId`            |
| `progressionUpdated`   | Current count | `progressionId`, `countId` |
| `progressionReset`     | Not set       | `progressionId`            |

See: [Progression](../../progression/).

## Stat events

| Event name    | Value        | Metadata           |
| ------------- | ------------ | ------------------ |
| `statUpdated` | Update value | `name`, `operator` |

See: [Stats](../../stats/).

## Tutorial events

| Event name              | Value       | Metadata     |
| ----------------------- | ----------- | ------------ |
| `tutorialAccepted`      | Not set     | `tutorialId` |
| `tutorialDeclined`      | Not set     | `tutorialId` |
| `tutorialStarted`       | Step number | `tutorialId` |
| `tutorialStepCompleted` | Step number | `tutorialId` |
| `tutorialCompleted`     | Step number | `tutorialId` |
| `tutorialAbandoned`     | Step number | `tutorialId` |
| `tutorialReset`         | Not set     | `tutorialId` |

See: [Tutorials](../../tutorials/).

## Donation events

| Event name          | Value   | Metadata                    |
| ------------------- | ------- | --------------------------- |
| `donationRequested` | Not set | `donationId`                |
| `donationGiven`     | Not set | `donationId`, `recipientId` |
| `donationClaimed`   | Not set | `donationId`                |

See: [Donations](../../economy/donations/).

## Team events

| Event name          | Value             | Metadata                                                    |
| ------------------- | ----------------- | ----------------------------------------------------------- |
| `teamCreated`       | Maximum team size | `teamId`, `open`                                            |
| `teamItemsGranted`  | Amount granted    | `teamId`, `itemId`, `source`                                |
| `teamItemsConsumed` | Amount consumed   | `itemId`, `teamId`                                          |
| `teamItemUpdated`   | Not set           | `teamId`, `itemId`, `stringProperties`, `numericProperties` |

See: [Teams](../../teams/).

## Event leaderboard events

| Event name                    | Value      | Metadata                                   |
| ----------------------------- | ---------- | ------------------------------------------ |
| `eventLeaderboardUpdated`     | Main score | `eventLeaderboardId`, `subscore`           |
| `eventLeaderboardRolled`      | Not set    | `eventLeaderboardId`                       |
| `eventLeaderboardClaimed`     | Not set    | `eventLeaderboardId`                       |
| `teamEventLeaderboardUpdated` | Main score | `teamId`, `eventLeaderboardId`, `subscore` |
| `teamEventLeaderboardRolled`  | Not set    | `teamId`, `eventLeaderboardId`             |
| `teamEventLeaderboardClaimed` | Not set    | `teamId`, `eventLeaderboardId`             |

See: [Event leaderboards](../../event-leaderboards/).

## Unlockable events

| Event name                  | Value                    | Metadata                     |
| --------------------------- | ------------------------ | ---------------------------- |
| `unlockableCreated`         | Not set                  | `unlockableId`               |
| `unlockableUnlockStarted`   | Active unlockables count | `unlockableId`, `instanceId` |
| `unlockableUnlockPurchased` | Not set                  | `unlockableId`, `instanceId` |
| `unlockableSlotPurchased`   | Active slots count       | None                         |
| `unlockableClaimed`         | Not set                  | `unlockableId`, `instanceId` |

See: [Unlockables](../../unlockables/).

## Incentive events

| Event name                  | Value   | Metadata                            |
| --------------------------- | ------- | ----------------------------------- |
| `incentiveCreated`          | Not set | `incentiveId`, `code`               |
| `incentiveDeleted`          | Not set | `incentiveId`, `code`               |
| `incentiveSenderClaimed`    | Not set | `incentiveId`, `code`, `claimantId` |
| `incentiveRecipientClaimed` | Not set | `incentiveId`, `code`               |

See: [Incentives](../../incentives/).

## Challenge events

| Event name                    | Value       | Metadata                                                 |
| ----------------------------- | ----------- | -------------------------------------------------------- |
| `challengeCreated`            | Not set     | `challengeId`, `templateId`, `isOpen`, `maxSize`         |
| `challengeInvitationSent`     | Not set     | `challengeId`, `inviteeId`                               |
| `challengeInvitationAccepted` | Not set     | `challengeId`                                            |
| `challengeJoined`             | Not set     | `challengeId`                                            |
| `challengeUpdated`            | New score   | `challengeId`, `score`, `subscore`, `oldRank`, `newRank` |
| `challengeClaimed`            | Final score | `challengeId`, `score`, `subscore`, `rank`               |
| `challengeLeft`               | Not set     | `challengeId`                                            |

See: [Challenges](../../challenges/).

## Auction events

| Event name            | Value   | Metadata                                            |
| --------------------- | ------- | --------------------------------------------------- |
| `auctionCreated`      | Not set | `auctionId`, `templateId`, `conditionId`, `itemIds` |
| `auctionCancelled`    | Not set | `auctionId`                                         |
| `auctionBid`          | Not set | `auctionId`                                         |
| `auctionClaimCreated` | Not set | `auctionId`                                         |
| `auctionClaimBid`     | Not set | `auctionId`                                         |

See: [Auctions](../../auctions/).

## Gotchas

- Team variants of a few events reuse their base name. `achievementUpdated` and `statUpdated` are emitted for both individual players and teams; the team version adds a `teamId` metadata key. Match on the base name to catch both.
- `purchaseCompleted` uses the metadata key `id` rather than `storeItemId` for backwards compatibility.
- `unlockableSlotPurchased` is the only event with no metadata.
- The Streaks system has a publish option but currently emits no events.
- `source` metadata values (for example on `currencyGranted`) explain why a grant or spend happened, such as a reward or a purchase. They are separate from the event names above.

## See also

- [Publishers](../../publishers/)
- [About analytics in Hiro](../)
- [Understand events (Satori)](../../../../satori/concepts/performance-monitoring/understand-events/)