Economy #

Read more about the Economy system in Hiro here.

Functions #

RewardCreate #

Prepare a new reward configuration to be filled in and used later.

1

rewardConfig := systems.GetEconomySystem().RewardCreate()

RewardConvert #

Transform a wire representation of a reward into an equivalent configuration representation.

1
2
3
4
5
6
7
8
9

contents := &hiro.AvailableRewards{
  Guaranteed:     nil,
  Weighted:       nil,
  MaxRolls:       0,
  TotalWeight:    0,
  MaxRepeatRolls: 0,
}

rewardConfig := systems.GetEconomySystem().RewardConvert(contents)

RewardRoll #

Take a reward configuration and roll an actual reward from it, applying all appropriate rules.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

userId := "userId"
rewardConfig := &hiro.EconomyConfigReward{
  Guaranteed:     nil,
  Weighted:       nil,
  MaxRolls:       0,
  MaxRepeatRolls: 0,
  TotalWeight:    0,
}

reward, err := systems.GetEconomySystem().RewardRoll(ctx, logger, nk, userId, rewardConfig)
if err != nil {
  return err
}

RewardGrant #

Update a user’s economy, inventory, and/or energy models with the contents of a rolled reward.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

userId := "userId"
currencies := map[string]int64{"coins": 10}
items := map[string]int64{"sword": 1}
modifiers := []*hiro.RewardModifier{{}}
walletMetadata := map[string]interface{}{}

updatedWallet, rewardModifiers, timestamp, err := systems.GetEconomySystem().Grant(ctx, logger, nk, userId, currencies, items, modifiers, walletMetadata)
if err != nil {
  return err
}

DonationClaim #

Claim donation rewards for a user for the given donation.

1
2
3
4
5
6
7

userId := "userId"
donationIds := []string{"donationId_001", "donationId_002", "donationId_003"}

donationsList, err := systems.GetEconomySystem().DonationClaim(ctx, logger, nk, userId, donationIds)
if err != nil {
  return err
}

DonationGet #

Get all donations for the given list of users.

1
2
3
4
5
6

userIds := []string{"userId_001", "userId_002", "userId_003"}

donationsList, err := systems.GetEconomySystem().DonationGet(ctx, logger, nk, userIds)
if err != nil {
  return err
}

DonationGive #

Contribute to a particular donation for a user.

1
2
3
4
5
6
7
8

userId := "userId"
donationId := "donationId"
fromUserId := "fromUserId"

updatedWallet, updatedInventory, rewardModifiers, contributorReward, timestamp, err := systems.GetEconomySystem().DonationGive(ctx, logger, nk, userId, donationId, fromUserId)
if err != nil {
  return err
}

DonationRequest #

Create a donation request for a given donation and user.

1
2
3
4
5
6
7

userId := "userId"
donationId := "donationId"

donation, success, err := systems.GetEconomySystem().DonationRequest(ctx, logger, nk, userId, donationId)
if err != nil {
  return err
}

List #

Get the defined store items and placements within the economy system.

1
2
3
4
5
6

userId := "userId"

storeItems, placements, rewardModifiers, timestamp, err := systems.GetEconomySystem().List(ctx, logger, nk, userId)
if err != nil {
  return err
}

Grant #

Add currencies and reward modifiers to a user’s economy.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

userId := "userId"
currencies := map[string]int64{"coins": 10}
items := map[string]int64{"sword": 1}
modifiers := []*hiro.RewardModifier{{}}
walletMetadata := map[string]interface{}{}

updatedWallet, rewardModifiers, timestamp, err := systems.GetEconomySystem().Grant(ctx, logger, nk, userId, currencies, items, modifiers, walletMetadata)
if err != nil {
  return err
}

UnmarshalWallet #

Unmarshal and return an account’s wallet as a map[string]int64.

1
2
3
4
5
6

account := &api.Account{}

wallet, err := systems.GetEconomySystem().UnmarshalWallet(account)
if err != nil {
  return err
}

PurchaseIntent #

Create a purchase intent for a particular store item and user.

1
2
3
4
5
6
7
8
9

userId := "userId"
itemId := "itemId"
store := hiro.EconomyStoreType_ECONOMY_STORE_TYPE_APPLE_APPSTORE
sku := "sku"

err := systems.GetEconomySystem().PurchaseIntent(ctx, logger, nk, userId, itemId, store, sku)
if err != nil {
  return err
}

PurchaseItem #

