シーズンパスをゲームに統合する

Last updated on October 23, 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.

Unreal
Unity

FString Language = TEXT("en");

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

var seasonPass = AccelByteSDK.GetClientRegistry().GetApi().GetSeasonPass();

string language = "en";

seasonPass.GetCurrentSeason(language, result =>
{
    if (result.IsError)
    {
        // Do something when failed
        Debug.Log($"Error {result.Error.Code}: {result.Error.Message}")
        return;
    }
    
    // Do something when successful
});

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.

Unreal
Unity

FString Language = TEXT("en");

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

var seasonPass = AccelByteSDK.GetClientRegistry().GetApi().GetSeasonPass();

seasonPass.GetCurrentUserSeason(result =>
{
    if (result.IsError)
    {
        // Do something when failed
        Debug.Log($"Error {result.Error.Code}: {result.Error.Message}")
        return;
    }
    
    // Do something when successful
});

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.

Unreal
Unity

int32 EXP = 300;
FString UserId = "TargetUserId";

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

var seasonPass = AccelByteSDK.GetClientRegistry().GetApi().GetSeasonPass();

int exp = 300;
string userId = "TargetUserId";

seasonPass.GrantExpToUser(userId, exp, result =>
{
    if (result.IsError)
    {
        // Do something when failed
        Debug.Log($"Error {result.Error.Code}: {result.Error.Message}")
        return;
    }
    
    // Do something when successful
});

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.

Unreal
Unity

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 successful
    }),
    FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something when failed
    })
);

var seasonPass = AccelByteSDK.GetClientRegistry().GetApi().GetSeasonPass();

ItemCriteria itemCriteria = new ItemCriteria
{
    language = "en",
    region = "US",
    itemType = ItemType.SEASON,
    categoryPath = "/seasonpass",
};

seasonPass.GetItemsByCriteria(itemCriteria, result =>
{
    if (result.IsError)
    {
        // Do something when failed
        Debug.Log($"Error {result.Error.Code}: {result.Error.Message}")
        return;
    }
    
    // Do something when successful
});

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

Unreal
Unity

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)
    {
        // So something when successful
    }),
    FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something when failed
    })
);

var seasonPass = AccelByteSDK.GetClientRegistry().GetApi().GetSeasonPass();

OrderRequest orderTier = new OrderRequest
{
    currencyCode = "CurrencyCode",
    discountedPrice = 100,
    itemId = "ItemId",
    price = 100,
    quantity = 1,
    returnUrl = "https://example.com",
    region = "US",
    language = "en"
};

seasonPass.CreateOrder(orderTier, result =>
{
    if (result.IsError)
    {
        // Do something when failed
        Debug.Log($"Error {result.Error.Code}: {result.Error.Message}")
        return;
    }
    
    // Do something when successful
});

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.

Unreal
Unity

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 successful
    }),
    FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something when failed
    })
);

var seasonPass = AccelByteSDK.GetClientRegistry().GetApi().GetSeasonPass();

ItemCriteria itemCriteria = new ItemCriteria
{
    language = "en",
    region = "US",
    itemType = ItemType.SEASON,
    categoryPath = "/seasonpass",
};

seasonPass.GetItemsByCriteria(itemCriteria, result =>
{
    if (result.IsError)
    {
        // Do something when failed
        Debug.Log($"Error {result.Error.Code}: {result.Error.Message}")
        return;
    }
    
    // Do something when successful
});

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

Unreal
Unity

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 successful
    }),
    FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something when failed
    })
);

var seasonPass = AccelByteSDK.GetClientRegistry().GetApi().GetSeasonPass();

OrderRequest orderPass = new OrderRequest
{
    currencyCode = "CurrencyCode",
    discountedPrice = 100,
    itemId = "ItemId",
    price = 100,
    quantity = 1,
    returnUrl = "https://example.com",
    region = "US",
    language = "en"
};

seasonPass.CreateOrder(orderPass, result =>
{
    if (result.IsError)
    {
        // Do something when failed
        Debug.Log($"Error {result.Error.Code}: {result.Error.Message}")
        return;
    }
    
    // Do something when successful
});

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.

Unreal
Unity

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 successful
    }),
    FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        // Do something when failed
    })
);

var seasonPass = AccelByteSDK.GetClientRegistry().GetApi().GetSeasonPass();

SeasonClaimRewardRequest claimRewardRequest = new SeasonClaimRewardRequest
{
    passCode = "PremiumPassCode",
    tierIndex = 0,
    rewardCode = "RewardCode",
};

seasonPass.ClaimRewards(claimRewardRequest, result =>
{
    if (result.IsError)
    {
        // Do something when failed
        Debug.Log($"Error {result.Error.Code}: {result.Error.Message}");
        return;
    }
    
    // Do something when successful
});

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.

Unreal
Unity

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

var seasonPass = AccelByteSDK.GetClientRegistry().GetApi().GetSeasonPass();

seasonPass.BulkClaimRewards(result =>
{
    if (result.IsError)
    {
        // Do something when failed
        Debug.Log($"Error {result.Error.Code}: {result.Error.Message}")
        return;
    }
    
    // Do something when successful
});

Overview​

Goals​

Prerequisites​

Retrieve the current season pass​

Retrieve the player's current season pass progress​

Grant XP to the player using the Server API​

Level up in tiers​

Unlock a premium pass​

Claim a reward​

Claim all rewards​

On this page