Skip to main content

Integrate season passes into your game

Last updated on February 12, 2024

Overview

This document will guide you using AccelByte Gaming Services (AGS) to integrate a Season Pass service into your game using the Client SDK.

Goals

After finishing this guide, you should be able to understand:

  • How to retrieve current season pass information from the game client.
  • How to retrieve the user's season progression from the game client.
  • How to grant XP and level up tiers from the game client.
  • How to claim season pass rewards from the game client.

Prerequisites

You will need access to:

  • The AGS Admin Portal.
    • The AccelByte Unreal SDK or AccelByte Unity SDK, including the required permissions:
      • Client ID
      • Client Secret
  • The AccelByte Season Pass API documentation for further reference.

You will also need to make sure you have configured the season pass via the Admin Portal to integrate the season pass into your game.

Retrieve the current season pass

The game client can query the current active season pass to return information, such as the tier progression information which includes the required XP and reward passes for each tier.

FString Language = TEXT(“en”);

AccelByte::FRegistry::SeasonPass.GetCurrentSeason(
Language,
THandler<FAccelByteModelsSeasonInfo>::CreateLambda([&](const FAccelByteModelsSeasonInfo& Result)
{
/* do something when succeed */
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
/* do something when failed */
})
);

Retrieve the player’s current season pass progress

The game client can query a player’s season data to show the player their season progress and claimable rewards.

FString Language = TEXT(“en”);

AccelByte::FRegistry::SeasonPass.GetCurrentUserSeason(
THandler<FAccelByteModelsUserSeasonInfo>::CreateLambda([](const FAccelByteModelsUserSeasonInfo& Result)
{
/* do something when succeed*/
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
/* do something when failed */
})
);

Grant XP to the player using the Server API

The game server can grant experience points (XP) to the player by using the Server API to help players progress through the season. For example, the XP can be granted once the player finishes tasks or challenges during the season.

int32 EXP = 300;
FString UserId = “TargetUserId”;

AccelByte::FRegistry::ServerSeasonPass.GrantExpToUser(
UserId, EXP,
THandler<FAccelByteModelsUserSeasonInfoWithoutReward>::CreateLambda(
[](const FAccelByteModelsUserSeasonInfoWithoutReward& Result)
{
/* do something when succeeded */
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
/* do something when failed */
})
);

Level up in tiers

Players can move up tiers in two ways: either by gaining XP in season challenges or by buying access to tiers. If a player moves up a tier from gaining XP, their tier will be leveled up automatically, their XP will be reset to 0, and any remaining XP from the previous tier will be added back to the player’s XP. Players can also purchase access to advanced tiers.

Before purchasing tier access, make sure you have detailed information for the tier item. Otherwise, you will need to query the tier item from the Ecommerce service to get the details of the item.

FAccelByteModelsItemCriteria ItemCriteria;
ItemCriteria.ItemType = EAccelByteItemType::SEASON;
ItemCriteria.CategoryPath = TEXT("/seasonpass");
int32 Offset = 0;
int32 Limit = 32;

AccelByte:FRegistry::Item.GetItemsByCriteria(
ItemCriteria, Offset, Limit,
THandler<FAccelByteModelsItemPagingSlicedResult>::CreateLambda([](const FAccelByteModelsItemPagingSlicedResult& Result)
{
/* do something when succeed*/
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
/* do something when failed */
})
);

After you have the tier item information, the game client can call the CreateNewOrder function to purchase access to a tier.

FAccelByteModelsOrderCreate OrderTier;
OrderTier.CurrencyCode = TEXT(“CurrencyCode”);
OrderTier.DiscountedPrice = 100;
OrderTier.Price = 100;
OrderTier.Quantity = 1;
OrderTier.ReturnUrl = TEXT("https://example.com");
OrderTier.ItemId = TEXT(“ItemId”);
OrderTier.Region = "US";
OrderTier.Language = "en";

FRegistry::Order.CreateNewOrder(
OrderTier,
THandler<FAccelByteModelsOrderInfo>::CreateLambda([&](const FAccelByteModelsOrderInfo& Result)
{
/* do something when succeed */
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
/* do something when failed */
})
);

Unlock a premium pass

Players can purchase a premium pass to gain access to additional rewards from season events. Before purchasing the premium pass item, make sure you have detailed information for it. Otherwise, you will need to query the premium pass item to get the details of the item.

FAccelByteModelsItemCriteria ItemCriteria;
ItemCriteria.ItemType = EAccelByteItemType::SEASON;
ItemCriteria.CategoryPath = TEXT(/seasonpass”);
int32 Offset = 0;
int32 Limit = 32;

AccelByte:FRegistry::Item.GetItemsByCriteria(
ItemCriteria, Offset, Limit, THandler<FAccelByteModelsItemPagingSlicedResult>::CreateLambda(
[](const FAccelByteModelsItemPagingSlicedResult& Result)
{
/* do something when succeeded */
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
/* do something when failed */
})
);

After you have the premium pass item information, the game client can call the CreateNewOrder function to purchase the premium pass.

FAccelByteModelsOrderCreate OrderPass;
OrderTier.CurrencyCode = TEXT(“CurrencyCode”);
OrderTier.DiscountedPrice = 100;
OrderTier.Price = 100;
OrderTier.Quantity = 1;
OrderTier.ReturnUrl = TEXT("https://example.com");
OrderTier.ItemId = TEXT(“ItemId”);
OrderTier.Region = "US";
OrderTier.Language = "en";

FRegistry::Order.CreateNewOrder(
OrderPass,
THandler<FAccelByteModelsOrderInfo>::CreateLambda([&](const FAccelByteModelsOrderInfo& Result)
{
/* do something when succeed */
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
/* do something when failed */
})
);

Claim a reward

If a season wasn’t configured to grant players' earned rewards automatically, the game client needs to claim a player's reward manually. You can use the ClaimRewards function to claim a player's reward.

FString PassCode = TEXT(“PremiumPassCode”);
int32 TierIndex = 0;
FString RewardCode = TEXT(“RewardCode”);

FAccelByteModelsSeasonClaimRewardRequest ClaimRequest{
PassCode, TierIndex, RewardCode
};
AccelByte::FRegistry::SeasonPass.ClaimRewards(
ClaimRequest,
THandler<FAccelByteModelsSeasonClaimRewardResponse>::CreateLambda(
[&](const FAccelByteModelsSeasonClaimRewardResponse& Result)
{
/* do something when succeed*/
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
/* do something when failed */
})
);

Claim all rewards

If a player has multiple rewards available to claim, the game client can claim all the rewards at once. You can use BulkClaimRewards to claim multiple rewards at the same time.

AccelByte::FRegistry::SeasonPass.BulkClaimRewards(
THandler<FAccelByteModelsSeasonClaimRewardResponse>::CreateLambda(
[&](const FAccelByteModelsSeasonClaimRewardResponse& Result)
{
/* do something when succeed*/
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
/* do something when failed */
})
);