User accounts

User accounts A user represents an identity within the server. Every user is registered and has a profile for other users to find and become friends with or join groups and chat.

A user can own records, share public information with other users, and authenticate via a variety of different social providers.

Note: The system owner identity is represented by a user account with a nil UUID (00000000-0000-0000-0000-000000000000).

Fetch account

When a user has a session you can retrieve their account. The profile contains a variety of information which includes various “linked” social providers.

// Client
var account = await client.GetAccountAsync(session);
var user = account.User;
System.Console.WriteLine("User id '{0}' username '{1}'", user.Id, user.Username);
System.Console.WriteLine("User wallet: '{0}'", account.Wallet);

Some information like wallet, device IDs and custom ID are private but part of the profile is visible to other users.

Public Field	Description
user.id	The unique identifier for the user.
user.username	A unique nickname for the user.
user.display_name	The display name for the user (empty by default).
user.avatar_url	A URL with a profile picture for the user (empty by default).
user.lang	The preferred language settings for the user (default is “en”).
user.location	The location of the user (empty by default).
user.timezone	The timezone of the user (empty by default).
user.metadata	A slot for custom information for the user - Read only from the client.
user.edge_count	Number of friends this user has.
user.facebook_id	Facebook identifier associated with this user.
user.google_id	Google identifier associated with this user.
user.gamecenter_id	GameCenter identifier associated with this user.
user.steam_id	Steam identifier associated with this user.
user.create_time	A timestamp for when the user was created.
user.update_time	A timestamp for when the user was last updated.
user.online	A boolean that indicates whether the user is currently online or not.

Private Field	Description
email	Email address associated with this user.
devices	List of device IDs associated with this user.
custom_id	Custom identifier associated with this user.
wallet	User’s wallet - Read only from the client.
verify_time	A timestamp for when the user was verified (currently only used by Facebook).

User metadata

You can store additional fields for a user in user.metadata which is useful to share data you want to be public to other users. We recommend using user metadata to store very common fields which other users will need to see. For example, use metadata to enable users to show biographical details if desired, or to display their character name, level, and game statistics.

For all other information you can store records with public read permissions which other users can find.

Metadata is limited to 16KB per user. This can be set only via the script runtime, similar to the wallet.

The following example showcases using user metadata to store a VIP status which is then used as part of a before join tournament hook which only allows VIP members to join.

// Server
// Assuming a user metadata structure as follows
const metadata = {
  vip: true
};

// Add a before hook to only allow VIP users to join the vip_only tournament
let BeforeJoinTournament: nkruntime.BeforeHookFunction<JoinTournamentRequest> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime, data: nkruntime.JoinTournamentRequest): nkruntime.JoinTournamentRequest | void {
  const account = nk.accountGetId(ctx.userId)

  // Only do the following checks if the tournament id is `vip_only`
  if (data.tournamentId != "vip_only") {
    return data;
  }

  // Only continue with the Join Tournament if the actioning user is a vip
  if (account.user.metadata["vip"]) {
    return data;
  }

  logger.warn("you must be a vip to join this tournament")
  return null;
};

// Register inside InitModule
initializer.registerBeforeJoinTournament(BeforeJoinTournament);

Virtual wallet

MetaFi has the concept of a virtual wallet and transaction ledger. MetaFi allows developers to create, update and list changes to the user’s wallet. This operation has transactional guarantees and is only achievable with the script runtime.

With server-side code it’s possible to update the user’s wallet.

// Server
let user_id = '8f4d52c7-bf28-4fcf-8af2-1d4fcf685592';

let changeset = {
  coins: 10, // Add 10 coins to the user's wallet.
  gems: -5,   // Remove 5 gems from the user's wallet.
};

let metadata = {
  gameResult: 'won'
};

let result: nkruntime.WalletUpdateResult;

try {
    result = nk.walletUpdate(user_id, changeset, metadata, true);
} catch (error) {
    // Handle error
}

The wallet is private to a user and cannot be seen by other users. You can fetch wallet information for a user via Fetch Account operation.

Online indicator #

MetaFi can report back user online indicators in two ways:

1. Fetch user information to see if they are online. The user presence will be detected if they have an active socket connection to the server and did not set appearOnline=false.

2. Publish and subscribe to user status presence updates. This will give you updates when the online status of the user changes (along side a custom message).

Fetch users

You can fetch one or more users by their IDs or handles. This is useful for displaying public profiles with other users.

// Client
var ids = new[] {"userid1", "userid2"};
var usernames = new[] {"username1", "username2"};
var facebookIds = new[] {"facebookid1"};
var result = await client.GetUsersAsync(session, ids, usernames, facebookIds);

foreach (var u in result.Users)
{
    System.Console.WriteLine("User id '{0}' username '{1}'", u.Id, u.Username);
}

Update account

When a user is registered most of their profile is setup with default values. A user can update their own profile to change fields but cannot change any other user’s profile.

// client
const string displayName = "My new name";
const string avatarUrl = "http://graph.facebook.com/avatar_url";
const string location = "San Francisco";
await client.UpdateAccountAsync(session, null, displayName, avatarUrl, null, location);

With server-side code it’s possible to update any user’s profile.