Hello brainCloud team,

We are designing a follow/friend system for our game and would like to confirm a few details before implementation.

Our intended model is:

• We maintain our own FOLLOW Custom Entity as the source of truth.
• A game “friend” is defined only when two users follow each other mutually.
• When mutual follow is established, we plan to call FriendService.AddFriends([targetProfileId]).
• When either side unfollows, we plan to call FriendService.RemoveFriends([targetProfileId]).
• We may later use brainCloud Friends as an optimized source for social leaderboards.

Questions

1. Friend Relationship Direction

Are AddFriends and RemoveFriends bidirectional for internal brainCloud friends?

• If user A calls AddFriends([B]), will B also see A in ListFriends("brainCloud")?
• Will both A and B see each other in GetSocialLeaderboard results if they both have leaderboard scores?
• If A calls RemoveFriends([B]), is the friend relationship removed from both users?

2. Idempotency

Are AddFriends and RemoveFriends idempotent?

• What happens if AddFriends([B]) is called when A and B are already friends?
• What happens if RemoveFriends([B]) is called when they are not friends?

3. Consistency and Caching

Are friend changes immediately visible?

• After AddFriends or RemoveFriends, should ListFriends("brainCloud") and GetSocialLeaderboard reflect the change immediately?
• Or is there any eventual consistency or caching delay we should expect?

4. Friend Count Limits

Is there a hard or recommended limit for the number of brainCloud friends per user?

• We could not find a documented hard cap.
• Are there practical performance limits we should design around?

5. GetSocialLeaderboard Behavior With Many Friends

How does GetSocialLeaderboard behave when a user has many friends?

• Does it return all recognized friends plus self, with no paging or limit?
• Is there any hidden maximum result count or payload limit?
• Are pacers included in this result as well?

6. Recommended API for Top-N Friend Leaderboards

What is the recommended API for a top-N friends leaderboard?

• Can we use GetMultiSocialLeaderboard([leaderboardId], leaderboardResultCount, replaceName) with a single leaderboard ID?
• Is leaderboardResultCount applied after social filtering and score sorting?
• Is there a maximum allowed value for leaderboardResultCount?
• Is this API preferred over GetSocialLeaderboard when we only need the top 50 friends?

7. Social Leaderboard Pagination

Is regular pagination supported for social leaderboards?

• We found GetGlobalLeaderboardPage for global leaderboards, but did not find an equivalent offset/page API for social leaderboards.
• Is there any supported way to retrieve friend leaderboard entries 51-100, 101-150, etc., without requesting all prior entries?

8. Billing and API Counts

Is GetSocialLeaderboard counted as one API call regardless of the number of friends returned?

• Are there additional billing or performance considerations based on response size or number of leaderboard entries returned?

9. Recommended Usage

Are brainCloud Friends suitable as an app-specific “mutual follow friend cache”?

• We will not use brainCloud Friends for unrelated gameplay relationships.
• We plan to keep FOLLOW as our source of truth and use brainCloud Friends only as a derived mirror/cache for mutual follow relationships.
• Does this align with recommended brainCloud usage?

Thank you.