Persona Component Tutorial

Persona Component Tutorial#

Personas are one of the first things you should learn after Authentication Basics in Xsolla Backend.

This tutorial walks you through the Persona component, its services, and real-world implementation. You will learn how to create, update, and manage personas while leveraging Persona Resources in XBE ecosystems.

Overview#

A Persona represents all player data in a game, enabling multiple personas per account. Personas serve as unique online identities within a game and allow robust user management capabilities.

Difficulty Rating: ⭐⭐☆☆☆

Key Points#

  • Streamlined Identity Management: Personas serve as modular identities, allowing users to maintain multiple profiles or characters within a game ecosystem.

  • Customizable Attributes: Easily define and modify persona attributes to enhance gameplay and personalization.

  • Robust API Integration: The PersonaService provides methods for managing personas, updating attributes, and retrieving associated resources with ease.

  • Scalable Design: The persona framework supports complex systems with multiple players, resources, and transactions.

  • Seamless Resource Management: Integrate persona-specific resources for inventory, stats, and ownership through unified APIs.

  • Cross-Language Examples: Comprehensive implementation examples for C++, C#, TypeScript, Unity, and Unreal.

Tutorial Steps#

  1. Persona Basics

  2. Using PersonaService

  3. Create a Persona

  4. Update an Existing Persona

  5. Update Persona Attributes

  6. Populate Persona Data

  7. Resources

  8. Create Resource

  9. Persona Resources

Persona#

A Persona acts as a user’s identity within a game. Each persona contains essential metadata and attributes that define the user’s role, gameplay data, or settings.

Data Structure#

Field

Description

UserUid

Unique identifier of the user.

Name

Unique persona name.

Description

A textual description of the persona.

ProductUid

Associated product UID.

Attributes

Key-value pairs defining persona characteristics.

PersonaService#

The PersonaService serves as the primary interface to create, manage, and retrieve personas.

Service Functions#

Method

Description

Create

Creates a new persona.

FindById

Retrieves a persona by ID.

FindAll

Returns all accessible personas.

Update

Updates persona information.

Count

Retrieves a count of personas based on criteria.

Delete

Deletes a persona by its unique identifier.

