Go to dashboard

CoreServices

Information about the attributes and methods available in the CoreServices class.

CoreServices powers the critical components of Sphere Kit, including authentication, achievements and error handling. CoreServices is a static class and all attributes and methods are static.

Attributes

Name
Purpose

HasInitialized

Whether Sphere Kit has been initialised.

CurrentPlayer

The signed in player information (present even if authentication has expired). Null if no player has been signed in.

AchievementsSettings

The settings for the Achievements module.

DatabaseSettings

The settings for the Database module.

Methods

Initialize()

Initialises Sphere Kit. This method must be called before any other methods in the Sphere Kit SDK.

Example

await CoreServices.Initialize();

Possible exceptions

MissingFieldException

The Project Settings have not been configured correctly.

SignInWithSphere(bool refresh = false)

Signs in the player to the game using their Sphere account.

Parameters:

  • bool refresh: Whether to open the browser and complete the full sign-in process even if the user has already been signed in.

Example

await CoreServices.SignInWithSphere();

Possible exceptions

InvalidOperationException

Authentication will not work on iOS and Android if the Deep Link Scheme has not been configured.

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

SignInCancelled

The user has cancelled the sign-in operation. If the user just closes the browser, this exception will not be triggered.

SignInFailed

The sign-in has failed due to an unexpected error.

SignInTimeout

The sign-in attempt has timed out after 10 minutes.

GetPlayerInfo(string uid)

Gets the player information for the given UID.

Parameters:

  • string uid: The UID of the player to retrieve.

Returns: The player information for the UID specified (Player instance).

Example

await CoreServices.GetPlayerInfo("YOUR_UID_HERE");

Possible exceptions

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

NotSignedIn

User is not signed in.

NotFoundException

Exception code (NotFoundException)
Meaning

PlayerNotFound

The player with the specified UID was not found in this game.

GetPlayerCount()

Gets the total number of players in the game.

Returns: Task<long> The total number of players that have signed in to this game.

Example

var playerCount = await CoreServices.GetPlayerCount();

Possible exceptions

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

NotSignedIn

User is not signed in.

AddPlayerStateChangeListener(Action<AuthState> onPlayerStateChange, bool requireInitialState = false)

Adds a listener for player authentication and information state changes.

Parameters:

  • Action<AuthState> onPlayerStateChange: A callback for when the player state changes.

  • bool requireInitialState: Whether to call the callback with the latest player state immediately after adding the listener.

Example

Action<AuthState> myListener = (authState) => { /* ... */ };
CoreServices.AddPlayerStateChangeListener(myListener);
RemovePlayerStateChangeListener(Action onPlayerStateChange)

Removes a listener for player authentication and information state changes.

Parameters:

  • Action<AuthState> onPlayerStateChange: The callback to be removed.

Example

Action<AuthState> myListener = (authState) => { /* ... */ };
CoreServices.AddPlayerStateChangeListener(myListener);
// ... later in the code
CoreServices.RemovePlayerStateChangeListener(myListener);
UpdatePlayerMetadata(Dictionary<string, PlayerDataOperation> update)

Updates the signed-in player's metadata. The metadata will be publicly shown on the user's profile in the Sphere app. A maximum of 10 fields can be added, and fields can only be strings, numbers or booleans.

Parameters:

  • Dictionary<string, PlayerDataOperation> update: The update specification.

The key of the update specification is the metadata field to be updated, for example: "K/D"

The value is a PlayerDataOperation, which can be one of the following:

Operation
Purpose

PlayerDataOperation.Set(object value)

Sets the field to the specified value.

PlayerDataOperation.Inc(object value)

Increments the field by the specified value.

PlayerDataOperation.Dec(object value)

Decrements the field by the specified value.

PlayerDataOperation.Min(object value)

Sets the field to the minimum of the current value and the specified value.

PlayerDataOperation.Max(object value)

Sets the field to the maximum of the current value and the specified value.

PlayerDataOperation.Mul(object value)

Multiplies the field by the specified value.

PlayerDataOperation.Div(object value)

Divides the field by the specified value.

PlayerDataOperation.Unset()

Unsets the field (removes the field and its data).

Returns: Task<Player> : The updated player information

Example

var updatedPlayer = await CoreServices.UpdatePlayerMetadata(new Dictionary<string, PlayerDataOperation>());

Possible exceptions

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

NotSignedIn

User is not signed in.

BadRequestException

Exception code (BadRequestExceptionCode)
Meaning

InvalidUpdateDataType

The data type of the field being updated does not match the update operation (e.g. Inc operation on a field with a string value)

PlayerMetadataLimitReached

There are already 10 metadata fields added and fields must be removed to add more fields.

DivideByZero

The value of a divide operation cannot be zero.

GetAchievements(string? query = null, int pageSize = 30, string? groupName = null, bool? ungrouped = null, AchievementsSortField sortBy = AchievementsSortField.DisplayName, SortDirection sortDirection = SortDirection.Ascending)

Gets achievements available in the game. If no sort field/direction is provided, achievements will be returned in ascending order of their display name.

