Integrate season passes into your game

Last updated on October 24, 2024

Overview

This article walks you through how to integrate the AccelByte Gaming Services (AGS) Season Pass service into your game through the Client SDK or Extend SDK as follows:

• Retrieve current season pass information from the game client.
• Retrieve the user's season progression from the game client.
• Grant XP and level up tiers from the game client.
• Claim season pass rewards from the game client.

Prerequisites

You will need access to:

• The AGS Admin Portal.
  • The AccelByte Unreal SDK, AccelByte Unity SDK or AccelByte Extend 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

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
    })
);

Unity

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
});

Go Extend SDK

seasonService := &seasonpass.SeasonService{
    Client:          factory.NewSeasonpassClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
language := "en"
input := &season.PublicGetCurrentSeasonParams{
    Namespace: namespace,
    Language:  &language,
}
result, err := seasonService.PublicGetCurrentSeasonShort(input)

Python Extend SDK

import accelbyte_py_sdk.api.seasonpass as seasonpass_service

result, error = group_service.public_get_current_season(
    language="en",
)
if error:
    exit(error)

Java Extend SDK

final Season seasonWrapper = new Season(sdk);
String language = "en";

LocalizedSeasonInfo localizedSeasonInfo;
try {
    localizedSeasonInfo = seasonWrapper.publicGetCurrentSeason(PublicGetCurrentSeason.builder()
        .namespace("<namespace>")
        .language(language)
        .build());
} catch (HttpResponseException e) {
    // Do something when failed
    return;
}

if (localizedSeasonInfo != null)
{
    // Do something when successful
}

C# Extend SDK

var response = sdk.Seasonpass.Season.PublicGetCurrentSeasonOp
    .SetLanguage("en")
    .Execute(sdk.Namespace);
if (response != null)
{
    //do something when success
}

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

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
    })
);

Unity

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
});

Go Extend SDK

seasonService := &seasonpass.SeasonService{
    Client:          factory.NewSeasonpassClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
userId := "myuserid"
input := &season.PublicGetCurrentUserSeasonParams{
    Namespace: namespace,
    UserID:    userId,
}
result, err := seasonService.PublicGetCurrentUserSeasonShort(input)

Python Extend SDK

import accelbyte_py_sdk.api.seasonpass as seasonpass_service

result, error = group_service.public_get_current_user_season(
    user_id="********************************",
)
if error:
    exit(error)

Java Extend SDK

final Season seasonWrapper = new Season(sdk);
String userId = "YourUserId";
final ClaimableUserSeasonInfo response;
try {
    response = seasonWrapper.publicGetCurrentUserSeason(PublicGetCurrentUserSeason.builder()
        .namespace("<namespace>")
        .userId(userId)
        .build());
} catch (Exception e) {
    // Do something when failed
    return;
}

if (response == null) {
    // Null response from server
} else {
    // Do something when successful
}

C# Extend SDK

string userId = "<user-id>";

var response = sdk.Seasonpass.Season.PublicGetCurrentUserSeasonOp
    .Execute(sdk.Namespace, userId);
if (response != null)
{
    //do something when success
}

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

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
    })
);

Unity

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
});

Go Extend SDK

tierService := &seasonpass.TierService{
    Client:          factory.NewSeasonpassClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
userId := "myuserid"
body := seasonpassclientmodels.UserExpGrant {
    Exp: 300,
}
input := &tier.GrantUserExpParams{
    Body:      &body,
    Namespace: namespace,
    UserID:    userId,
}
result, err := tierService.GrantUserExpShort(input)

Python Extend SDK

import accelbyte_py_sdk.api.seasonpass as seasonpass_service
import accelbyte_py_sdk.api.seasonpass.models as seasonpass_models

result, error = group_service.grant_user_exp(
    user_id="********************************",
    body=seasonpass_models.UserExpGrant()
    .with_exp(300),
)
if error:
    exit(error)

Java Extend SDK

C# Extend SDK

string userId = "<user-id>";

var response = sdk.Seasonpass.Tier.GrantUserExpOp
    .SetBody(new UserExpGrant()
    {
        Exp = 300
    })
    .Execute(sdk.Namespace, userId);
if (response != null)
{
    //do something when success
}

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

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
    })
);

