Friend Service Tasks #

Common objectives you can achieve using the Friend Service include:

Pragma currently supports the Friend API in the Unreal SDK. Unity implementation is available through FriendServiceRaw.cs.

Initialize the Friend service (Required) #

Before you can issue any Friend service calls using the Friend API, you must initialize the service using the Friend API Initialize method. This step will synchronize friend states between the SDK and the Pragma backend.

Upon logout, the service is un-initialized. You must call initialize() on the service when you log back in.
Player->FriendApi().Initialize(
    FOnCompleteDelegate
);

The Initialize method triggers the OnChanged events, providing you with a list of friends and invites. After you receive a successful response, you can begin using the Friend service API.

While the Pragma SDK constantly attempts to stay in sync with the Pragma Engine backend, there may be instances where you want to explicitly force the Friend API to sync with the backend data. To forcibly synchronize the client’s state with the platform, call the Unreal PragmaFriendApi ForceSync function.

Initializing the Friend service is also required if you want to use the Presence feature.

Related events:

Related errors:

Configure maximum pending sent or received invites #

Developers can set a maximum number of sent or received invites a player can have in a pending state at one time. When a pending sent or received invite is accepted, rejected, or canceled, the player can again send or receive invites.

serviceConfigs:
  FriendServiceConfig:
    ...

Send a friend invite #

A player can send an invite to another player using the player’s social ID or display name. Social IDs and display names may be visible in game instances, on leaderboards, or communicated through methods outside of Pragma, such as via social media. Developers can access the SocialId and DisplayName via the Unreal UPragmaPartyPlayer object. Pragma recommends sending invites by socialId if possible because display names can easily change. However, display names may be preferable if manually typing in a value.

When called, SendFriendInviteByDisplayName and SendFriendInviteBySocialId add a pending sent invite to the inviter’s friend list, and a pending received invite to the invitee’s friend list.

Players cannot send invites to players if they are on the player’s blocklist. Similarly, you cannot send a friend invite to an account on your blocklist. Doing so will result in a Friend_InviteeIsBlocked error.

If a player’s number of pending sent invites is at its max, the oldest pending sent friend invite is removed to make room for the new one. If a player’s received invites list is full, the inviter will receive a Friend_InviteeReceivedInvitesFull error.

Invites do not expire.

Send a friend invite by social ID #

To send a friend invite using the invitee’s social ID, use the Friend API’s SendFriendInviteBySocialId method.

Player->FriendApi().SendFriendInviteBySocialId(
    SocialId,
    FOnCompleteDelegate
);

SendFriendInviteBySocialIdV1(SendFriendInviteBySocialIdV1Request request,
            Protocol.OnComplete<SendFriendInviteBySocialIdV1Response> callback)

{
    "requestId": 1,
    "type": "FriendRpc.SendFriendInviteBySocialIdV1Request",
    "payload": {
        "inviteeSocialId": "9c82f3d5-5857-4f93-a07f-f6bb38fd9aba"
    }
}

Send a friend invite by display name #

To send a friend invite using the invitee’s display name, use the Friend API’s SendFriendInviteByDisplayName method.

Player->FriendApi().SendFriendInviteByDisplayName(
    DisplayName,
    FOnCompleteDelegate
);

SendFriendInviteV1(SendFriendInviteV1Request request,
            Protocol.OnComplete<SendFriendInviteV1Response> callback)

{
    "requestId": 1,
    "type": "FriendRpc.SendFriendInviteV1Request",
    "payload": {
        "inviteeDisplayName": {
            "displayName": "test02",
            "discriminator": "9165"
        }
    }
}

Related events:

Related errors:

Accept a friend invite #

To accept a friend invite, use the Friend API’s AcceptFriendInvite method with the inviter’s socialId. When accepted, the inviter and invitee are added to each other’s friend list.

Player->FriendApi().AcceptFriendInvite(
    InviterSocialId,
    FOnCompleteDelegate
);

RespondToFriendInviteV1(RespondToFriendInviteV1Request request,
            Protocol.OnComplete<RespondToFriendInviteV1Response> callback)

{
    "requestId": 1,
    "type": "FriendRpc.RespondToFriendInviteV1Request",
    "payload": {
        "inviterSocialId": "9c82f3d5-5857-4f93-a07f-f6bb38fd9aba",
        "acceptInvite": true
    }
}