Validate a purchase and give the user the appropriate rewards.

1
2
3
4
5
6
7
8
9

userId := "userId"
itemId := "itemId"
store := hiro.EconomyStoreType_ECONOMY_STORE_TYPE_APPLE_APPSTORE
receipt := "<receipt>"

updatedWallet, updatedInventory, reward, isSandboxPurchase, err := systems.GetEconomySystem().PurchaseItem(ctx, logger, db, nk, userId, itemId, store, receipt)
if err != nil {
  return err
}

PurchaseRestore #

Process a restore attempt for the given user, based on a set of restore receipts.

1
2
3
4
5
6
7
8

userId := "userId"
store := hiro.EconomyStoreType_ECONOMY_STORE_TYPE_APPLE_APPSTORE
receipts := []string{"<receipt_001>", "<receipt_002>"}

err := systems.GetEconomySystem().PurchaseRestore(ctx, logger, nk, userId, store, receipts)
if err != nil {
  return err
}

PlacementStatus #

Get the status of a specified placement.

1
2
3
4
5
6
7
8
9

userId := "userId"
rewardId := "rewardId"
placementId := "placementId"
retryCount := 3

placementStatus, err := systems.GetEconomySystem().PlacementStatus(ctx, logger, nk, userId, rewardId, placementId, retryCount)
if err != nil {
  return err
}

PlacementStart #

Indicate that a user has begun viewing an ad placement.

1
2
3
4
5
6
7
8

userId := "userId"
placementId := "placementId"
metadata := map[string]string{}

placementStatus, err := systems.GetEconomySystem().PlacementStart(ctx, logger, nk, userId, placementId, metadata)
if err != nil {
  return err
}

PlacementSuccess #

Indicate that a user has successfully viewed an ad placement and provide the appropriate reward.

1
2
3
4
5
6
7
8

userId := "userId"
placementId := "placementId"
rewardId := "rewardId"

reward, placementMetadata, err := systems.GetEconomySystem().PlacementSuccess(ctx, logger, nk, userId, rewardId, placementId)
if err != nil {
  return err
}

PlacementFail #

Indicate that a user has failed to successfully view an ad placement.

1
2
3
4
5
6
7
8

userId := "userId"
placementId := "placementId"
rewardId := "rewardId"

placementMetadata, err := systems.GetEconomySystem().PlacementFail(ctx, logger, nk, userId, rewardId, placementId)
if err != nil {
  return err
}

Hooks #

SetOnDonationClaimReward #

Set a custom reward function which will run after a donation’s reward is rolled.

1
2
3
4
5
6

systems.GetEconomySystem().SetOnDonationClaimReward(DonationClaimReward)

func DonationClaimReward(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, userID, sourceID string, source *hiro.EconomyConfigDonation, rewardConfig *hiro.EconomyConfigReward, reward *hiro.Reward) (*hiro.Reward, error) {
	// Modify reward or take additional actions.
	return reward, nil
}

SetOnDonationContributorReward #

Set a custom reward function which will run after a donation’s sender reward is rolled.

1
2
3
4
5
6

systems.GetEconomySystem().SetOnDonationContributorReward(OnDonationContributorReward)

func OnDonationContributorReward(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, userID, sourceID string, source *hiro.EconomyConfigDonation, rewardConfig *hiro.EconomyConfigReward, reward *hiro.Reward) (*hiro.Reward, error) {
	// Modify reward or take additional actions.
	return reward, nil
}

SetOnPlacementReward #

Set a custom reward function which will run after a placement’s reward is rolled.

1
2
3
4
5
6

systems.GetEconomySystem().SetOnPlacementReward(OnPlacementReward)

func OnPlacementReward(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, userID, sourceID string, source *hiro.EconomyPlacementInfo, rewardConfig *hiro.EconomyConfigReward, reward *hiro.Reward) (*hiro.Reward, error) {
	// Modify reward or take additional actions.
	return reward, nil
}

SetOnStoreItemReward #

Set a custom reward function which will run after store item’s reward is rolled.

1
2
3
4
5
6

systems.GetEconomySystem().SetOnStoreItemReward(OnStoreItemReward)

func OnStoreItemReward(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, userID, sourceID string, source *hiro.EconomyConfigStoreItem, rewardConfig *hiro.EconomyConfigReward, reward *hiro.Reward) (*hiro.Reward, error) {
	// Modify reward or take additional actions.
	return reward, nil
}