How accounts work

Last updated on October 24, 2024

Overview

This guide presents essential information about using AGS accounts, to help ensure your players have trouble-free experiences. Topics include:

• How to create an AGS account
• How to link Identity Provider accounts
• Typical use cases & best practices

Prerequisites

• You are familiar with AGS Account Structure & the Key Concepts.

How to get an AGS account

An AGS account provides access to all other AccelByte Gaming Services, such as: user profile, game progression, wallet, entitlements, and more. AGS accounts also enable cross-platform user experiences by linking with multiple identity provider accounts.

Each AGS account can have two different statuses:

• Headless
• Full

Get a headless AGS account

A headless account is the most common type. The system automatically creates one when players sign in to your game for the first time with a custom Device ID or an Identity Provider account like: Playstation, Steam, XBox etc. Once the system creates a headless AGS account, it links it to the corresponding device ID or Identity Provider account.

note

To enable Identity Provider account sign-ins in your game, you need to create the necessary Identity Provider configurations. Read the Authentication section for more details.

Here is a simple overview of the process, starting with a common example.

Example - part 1

Your game studio has two live games (game_1 & game_2) launched on Steam; both are using the same AGS environment.

As a player, this is my first time signing in to either game (e.g: game_1) on Steam with my Steam account(my_steam_account).

Here is what happens:

• As this is the first time the player uses this Steam account (my_steam_account) to sign in to either of the games, AGS hasn't linked it to an existing AGS account. The system creates a headless AGS account (my_ags_account) automatically.
• It includes:
  • A Publisher User ID(publisher_user_id_1) in the Publisher Namespace.
  • A Game User ID (game_user_id_1) in this game Namespace (game_1) that the system links with the Publisher User ID(publisher_user_id_1).
  • This Steam account(my_steam_account) links to this AGS account(my_ags_account) automatically.

Example - part 2

The player uses the same Steam account(my_steam_account) to sign in to the other game (game_2) for the first time on Steam.

Here is what happens:

• This Steam account(my_steam_account) links to an AGS account(my_ags_account). The system doesn't create a new AGS account; instead, the player logs in to the game (game_2) directly.
• The system creates a new Game User ID (game_user_id_2) in the game Namespace (game_2).
• After that, the player's headless AGS account(my_ags_account) includes:
  • A Publisher User ID (publisher_user_id_1) in the Publisher Namespace.
  • A Game User ID (game_user_id_1) in the Game Namespace(game_1), which the system associates with the Publisher User ID (publisher_user_id_1).
  • Another Game User ID (game_user_id_2) in the Game Namespace(game_2), which the system associates with the Publisher User ID(publisher_user_id_1).
  • A linked Steam account(my_steam_account).

note

The only way to verify identity and sign in to a headless account is to authenticate the linked identity provider account (or device ID).

Consider prompting players to upgrade their headless account once they start investing in your game. That way, you can build a direct relationship with your players.

Get a full AGS account

A full account is a complete AccelByte account with a verified email address, password, and basic user information.

Players can get a number of benefits from a full account:

• Use it for account linking with any supported identity provider (such as: Steam, PlayStation, XBox, etc.).
• Enable the 2FA mechanism for account protection.
• Manage profiles, request access to their personal data, and more.

There are two ways to get a full account: enable full account registration, and upgrade a headless account to a full one.

note

You can customize the validation of players' username, display name, password, and email with AGS IAM Input Validation.

Enable the traditional full account registration

You can enable the full account registration flow through our Player Portal or SDKs.

Here is a simple overview of the process:

Full account registration through the Player Portal

note

With our App Editor, you can apply UI and configuration changes to your Player Portal while it's running, eliminating the requirement to rebuild or redeploy.

In-game player registration

This function allows your players to register for an account in your game.

Unreal