To view pending friend invites, use GetReceivedInvites.

Related events:

Related errors:

Decline a friend invite #

To decline a friend invite, use the Friend API’s DeclineFriendInvite with the inviter’s social ID.

Player->FriendApi().DeclineFriendInvite(
    InviterSocialId,
    FOnCompleteDelegate
);

RespondToFriendInviteV1(RespondToFriendInviteV1Request request,
            Protocol.OnComplete<RespondToFriendInviteV1Response> callback)

{
    "requestId": 1,
    "type": "FriendRpc.RespondToFriendInviteV1Request",
    "payload": {
        "inviterSocialId": "9c82f3d5-5857-4f93-a07f-f6bb38fd9aba",
        "acceptInvite": false
    }
}

To view pending friend invites, use GetReceivedInvites.

Related events:

Related errors:

Block or unblock accounts #

Developers can allow players to block and unblock friend invites from a specific account.

Blocking invites works on the account level. Thus, blocking another player prevents them from sending invites across all game shards.

Block single account #

The Friend API’s Block allows a player to block friend invites sent by a specific account. When a player blocks an account, the specified account, identified by the socialId, is added to the blocker’s block list. Any pending invitations from the blocked account are automatically deleted. If the players are friends, Pragma Engine removes each player from the others’ friend list before blocking.

Unreal:

Player->FriendApi().Block(
    SocialId
    FOnCompleteDelegate
);

If a blocked player attempts to send a friend invite, they receive the Friend_BlockedByInvitee error.

Unblock single account #

The Unblock method allows a player to unblock an account on their block list. The specified account, identified by the socialId, is removed from the issuing player’s block list and can send them friend invites. If the blocked player was a friend before being blocked, the friend status is not restored.

Unreal:

Player->FriendApi().Unblock(
    SocialId
    FOnCompleteDelegate
);

View block list #

The GetBlockedList method returns all accounts on a player’s block list.

Unreal:

Player->FriendApi().GetBlockedList();

Related events

Related errors:

Disable or enable all incoming friend invites #

Developers can allow players to disable or enable all incoming invites from any account using the DisableIncomingFriendInvites and EnableIncomingFriendInvites methods. By default, all players can receive invites.

Disabling or enabling incoming invites does not add or remove accounts from a player’s block list.

To disable all incoming invites, use DisableIncomingFriendInvites. Players who attempt to send friend invites to accounts that have incoming invites disabled will receive the Friend_InviteeDisabledInvites error.

Unreal:

Player->FriendApi().DisableIncomingFriendInvites(
    FOnCompleteDelegate
);

To enable all incoming invites, use EnableIncomingFriendInvites:

Unreal:

Player->FriendApi().EnableIncomingFriendInvites(
    FOnCompleteDelegate
);

To view the current enabled/disabled status, use AreIncomingInvitesEnabled:

Unreal:

Player->FriendApi().AreIncomingInvitesEnabled();

Related events

Related errors:

View friend lists and invite data #

You can access friend list and invite data in the following ways:

  • Listen to events that communicate friend and invite information:

    • OnFriendListChanged
    • OnSentInvitesChanged
    • OnReceivedInvitesChanged
    • OnBlockedListChanged
    • OnIncomingFriendInvitesEnabledChanged

  • Use the following Get methods:

    • Unreal:
      • GetFriends
      • GetSentInvites
      • GetReceivedInvites
      • GetBlockedList
    • Unity:
      • GetFriendListV1

    See: Friend SDK methods and Friend events for more details.

Remove a friend #

To remove a player from your friend list, use the Friend API’s RemoveFriend with the player’s social ID. This call removes each player from the other player’s friend list.

Player->FriendApi().RemoveFriend(
    SocialId
    FOnCompleteDelegate
);

RemoveFriendV1(RemoveFriendV1Request request,
            Protocol.OnComplete<RemoveFriendV1Response> callback)

{
    "requestId": 1,
    "type": "FriendRpc.RemoveFriendV1Request",
    "payload": {
        "friendSocialId": "9c82f3d5-5857-4f93-a07f-f6bb38fd9aba"
    }
}

Related events:

Related errors:


Friends
Friend Reference