Unity

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
});

Go Extend SDK

itemService := &platform.ItemService{
    Client:          factory.NewPlatformClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
categoryPath := "/seasonpass"
itemType := item.QueryItems1SEASONConstant
region := "US"
input := &item.QueryItems1Params{
    Namespace:              namespace,
    CategoryPath:           &categoryPath,
    ItemType:               &itemType,
    Region:                 &region,
}
result, err := itemService.QueryItems1Short(input)

Python Extend SDK

import accelbyte_py_sdk.api.platform as platform_service

result, error = platform_service.query_items_1(
    region="US",
    item_type="SEASON",
    category_path="/seasonpass",
)
if error:
    exit(error)

Java Extend SDK

C# Extend SDK

var response = sdk.Platform.Item.QueryItems1Op
    .SetRegion("US")
    .SetItemType(QueryItems1ItemType.SEASON)
    .SetCategoryPath("/seasonpass")
    .Execute(sdk.Namespace);
if (response != null)
{
    //do something when success
}

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

Unreal

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
    })
);

Unity

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
});

Go Extend SDK

orderService := &platform.OrderService{
    Client:          factory.NewPlatformClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
userId := "myuserid"
currencyCode := "mycurrencycode"
discountedPrice := int32(100)
itemId := "myitemid"
quantity := int32(1)
body := platformclientmodels.OrderCreate {
    CurrencyCode: &currencyCode,
    DiscountedPrice: &discountedPrice,
    ItemID: &itemId,
    Price: 100,
    Quantity: &quantity,
    ReturnURL: "https://example.com",
    Region: "US",
    Language: "en",
}
input := &order.PublicCreateUserOrderParams{
    Body:      &body,
    Namespace: namespace,
    UserID:    userId,
}
result, err := orderService.PublicCreateUserOrderShort(input)

Python Extend SDK

import accelbyte_py_sdk.api.platform as platform_service
import accelbyte_py_sdk.api.platform.models as platform_models

result, error = platform_service.public_create_user_order(
    user_id="********************************",
    body=platform_models.OrderCreate()
    .with_currency_code("CurrencyCode")
    .with_discounted_price(100)
    .with_item_id("ItemId")
    .with_price(100)
    .with_quantity(1)
    .with_return_url("https://example.com")
    .with_region("US")
    .with_language("en"),
)
if error:
    exit(error)

Java Extend SDK

C# Extend SDK

string userId = "<user-id>";

var response = sdk.Platform.Order.PublicCreateUserOrderOp
    .SetBody(new OrderCreate()
    {
        CurrencyCode = "CurrencyCode",
        DiscountedPrice = 100,
        ItemId = "<item-id>",
        Price = 100,
        Quantity = 1,
        ReturnUrl = "https://example.com",
        Region = "US",
        Language = "en"
    })
    .Execute(sdk.Namespace, userId);
if (response != null)
{
    //do something when success
}

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

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
    })
);

Unity

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
});

Go Extend SDK

itemService := &platform.ItemService{
    Client:          factory.NewPlatformClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
categoryPath := "/seasonpass"
itemType := item.QueryItems1SEASONConstant
region := "US"
input := &item.QueryItems1Params{
    Namespace:              namespace,
    CategoryPath:           &categoryPath,
    ItemType:               &itemType,
    Region:                 &region,
}
result, err := itemService.QueryItems1Short(input)

Python Extend SDK

import accelbyte_py_sdk.api.platform as platform_service

result, error = platform_service.query_items_1(
    region="US",
    item_type="SEASON",
    category_path="/seasonpass",
)
if error:
    exit(error)

Java Extend SDK

C# Extend SDK

var response = sdk.Platform.Item.QueryItems1Op
    .SetRegion("US")
    .SetItemType(QueryItems1ItemType.SEASON)
    .SetCategoryPath("/seasonpass")
    .Execute(sdk.Namespace);
if (response != null)
{
    //do something when success
}

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

Unreal

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
    })
);