Create a Persona for a User#

 1auto XBESubsystem = (FOnlineSubsystemXBE*)IOnlineSubsystem::Get();
 2auto CoreSDK = XBESubsystem->GetCoreSDK();
 3auto obj{ std::make_shared<xbe::sdk::models::Persona>() };
 4obj->SetName(utility::conversions::to_string_t("Persona Name"));
 5obj->SetUid(utility::conversions::to_string_t(CoreSDK->GetLoggedInUser()->GetUid()));
 6
 7auto personaService = CoreSDK->GetServiceFactory()->GetService<xbe::sdk::services::PersonaService>();
 8
 9personaService->Create(obj).then(
10   [](pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
11{
12     try
13     {
14         auto persona = task.get();
15
16     }
17     catch (const xbe::sdk::Exception& e)
18     {
19         // Handle error here
20         throw e;
21     }
22}).wait();

1PersonaService personaService = CoreSDK.GetService<PersonaService>();
2Persona persona = new()
3{
4   Name = "Persona Name",
5   UserUid = CoreSDK.LoggedInUser.Uid,
6};
7
8persona = personaService.Create(persona);

1// TODO

 1auto XBESubsystem = (FOnlineSubsystemXBE*)IOnlineSubsystem::Get();
 2auto CoreSDK = XBESubsystem->GetCoreSDK();
 3auto obj{ std::make_shared<xbe::sdk::models::Persona>() };
 4obj->SetName(utility::conversions::to_string_t("Persona Name"));
 5obj->SetUid(utility::conversions::to_string_t(CoreSDK->GetLoggedInUser()->GetUid()));
 6
 7auto personaService = CoreSDK->GetServiceFactory()->GetService<xbe::sdk::services::PersonaService>();
 8
 9personaService->Create(obj).then(
10   [](pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
11{
12     try
13     {
14         auto persona = task.get();
15
16     }
17     catch (const xbe::sdk::Exception& e)
18     {
19         // Handle error here
20         throw e;
21     }
22}).wait();

1// TODO

Update an Existing Persona#

 1auto XBESubsystem = (FOnlineSubsystemXBE*)IOnlineSubsystem::Get();
 2auto CoreSDK = XBESubsystem->GetCoreSDK();
 3auto personaService = CoreSDK->GetServiceFactory()->GetService<xbe::sdk::services::PersonaService>();
 4
 5std::string PERSONA_ID = "5f5b3b7b-4b3b-4b3b-4b3b-5f5b3b7b4b3b";
 6
 7personaService->FindById(PERSONA_ID).then(
 8    [PERSONA_ID, personaService](pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
 9    {
10        try
11        {
12            auto persona = task.get();
13            persona->SetName(utility::conversions::to_string_t("The Doctor"));
14            personaService->Update(persona->GetUid(), persona).then(
15                [](pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
16            {
17                try
18                {
19                    auto persona = task.get();
20                }
21                catch (const xbe::sdk::Exception& e)
22                {
23                    // Handle error here
24                    throw e;
25                }
26            }).wait();
27
28        }
29        catch (const xbe::sdk::Exception& e)
30        {
31            // Handle error here
32            throw e;
33        }
34}).wait();

1PersonaService personaService = CoreSDK.GetService<PersonaService>();
2Persona persona = personaService.FindByID(PERSONA_ID);
3
4persona.Name = "The Doctor";
5persona = personaService.Update(persona.Uid.ToString(), persona);

1// TODO

 1auto XBESubsystem = (FOnlineSubsystemXBE*)IOnlineSubsystem::Get();
 2auto CoreSDK = XBESubsystem->GetCoreSDK();
 3auto personaService = CoreSDK->GetServiceFactory()->GetService<xbe::sdk::services::PersonaService>();
 4
 5std::string PERSONA_ID = "5f5b3b7b-4b3b-4b3b-4b3b-5f5b3b7b4b3b";
 6
 7personaService->FindById(PERSONA_ID).then(
 8    [PERSONA_ID, personaService](pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
 9    {
10        try
11        {
12            auto persona = task.get();
13            persona->SetName(utility::conversions::to_string_t("The Doctor"));
14            personaService->Update(persona->GetUid(), persona).then(
15                [](pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
16            {
17                try
18                {
19                    auto persona = task.get();
20                }
21                catch (const xbe::sdk::Exception& e)
22                {
23                    // Handle error here
24                    throw e;
25                }
26            }).wait();
27
28        }
29        catch (const xbe::sdk::Exception& e)
30        {
31            // Handle error here
32            throw e;
33        }
34}).wait();

1// TODO

Update Persona Attributes#

 1auto XBESubsystem = (FOnlineSubsystemXBE*)IOnlineSubsystem::Get();
 2auto CoreSDK = XBESubsystem->GetCoreSDK();
 3auto personaService = CoreSDK->GetServiceFactory()->GetService<xbe::sdk::services::PersonaService>();
 4
 5std::string Persona_ID = "5f5b3b7b-4b3b-4b3b-4b3b-5f5b3b7b4b3b";
 6
 7personaService->FindById(Persona_ID).then([Persona_ID, personaService](
 8    pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
 9{
10    try
11    {
12        std::map<utility::string_t, xbe::sdk::Variant> map = {
13            {
14                _XPLATSTR("inventory"),
15                Inventory({
16                    Item("Sonic Screwdriver", 100, {
17                        Owner("Whitaker"),
18                        Owner("Capaldi"),
19                        Owner("Smith"),
20                        Owner("Tennant"),
21                        Owner("Eccleston")
22                    })
23                })
24            }
25        };
26
27        auto attribute{ std::make_shared<xbe::sdk::Object>(map) };
28        persona->SetAttributes(attribute);
29
30        personaService->Update(persona->GetUid(), persona).then(
31            [](pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
32        {
33            try
34            {
35                auto persona = task.get();
36            }
37            catch (const xbe::sdk::Exception& e)
38            {
39                // Handle error here
40                throw e;
41            }
42        }).wait();
43
44    }
45    catch (const xbe::sdk::Exception& e)
46    {
47        // Handle error here
48        throw e;
49    }
50}).wait();

 1PersonaService personaService = CoreSDK.GetService<PersonaService>();
 2Persona persona = personaService.FindByID(PERSONA_ID);
 3
 4Owner owner1 = new() { name = "Whitaker" };
 5Owner owner2 = new() { name = "Capaldi" };
 6Owner owner3 = new() { name = "Smith" };
 7Owner owner4 = new() { name = "Tennant" };
 8Owner owner5 = new() { name = "Eccleston" };
 9
10List<Owner> previousOwners = new() { owner1, owner2, owner3, owner4, owner5 };
11
12Item item = new()
13{
14    name = "Sonic Screwdriver",
15    value = 100,
16    previousOwners = previousOwners,
17};
18
19List<Item> items = new() { item };
20Inventory inventory = new() { items = items };
21
22Object attributes = new() {{ "inventory", inventory }};
23
24persona.Attributes = attributes;
25persona = personaService.Update(persona.Uid.ToString(), persona);
26
27Inventory inv = new Inventory(persona.Attributes["inventory"] as Object);

1// TODO

 1auto XBESubsystem = (FOnlineSubsystemXBE*)IOnlineSubsystem::Get();
 2auto CoreSDK = XBESubsystem->GetCoreSDK();
 3auto personaService = CoreSDK->GetServiceFactory()->GetService<xbe::sdk::services::PersonaService>();
 4
 5std::string Persona_ID = "5f5b3b7b-4b3b-4b3b-4b3b-5f5b3b7b4b3b";
 6
 7personaService->FindById(Persona_ID).then([Persona_ID, personaService](
 8    pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
 9{
10    try
11    {
12        std::map<utility::string_t, xbe::sdk::Variant> map = {
13            {
14                _XPLATSTR("inventory"),
15                Inventory({
16                    Item("Sonic Screwdriver", 100, {
17                        Owner("Whitaker"),
18                        Owner("Capaldi"),
19                        Owner("Smith"),
20                        Owner("Tennant"),
21                        Owner("Eccleston")
22                    })
23                })
24            }
25        };
26
27        auto attribute{ std::make_shared<xbe::sdk::Object>(map) };
28        persona->SetAttributes(attribute);
29
30        personaService->Update(persona->GetUid(), persona).then(
31            [](pplx::task<std::shared_ptr<xbe::sdk::models::Persona>> task)
32        {
33            try
34            {
35                auto persona = task.get();
36            }
37            catch (const xbe::sdk::Exception& e)
38            {
39                // Handle error here
40                throw e;
41            }
42        }).wait();
43
44    }
45    catch (const xbe::sdk::Exception& e)
46    {
47        // Handle error here
48        throw e;
49    }
50}).wait();

1// TODO

Populate Persona Data#

 1// Define the Owner class
 2class Owner {
 3public:
 4    std::string name;
 5
 6    Owner(const std::string& ownerName) : name(ownerName) {}
 7};
 8
 9// Define the Item class
10class Item {
11public:
12    std::string name;
13    int value;
14    std::vector<Owner> previousOwners;
15
16    Item(const std::string& itemName, int itemValue, const std::vector<Owner>& owners)
17        : name(itemName), value(itemValue), previousOwners(owners) {}
18};
19
20// Define the Inventory class
21class Inventory : public xbe::sdk::Variant {
22public:
23    std::vector<Item> items;
24
25    Inventory(const std::vector<Item>& itemList) : items(itemList) {}
26};

 1[Serializable]
 2public class Owner
 3{
 4    public string name;
 5
 6    public Owner() {}
 7    public Owner(xbe.sdk.Object data)
 8    {
 9        name = data.GetValue("name");
10    }
11}
12
13[Serializable]
14public class Item
15{
16    public string name;
17    public float value;
18    public List<Owner> previousOwners;
19
20    public Item() {}
21    public Item(xbe.sdk.Object data)
22    {
23        name = data.GetValue<string>("name");
24        value = data.GetValue<float>("value");
25        previousOwners = data.GetValue<List<xbe.sdk.Object>>("previousOwners")
26            .Select(o => new Owner(o)).ToList();
27    }
28}
29
30[Serializable]
31public class Inventory
32{
33    public List<Item> items;
34
35    public Inventory() {}
36    public Inventory(xbe.sdk.Object data)
37    {
38        items = data.GetValue<List<xbe.sdk.Object>>("items").Select(
39            o => new Item(o)).ToList();
40    }
41}

1// TODO

 1// Define the Owner class
 2class Owner {
 3public:
 4    std::string name;
 5
 6    Owner(const std::string& ownerName) : name(ownerName) {}
 7};
 8
 9// Define the Item class
10class Item {
11public:
12    std::string name;
13    int value;
14    std::vector<Owner> previousOwners;
15
16    Item(const std::string& itemName, int itemValue, const std::vector<Owner>& owners)
17        : name(itemName), value(itemValue), previousOwners(owners) {}
18};
19
20// Define the Inventory class
21class Inventory : public xbe::sdk::Variant {
22public:
23    std::vector<Item> items;
24
25    Inventory(const std::vector<Item>& itemList) : items(itemList) {}
26};

1// TODO

Resources#

Resource Object Data Structure#

Resource Object#

Name

Description

Name

Unique resource name.

Cost

Associated costs.

Data

Arbitrary key-value data.

Defaults

Default configuration.

Description

Textual description.

ParentUid

UID of the parent resource.

Stackable

Indicates stackability.

Stats

Defined statistics.

Title

Display name for users.

Create Resource#

A Resource represents key in-game data and inventory items. This section demonstrates how to create resources programmatically.

 1try
 2{
 3    auto& resourceService = CoreSDK->GetServiceFactory()->GetService<services::ResourceService>();
 4    std::shared_ptr<Resource> resource = std::make_shared<Resource>(Resource());
 5
 6    resource->SetName(_XPLATSTR("Sonic Screwdriver"));
 7    resourceService->Create(resource).then(
 8        [resourceService](pplx::task<std::shared_ptr<Resource>> task)
 9    {
10        try
11        {
12            std::shared_ptr<Resource> resource2 = task.get();
13        }
14        catch (const xbe::sdk::Exception& e)
15        {
16            // Handle error here
17        }
18        catch (const std::exception& e)
19        {
20            // Handle error here
21        }
22    }).wait();
23}
24catch (const xbe::sdk::Exception& e)
25{
26    // Handle error here
27}
28catch (const std::exception& e)
29{
30    // Handle error here
31}

 1try
 2{
 3    ResourceService resourceService = CoreSDK.ServiceFactory.GetService<ResourceService>();
 4    Resource resource = new() { Name = "Sonic Screwdriver" };
 5    resource = await resourceService.Create(resource);
 6}
 7catch (Exception ex)
 8{
 9    // Handle error here
10}

1// TODO

1// TODO

1// TODO

Persona Resources#

A Persona Resource provides inventory and ownership capabilities, linking personas to game objects.

Data Structure#

PersonaResource Object#

Field

Description

PersonaUid

Associated persona’s UID.

ResourceUid

Resource definition UUID.

Quantity

Resource count (negative indicates unlimited).

Data

Additional resource metadata.

Stats

Unique attributes for non-stackable resources.

Retrieve Persona Resources#

 1try
 2{
 3    auto personaResourceService = CoreSDK->GetServiceFactory()->GetService<services::PersonaResourceService>();
 4    std::map<utility::string_t, Variant> searchParams{ { _XPLATSTR("personaUid"), PERSONA_ID } };
 5
 6    personaResourceService->FindAll(&searchParams).then(
 7        [](pplx::task<std::vector<std::shared_ptr<PersonaResource>>> task)
 8    {
 9        try
10        {
11            std::vector<std::shared_ptr<PersonaResource>> resources = task.get();
12
13        }
14        catch (const xbe::sdk::Exception& e)
15        {
16            // Handle error here
17        }
18    }).wait();
19}
20catch (const xbe::sdk::Exception& e)
21{
22    // Handle error here
23}
24catch (const std::exception& e)
25{
26    // Handle error here
27}

 1try
 2{
 3    PersonaResourceService personaResourceService = CoreSDK.ServiceFactory.GetService<PersonaResourceService>();
 4    Dictionary<string, string> query = new() {{ "personaUid", PERSONA_ID }};
 5    List<PersonaResource> resources = await personaResourceService.FindAll(query);
 6}
 7catch (Exception ex)
 8{
 9    // Handle error here
10}

1// TODO

1// TODO

1// TODO

Conclusion#

This tutorial demonstrated the creation, updating, and management of personas and persona resources, as well as creating resources critical to game development. These foundational actions empower scalable and robust identity management in gaming ecosystems.

Use Cases#

  • Multiplayer Gaming: Implement personas to allow players to create and manage multiple characters within a game.

  • Personalized Experiences: Use persona attributes to offer tailored experiences, including custom stats, avatars, and achievements.

  • Inventory Management: Seamlessly link personas to in-game resources and manage ownership, transactions, and inventory limits.

  • Game Ecosystem Integration: Enable modular identities that interact with other game systems such as matchmaking, achievements, and progression.

  • Enterprise Applications: Use personas in non-gaming scenarios like enterprise systems where roles, permissions, and resources need to be managed dynamically.

  • Stat Tracking: Enhance gameplay by linking personas to personalized stats, including leaderboards and performance tracking.