Parameters:

  • string? query: A full-text search query.

  • int pageSize: The number of achievements to retrieve at a time. Defaults to 30, maximum 30.

  • string? groupName: The group ID to get achievements from. Either this or ungrouped can be specified, not both.

  • bool? ungrouped: Whether to get ungrouped achievements. Either this or groupName can be specified, not both.

  • AchievementsSortField sortBy: The field to sort the achievements by. Defaults to display name.

  • SortDirection sortDirection: The direction to sort the achievements by. Defaults to ascending.

Returns: AchievementsCursor : A cursor to get the pages of achievements, where each page has up to pageSize achievements.

Example

var cursor = CoreServices.GetAchievements(
    query: "Gold",
    groupName: "group1",
    sortBy: AchievementsSortField.GroupOrder,
    sortDirection: SortDirection.Ascending
);

while (cursor.HasNext) {
    var achievements = await cursor.Next();
    /* ... */
}

Possible exceptions

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

NotSignedIn

User is not signed in.

ListAllAchievements(string? groupName = null, bool? ungrouped = null, AchievementsSortField sortBy = AchievementsSortField.DisplayName, SortDirection sortDirection = SortDirection.Ascending)

Gets an array of core achievement information in the game - including achievement ID, display name, group name and group order.

Parameters:

  • string? groupName: The group ID to get achievements from.

  • bool? ungrouped: Whether to get ungrouped achievements.

  • AchievementsSortField sortBy: The field to sort the achievements by.

  • SortDirection sortDirection: The direction to sort the achievements by.

Returns: Task<ListedAchievement[]> : An array of the core achievement information.

Example

var achievements = await CoreServices.ListAllAchievements(
    sortBy: AchievementsSortField.PercentageAchieved,
    sortDirection: SortDirection.Descending
);

foreach (var listedAchievement in achievements)
{
    Debug.Log(listedAchievement.DisplayName);
}

Possible exceptions

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

NotSignedIn

User is not signed in.

GetAchievementGroups(string? query = null, int pageSize = 30, AchievementGroupsSortField sortBy = AchievementGroupsSortField.DisplayName, SortDirection sortDirection = SortDirection.Ascending)

Gets achievement groups available in the game. If no sort field/direction is provided, achievement groups will be returned in ascending order of their display name.

Parameters:

  • string? query: A full-text search query.

  • int pageSize: The number of achievement groups to retrieve at a time. Defaults to 30, maximum 30.

  • AchievementGroupsSortField sortBy: The field to sort the achievement groups by.

  • SortDirection sortDirection: The direction to sort the achievement groups by.

Returns: AchievementGroupsCursor : A cursor to get the pages of achievement groups, where each page has up to pageSize achievement groups.

Example

var cursor = CoreServices.GetAchievementGroups(
    "Gold",
    sortBy: AchievementGroupsSortField.DisplayName,
    sortDirection: SortDirection.Descending
);

while (cursor.HasNext)
{
    var achievementGroups = await cursor.Next();
    /* ... */
}

Possible exceptions

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

NotSignedIn

User is not signed in.

ListAllAchievementGroups(AchievementGroupsSortField sortBy = AchievementGroupsSortField.DisplayName, SortDirection sortDirection = SortDirection.Ascending)

Gets an array of all achievement group IDs and their display name in the game.

Parameters:

  • AchievementGroupsSortField sortBy: The field to sort the achievement groups by.

  • SortDirection sortDirection: The direction to sort the achievement groups by.

Returns: Task<ListedAchievementGroup[]> : The array of all core achievement group information.

Example

var achievementGroups = await CoreServices.ListAllAchievementGroups(
    AchievementGroupsSortField.DisplayName,
    SortDirection.Ascending
);

foreach (var achievementGroup in achievementGroups)
{
    Debug.Log($"Achievement Group: {achievementGroup.DisplayName} (ID: {achievementGroup.Id})");
}

Possible exceptions

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

NotSignedIn

User is not signed in.

AcquireAchievement(string achievementId)

Adds an achievement to the signed-in player's achievements.

Parameters:

  • string achievementId: The ID of the achievement to acquire.

Example

await CoreServices.AcquireAchievement("achievementId");

Possible exceptions

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

NotSignedIn

User is not signed in.

BadRequestException

Exception code (BadRequestExceptionCode)
Meaning

AchievementAlreadyAdded

The achievement has already been acquired.

RemoveAchievement(string achievementId)

Removes an achievement from the signed-in player's achievements.

Parameters:

  • string achievementId: The ID of the achievement to remove.

Example

await CoreServices.RemoveAchievement("achievementId");

Possible exceptions

AuthenticationException

Exception code (AuthenticationExceptionCode)
Meaning

NotSignedIn

User is not signed in.

NotFoundException

Exception code (NotFoundExceptionCode)
Meaning

AchievementNotAdded

The achievement has notot been acquired yet.

SignOut()

Signs out of the current player account.

Example

await CoreServices.SignOut();
Dispose()

Disposes of Sphere Kit, signs out the player and clears all listeners.

Example

await CoreServices.Dispose();
PreviousSecuring your dataNextPlayer

Last updated