Unity

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
});

Go Extend SDK

orderService := &platform.OrderService{
    Client:          factory.NewPlatformClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
userId := "myuserid"
currencyCode := "mycurrencycode"
discountedPrice := int32(100)
itemId := "myitemid"
quantity := int32(1)
body := platformclientmodels.OrderCreate {
    CurrencyCode: &currencyCode,
    DiscountedPrice: &discountedPrice,
    ItemID: &itemId,
    Price: 100,
    Quantity: &quantity,
    ReturnURL: "https://example.com",
    Region: "US",
    Language: "en",
}
input := &order.PublicCreateUserOrderParams{
    Body:      &body,
    Namespace: namespace,
    UserID:    userId,
}

Python Extend SDK

import accelbyte_py_sdk.api.platform as platform_service
import accelbyte_py_sdk.api.platform.models as platform_models

result, error = platform_service.public_create_user_order(
    user_id="********************************",
    body=platform_models.OrderCreate()
    .with_currency_code("CurrencyCode")
    .with_discounted_price(100)
    .with_item_id("ItemId")
    .with_price(100)
    .with_quantity(1)
    .with_return_url("https://example.com")
    .with_region("US")
    .with_language("en"),
)
if error:
    exit(error)

Java Extend SDK

C# Extend SDK

string userId = "<user-id>";

var response = sdk.Platform.Order.PublicCreateUserOrderOp
    .SetBody(new OrderCreate()
    {
        CurrencyCode = "CurrencyCode",
        DiscountedPrice = 100,
        ItemId = "<item-id>",
        Price = 100,
        Quantity = 1,
        ReturnUrl = "https://example.com",
        Region = "US",
        Language = "en"
    })
    .Execute(sdk.Namespace, userId);
if (response != null)
{
    //do something when success
}

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

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
    })
);

Unity

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
});

Go Extend SDK

rewardService := &seasonpass.RewardService{
    Client:          factory.NewSeasonpassClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
userId := "myuserid"
passCode := "PremiumPassCode"
tierIndex := int32(0)
rewardCode := "RewardCode"
body := seasonpassclientmodels.UserRewardClaim {
    PassCode: &passCode,
    TierIndex: &tierIndex,
    RewardCode: &rewardCode,
}
input := &reward.PublicClaimUserRewardParams{
    Body:      &body,
    Namespace: namespace,
    UserID:    userId,
}
result, err := rewardService.PublicClaimUserRewardShort(input)

Python Extend SDK

import accelbyte_py_sdk.api.platform as platform_service
import accelbyte_py_sdk.api.platform.models as platform_models

result, error = platform_service.public_claim_user_reward(
    user_id="********************************",
    body=platform_models.UserRewardClaim()
    .with_pass_code("PremiumPassCode")
    .with_reward_code("RewardCode")
    .with_tier_index(0),
)
if error:
    exit(error)

Java Extend SDK

C# Extend SDK

string userId = "<user-id>";

var response = sdk.Seasonpass.Reward.PublicClaimUserRewardOp
    .SetBody(new UserRewardClaim()
    {
        PassCode = "PremiumPassCode",
        TierIndex = 0,
        RewardCode = "RewardCode"
    })
    .Execute(sdk.Namespace, userId);
if (response != null)
{
    //do something when success
}

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

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

Unity

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
});

Go Extend SDK

rewardService := &seasonpass.RewardService{
    Client:          factory.NewSeasonpassClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
userId := "myuserid"
input := &reward.PublicBulkClaimUserRewardsParams{
    Namespace: namespace,
    UserID:    userId,
}
result, err := rewardService.PublicBulkClaimUserRewardsShort(input)

Python Extend SDK

import accelbyte_py_sdk.api.platform as platform_service

result, error = platform_service.public_bulk_claim_user_rewards(
    user_id="********************************",
)
if error:
    exit(error)

Java Extend SDK

C# Extend SDK

string userId = "<user-id>";

var response = sdk.Seasonpass.Reward.PublicBulkClaimUserRewardsOp
    .Execute(sdk.Namespace, userId);
if (response != null)
{
    //do something when success
}