Friend Reference #

Friend service SDK #

The table below contains a list of the SDK methods relevant to the Friend service. These methods are available via the FriendApi.

Call	description
`AcceptFriendInvite`	Accept a friend invite. Inviter and invitee are added to each other’s friend list
`Block`	Allow a player top block another player from sending them invites by adding them to a blocklist
`DeclineFriendInvite`	Decline a friend invite
`DisableIncomingFriendInvites`	Do not allow a player to receive friend invites
`EnableIncomingFriendInvites`	Allow player to receive friend invites
`ForceSync`	Forcibly synchronize the player client FriendApi with the friend information in the Pragma Engine backend
`GetFriends`	Retrieve a list of Friend objects in a player’s friend list
`GetReceivedInvites`	Retrieve a list of Friend Overview objects representing players whose friend invites you have not yet accepted/rejected
`GetSentInvites`	Retrieve a list of Friend Overview objects representing players who have not responded yet to your friend invites
`Initialize`	Initialize the Friend API. Required to use the Friend SDK functions.
`RemoveFriend`	Remove a friend from your friend list using the friend’s social ID
`SendFriendInviteByDisplayName`	Send an invite using the invitee’s display name
`SendFriendInviteBySocialId`	Send an invite using the invitee’s social ID
`Unblock`	Remove a player from another player’s blocklist, allowing the unblocked player to send the unblocker friend invites

Data classes #

Friend class #

property	description
`socialId`	Unique social identifier for the player (game agnostic)
`displayName`	`PragmaDisplayName` object containing the player’s name and discriminator
`playerId`	A user’s identifier within a specific game
`playerIdByGameShard`	Map of player’s playerIds by game shard
`presence`	Presence for the player in a specific game
`presencesByGameShard`	Presences for the player across games
`providerAccountsByProviderId`	User’s `IdProviderAccount`s, which contain account information from identity providers. For specifics on the `IdProviderAccount` data class, see the Account Plugin topic.

Friend Overview class #

An overview of the Friend without sensitive information.

property	description
`socialId`	Unique social identifier for the player (game agnostic)
`displayName`	`PragmaDisplayName` object containing the player’s name and discriminator
`playerId`	A user’s identifier within a specific game
`playerIdByGameShard`	Map of player’s playerIds by game shard

Configuration #

FriendsServiceConfig #

The FriendsServiceConfig configuration block provides a place to define default values for the Friend and Presence services.

Note about GDPR compliance: Setting your maxTimeBetweenAccessMillis to a value over 30 days (2592000000 milliseconds) may result in GDPR noncompliance, as user data may exist in the cache until maxTimeBetweenAccessMillis is reached.

The following configuration values are related to Friends features:

config	description
`maxFriendsListSize`	Maximum number of friends an individual player can maintain Default: 400
`maxPendingSentInvites`	Maximum number of pending (unresponded to) sent invites an inviter can maintain before oldest pending invites are removed to make room for newer invites. If a player attempts to send a friend invite when their pending sent invite list is full, the oldest pending sent invite in their list will be deleted. A “sent invite removed” event is triggered for the inviter, and a “received invite removed” event is triggered for the invitee. Default: 20
`maxPendingReceivedInvites`	Maximum number of pending (unresponded to) received invites a player can maintain before subsequent invites are automatically rejected. If a player attempts to send a friend invite to a player whose received invites list is full, the inviter will receive an INVITEE_RECEIVED_INVITES_FULL error. Default: 20

See Presence Reference for information on other configuration values.

friendListCacheConfig #

The friendListCacheConfig configuration block within the FriendsServiceConfig block defines values for caching behavior for the friend service database.

config	description
`maxTimeBetweenAccessMillis`	If an entry has not been accessed in this amount of time, it is a candidate for removal in the next eviction sweep. See note above about GDPR compliance. Default: 72000000
`sizeBeforeExpirationEnforced`	Maximum size of the `friendListCache`, after which eviction sweeping will start removing entries Default: 50000
`sweepIntervalMillis`	Interval, in milliseconds, between sweep calls for the `friendListCache` Default: 900000

identityCacheConfig #

The identityCacheConfig configuration block within the FriendsServiceConfig block defines values for caching player identity data retrieved from the account service.

config	description
`maxTimeBetweenAccessMillis`	If an entry has not been accessed in this amount of time, it is a candidate for removal in the next eviction sweep. See note above about GDPR compliance. Default: 1800000
`sizeBeforeExpirationEnforced`	Maximum size of the `identityCache`, after which eviction sweeping will start removing entries Default: 500000
`sweepIntervalMillis`	Interval, in milliseconds, between sweep calls for the `identityCache` Default: 90000

Events #

There are several friend-related events that player clients can listen to. The following table describes the bindable events relevant to the Friend service.

The following events are handled by the player client.

Event	Trigger	Data returned
`OnFriendsListChanged`	A friend is added or removed from a player’s friend list, or a friend’s presence status changes	list of Friends on your friend list
`OnFriendUpdated`	A friend’s presence status changes	Friend
`OnSentInvitesChanged`	The status of a sent invite changes	list of FriendOverviews for pending sent invites
`OnReceivedInvitesChanged`	The status of a received invite changes	list of FriendOverviews for pending received invites
`OnBlockedListChanged`	An account is added or removed from the player’s blocklist.	list of FriendOverviews for accounts on your blocklist
`OnFriendInviteReceived`	A player receives an invite	FriendOverview
`OnFriendInviteAccepted`	An invitee accepts a friend invite	FriendOverview
`OnFriendInviteDeclined`	An invitee declines a friend invite	FriendOverview
`OnRemovedAsFriend`	A player is removed from another player’s friend list	Friend
`OnIncomingFriendInvitesEnabledChanged`	A player’s ability to receive invites changes	boolean

If notifications from the engine are received out of order due to a network issue, the friend cache will automatically refresh and the ‘On Changed’ events will be broadcasted.

Errors #

FriendService_InternalError
Friend_InviteNotFound
Friend_FriendNotFound
Friend_InviteeAlreadyFriend
Friend_FriendListFull
Friend_InviteeReceivedInvitesFull
Friend_FriendUpdateFailed
Friend_BlockedByInvitee
Friend_InviteeIsBlocked
Friend_InviteeDisabledInvites
Friend_SelfOperationNotAllowed
Friend_SocialIdentityNotFound
Friend_GameIdentityNotFound