const FString OriginalEmail = TEXT("originalEmail@example.com");
const FString Username = TEXT("JohnDoe");
const FString Password = TEXT("password");
const FString DisplayName = TEXT("testName");
const FString Country = TEXT("US");
const FString DateOfBirth = TEXT("2000-12-20");
bool bUserAccountCreated = false;

FRegistry::User.Registerv2(OriginalEmail, Username, Password, DisplayName, Country, DateOfBirth,
    THandler<FUserData>::CreateLambda([&bUserAccountCreated](const FUserData& Result)
    {
        UE_LOG(LogAccelByteUserTest, Display, TEXT("Success."));
        bUserAccountCreated = true;
    }),
    FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
    {
        UE_LOG(LogAccelByteUserTest, Error, TEXT("Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage)
    }));

Unity

private void OnRegister(Result<RegisterUserResponse> result)
{
    if (result.IsError)
    {
        Debug.Log($"Register failed: {result.Error.Message}");
    }
    else
    {
        Debug.Log("Register successful.");
    }
}

public static void Main(string[] args)
{
    var user = AccelByteSDK.GetClientRegistry().GetApi().GetUser();
    string email = "useremail@example.com";
    string username = "JohnDoe";
    string password = "password";
    string displayName = "displayed";
    string country = "US";
    System.DateTime dateOfBirth = new System.DateTime(year: 1995, month: 12, day: 30);
    user.Registerv2(email, username, password, displayName, country, dateOfBirth, OnRegister);
}

Go Extend SDK

usersV4Service := &iam.UsersV4Service{
    Client:          factory.NewIamClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
authType := "EMAILPASSWD"
country := "US"
dateOfBirth := "1995-12-30"
displayName := "displayed"
emailAddress := "useremail@example.com"
password := "password"
username := "JohnDoe"
input := &users_v4.AdminCreateUserV4Params{
    Body: &iamclientmodels.AccountCreateUserRequestV4{
        AuthType: &authType,
        EmailAddress: &emailAddress,
        Username: &username,
        Password: password,
        DisplayName: displayName,
        Country: &country,
        DateOfBirth: dateOfBirth,
        UniqueDisplayName: displayName,
    },
    Namespace: namespace,
}
result, err := usersV4Service.AdminCreateUserV4Short(input)

Python Extend SDK

import accelbyte_py_sdk.api.iam as iam_service
import accelbyte_py_sdk.api.iam.models as iam_models

result, error = iam_service.public_create_user_v4(
    body=iam_models.AccountCreateUserRequestV4()
    .with_auth_type(iam_models.AccountCreateUserRequestV4AuthTypeEnum.EMAILPASSWD)
    .with_country("US")
    .with_date_of_birth("1990-01-01")
    .with_display_name("********")
    .with_username("********")
    .with_password("********")
    .with_email_address("********")
)
if error:
    exit(error)

Java Extend SDK

Users usersWrapper = new Users(sdk);

String userEmail = "john.doe@example.com";
String userPassword = "pass567$#@";
String displayName = "John Doe";
String userCountry = "US";
String userDob = "2000-12-20";
ModelUserCreateRequestV3 body = ModelUserCreateRequestV3.builder()
    .authType(AccountCreateUserRequestV4.AuthType.EMAILPASSWD.toString())
    .emailAddress(userEmail)
    .password(userPassword)
    .displayName(displayName)
    .country(userCountry)
    .dateOfBirth(userDob)
    .build();

ModelUserCreateResponseV3 response;
try {
    usersWrapper.publicCreateUserV3(PublicCreateUserV3.builder()
        .namespace("<namespace>")
        .body(body)
        .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 userEmail = "john.doe@example.com";
string userPassword = "pass567$#@";
string displayName = "John Doe";
string userCountry = "US";
string userDob = "2000-12-20";

ModelUserCreateRequestV3 newUser = new ModelUserCreateRequestV3()
{
    AuthType = "EMAILPASSWD",
    EmailAddress = userEmail,
    Password = userPassword,
    DisplayName = displayName,
    Country = userCountry,
    DateOfBirth = userDob
};

ModelUserCreateResponseV3? cuResp = sdk.Iam.Users.PublicCreateUserV3Op
    .Execute(newUser, sdk.Namespace);
if (cuResp != null)
{
    //do something when success
}

Upgrade headless account to be a full account

Lack of a valid email address, username, password, and other necessary information is the only difference between a a headless and a full account. You can also get a full account by upgrading a headless account either through our Player Portal or SDKs.

Here is a simple overview of the process:

Upgrade a headless account through the Player Portal

In-Game upgrade headless account

This function allows your players to upgrade their headless account in your game.

Unreal

const FString OriginalEmail = TEXT("originalEmail@example.com");
const FString Password = TEXT("Password1");

FAccountUserData userData;
FRegistry::User.Upgrade(OriginalEmail, Password,
    THandler<FAccountUserData>::CreateLambda([&](const FAccountUserData& Result)
    {
        userData = Result;
        UE_LOG(LogAccelByteUserTest, Display, TEXT("Success."));
    }),
    FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& ErrorMessage)
    {
        UE_LOG(LogAccelByteUserTest, Error, TEXT("Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
    }));

//log out
FRegistry::User.ForgetAllCredentials();

Unity

var user = AccelByteSDK.GetClientRegistry().GetApi().GetUser();
string email = "johnDoe@example.com";
string password = "Password1";

//upgrade v1
Result<UserData> upgradeResult = null;
user.Upgrade(email, password, result =>
{
  upgradeResult = result;
});

Result logoutResult = null;
user.Logout(result =>
{
  logoutResult = result;
});

Go Extend SDK

usersService := &iam.UsersService{
    Client:          factory.NewIamClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
namespace := "mygame"
emailAddress := "useremail@example.com"
password := "password"
input := &users.PublicVerifyHeadlessAccountV3Params{
    Body:                 &iamclientmodels.ModelUpgradeHeadlessAccountV3Request{
        EmailAddress: &emailAddress,
        Password: &password,
    },
    Namespace:            namespace,
    NeedVerificationCode: &needVerificationCode,
}
result, err := usersService.PublicVerifyHeadlessAccountV3Short(input)

Python Extend SDK

import accelbyte_py_sdk.api.iam as iam_service
import accelbyte_py_sdk.api.iam.models as iam_models

result, error = iam_service.public_upgrade_headless_account_v4(
    body=iam_models.AccountUpgradeHeadlessAccountRequestV4()
    .with_email_address("********")
    .with_password("********")
)
if error:
    exit(error)

Java Extend SDK

Users usersWrapper = new Users(sdk);

String userEmail = "john.doe@example.com";
String userPassword = "pass567$#@";

ModelUpgradeHeadlessAccountV3Request body = ModelUpgradeHeadlessAccountV3Request.builder()
    .emailAddress(userEmail)
    .password(userPassword)
    .build();


ModelUserResponseV3 response;
try {
    response = usersWrapper.publicVerifyHeadlessAccountV3(PublicVerifyHeadlessAccountV3.builder()
        .namespace("<namespace>")
        .body(body)
        .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 userEmail = "john.doe@example.com";
string userPassword = "pass567$#@";

var response = _Sdk.Iam.Users.PublicVerifyHeadlessAccountV3Op
    .Execute(new ModelUpgradeHeadlessAccountV3Request()
    {
        EmailAddress = userEmail,
        Password = userPassword
    }, _Sdk.Namespace);
if (response != null)
{
    //do something when success
}

How to link Identity Provider accounts

Account linking is an essential feature to support cross-platform experiences. It represents the association of one or more identity providers with an AGS account. With a linked Identity Provider account, players can verify their identity and sign in to continue their experience across platforms while keeping their gameplay data intact.

note

Due to Identity Provider platform regulations, there are two primary limitations of account linking:

• A player can only link one identity provider account to one AGS account.
• Players can only link one identity provider account per platform to their AGS account. For example, a player can only link one Steam account to their AccelByte account. This rule is true even if players unlink their previous Steam account then attempt to link another one.

Here is a simple overview of the process:

Typical use case & best practices

Let's take a look at another typical cross-platform use case.

Example - part 1

As a game studio, I have one live game (game_1) launched on Steam and XBox.

As a player, I start my game_1 journey on the Steam platform first with my Steam account(my_steam_account).

Here is what will happen:

• The player is using this Steam account (my_steam_account) for the first time to sign in to game_1, which means they haven't linked it to an AGS account yet. The system automatically creates a new headless AGS account (my_ags_account).
• It includes:
  • A Publisher User ID(publisher_user_id_1) in the Publisher Namespace.
  • A Game User ID (game_user_id_1) in the Game Namespace (game_1), which is associated with the Publisher User ID (publisher_user_id_1).
  • Besides that, the Steam account (my_steam_account) the player used links to their AGS account(my_ags_account) automatically.

Example - part 2

The player wants to play game_1 on their XBox console with their XBox account (my_xbox_account) and continue their game progression on Steam on the XBox platform.

Best Practices

Here is our recommended solution in this case:

• Provide your players a no-friction experience to give your game a first try in any platform (Steam) by using an identity provider account(my_steam_account) which triggers the system to automatically create a headless account (my_ags_account).
• Once players start investing in your game, prompt them to upgrade their headless account(my_ags_account) to a full one.
• Before players start the game for the first time on a new platform (XBox), provide players an option to link their game platform account (my_xbox_account) to an existing AccelByte account (my_ags_account), if they have one.
• Players can continue their game experience on the new platform while keeping their gameplay data intact.

This is what the player has:

What if...

You may be curious about what happens if the player doesn't link their game platform account to the existing AccelByte account in Step 3 above before they start the game on the new platform.

Example - part 1

A player doesn't link their Xbox account (my_xbox_account) to their existing AGS account (my_ags_account) but chose to start game_1 directly.

This is what happens:

• As this is the first time the player uses their XBox account (my_xbox_account) to sign in to game_1 on their XBox console, their Xbox account isn't linked to any existing AGS account. The system creates another headless AGS account (my_ags_account_2) automatically.
• It includes:
  • A Publisher User ID (publisher_user_id_2) in the Publisher Namespace.
  • A Game User ID (game_user_id_2) in this specific Game Namespace (game_1), which links to the Publisher User ID (publisher_user_id_2).
  • The XBox account (my_xbox_account) the player used links to their AGS account (my_ags_account_2).

Example - part 2

A player realizes that they have to start this game_1 over again on XBox console. This is not what they want; they want to continue the game play they already have on the Steam platform.

Since game progress is stored in an AGS account, in this case, the player needs to link their XBox account (my_xbox_account) to the previous AGS account (my_ags_account) to continue the game play they created on Steam.

In terms of our account linking limitation, one identity provider account can link to one AGS account at a time. The player needs to unlink the XBox account (my_xbox_account) from the current AGS account (my_ags_account_2) first.

Here are the steps players may take in this case:

• Sign into Player Portal with the new AGS account (my_ags_account_2) and unlink the XBox account (my_xbox_account) from the AGS account first.
• Log out of the Player Portal and sign in with the previous AGS account (my_ags_account) and link the XBox account (my_xbox_account).
• That's it. The next time the player launches the game on Steam or XBox, they can share and continue the same game progression in this AGS account (my_ags_account).

Here is what the player has:

note

In the orphaned AGS account (my_ags_account_2), the system keeps everything as normal and doesn't clean anything up. The only thing we need to be aware of is that there is no way for that player to authenticate and sign into the AGS account anymore, unless it links with another third-party platform account or the player promotes it to a full AGS account before unlinking the XBox account.