My question has been answered.
Thank you for your kind and detailed explanations every time.

Thanks, that makes sense.

So our takeaway is that brainCloud Friends has no hard-coded friend limit, but very large friend lists can still have performance implications because friend IDs are stored in the UserProfile.

Also, since GetSocialLeaderboard returns all friends and does not support page-based access, it seems risky for us to allow very large mutual friend counts if we want to use Friends-based leaderboards for normal users.

We will discuss internally whether we should enforce product-level limits on following/follower or mutual friend counts, and reserve special handling, such as shadow leaderboards, for high-degree or influencer-like accounts.

Thanks again for the detailed guidance!

Thank you for your response.

We used the automated promotion without making any changes to it. However, we confirmed that it works correctly in the production app.

It seems that the issue may have been temporary, or that there was something incorrect in our configuration at the time. If the issue occurs again, we will contact you again with more details.

Thank you for your help.

Hi brainCloud team,

We are seeing an issue where an Automated Promotion that previously worked correctly no longer activates under the same conditions.

The promotion we are testing is configured as follows:

• App ID: 15389
• Promotion ID: 6
• Promotion Type: Automated Promotion
• Applicable members: currently set to Both existing and new entrants to the segment
• Target Segment: XP level based segment

This promotion was configured about a month ago, and from the beginning its Applicable members setting was New entrants to the segment only. It previously worked correctly with that setting.

Previously, when a new user progressed in the game and newly satisfied the XP level condition for the target segment, the Automated Promotion became eligible and was shown correctly on the client.

Recently, however, the promotion no longer activates with the same setting and the same flow. We have currently changed it to Both existing and new entrants to the segment as a temporary workaround for testing.

Current reproduction flow:

1. Start with a new user
2. The user starts in a state where they do not satisfy the target segment condition
3. The user progresses in the game and satisfies the XP level condition
4. In the brainCloud console, the user is confirmed to be included in the target segment
5. However, Promotion ID 6 does not appear in Eligible Promotions
6. If we change the same promotion’s Applicable members setting to Both existing and new entrants to the segment, it immediately becomes eligible

So it looks like the user is correctly entering the target segment due to an XP level change, but the Automated Promotion is not being associated/activated when using New entrants to the segment only.

We also noticed this related forum thread mentioning a similar issue and a patch:

https://forums.getbraincloud.com/topic/355/automated-promotion-not-associated-for-users-already-in-target-segment

Could you please confirm the following?

1. Is New entrants to the segment only expected to activate when a user newly satisfies a segment condition due to an XP level change?
2. Since this used to work before but no longer works with the same configuration and flow, could this be related to a recent patch or a change in promotion/segment association logic?
3. After updating XP level, is there any additional refresh or reevaluation step required besides calling RefreshPromotions?
4. As a workaround, Both existing and new entrants to the segment works. Is this the recommended setting, or should New entrants to the segment only still work for this case?

Thank you.

Hi @JasonL and @Paul-Winterhalder ,

Thank you both for the detailed clarification.

We now understand the usage calculation as follows:

• The client script.RUN call counts as +1 API count.
• The script.RUN Pre-hook execution counts as an additional +1 API count / CloudCode invocation.
• bridge.getGlobalProperty() does not count as an API call because it reads from the cached Game object.
• The original CloudCode script execution is covered by the original script.RUN request.
• Therefore, both the pass-through and blocked cases count as 2 API counts before considering any internal bridge.callAPI() calls from the original script.

Also, thank you for correcting the CloudCode internal API call rule. We will treat the current rule as “the first 2 API calls are free in a script, and every call after that is 1/2 API count,” not “first 3 free.”

One follow-up question:

If a script.RUN request has a Pre-hook and then the original CloudCode script runs, how is the “first 2 API calls are free” rule applied to internal bridge.callAPI() calls?

Is the free-call allowance applied separately per CloudCode script invocation, for example:

• Pre-hook CloudCode script: first 2 internal API calls are free
• Original CloudCode script: first 2 internal API calls are free

Or is the allowance shared across the whole request/session chain, including both the Pre-hook and the original CloudCode script?

For our current version-gate Pre-hook, we only call bridge.getGlobalProperty(), so this does not affect that hook directly. However, we would like to understand the calculation correctly in case the Pre-hook or the original script uses bridge.callAPI() in the future.

Regarding the “first 3 API calls are free” reference, I may have seen it in an older document or cached/search result. I will try to find the exact source and share it if I can locate it.

Thanks again.

Yes, that is the right question. The 10K number is not the expected case for every regular player. It is more of a worst-case upper bound for high-degree / influencer-like accounts in our social graph.

For regular players, we expect the friend count to be much smaller, likely under 100, and most users would probably be under 20. For those users, using brainCloud Friends with GetSocialLeaderboard / GetMultiSocialLeaderboard should be fine.

For the exceptional high-degree accounts, we expect the number to be limited at first, probably under 50. Your shadow leaderboard suggestion makes sense to us.

To confirm, would the recommended architecture be:

• Keep posting every player’s score to the main leaderboard.
• Tag high-degree / influencer-like accounts separately.
• For each tagged account, maintain a separate shadow leaderboard containing only that account’s friend scores.
• When a friend’s score changes, mirror that score into the relevant shadow leaderboard through Cloud Code.
• Use the normal global leaderboard paging APIs on the shadow leaderboard to support rank 1-50, 51-100, 101-150, etc.

A few details we would like to confirm:

1. Is GetGlobalLeaderboardPage on the per-influencer shadow leaderboard the intended way to support paging for these large friend lists?
2. For rotated leaderboards, should each shadow leaderboard use the same rotation settings as the main leaderboard?
3. Is there a practical recommended maximum number of shadow leaderboards or mirrored score writes we should design around?
4. Would increasing maxMultipleLeaderboardScoreLimit still only be needed for the regular top-N social leaderboard path, and should that be requested through brainCloud Support?

If this is the preferred pattern, we will design the normal-player path and high-degree-player path separately instead of trying to page through up to 10K friends with GetSocialLeaderboard.

Thanks!

Hello,

We are planning to use a CloudCode script.RUN API Pre-hook to enforce a client app version gate.

The flow is as follows:

1. The client calls ScriptService.RunScript once.
2. A script.RUN Pre-hook runs our Pre_VersionGate CloudCode script.
3. Inside Pre_VersionGate, we call bridge.getGlobalProperty("VERSION_POLICY") once.
4. If the policy allows the request, the original CloudCode script runs.
5. If the policy blocks the request, the Pre-hook returns 403 and the original script does not run.

We would like to confirm how this affects usage and billing.

Questions:

1. Does the script.RUN Pre-hook execution count as a separate CloudCode execution or API count in addition to the original RunScript call?
2. Does bridge.getGlobalProperty("VERSION_POLICY") inside the Pre-hook count as an API call / usage count?
3. The CloudCode documentation mentions that the first 3 API calls are free and each call after that counts as 1/2. Does this rule apply to API Hook CloudCode scripts as well?
4. In the normal pass-through case, how is the usage count calculated?
   • 1 client RunScript call
   • 1 Pre-hook execution
   • 1 getGlobalProperty call inside the Pre-hook
   • 1 original CloudCode script execution
5. In the blocked case, the original CloudCode script does not run. How is the usage count calculated in that case?
6. Could reading a Global Property on every script.RUN call become a performance or cost concern?
7. For a version policy that is read frequently but changed rarely, is there a recommended caching approach in BrainCloud?
8. Are there any Portal or usage report metrics where we can separately check the following?
   • API Hook execution count
   • CloudCode script execution count
   • CloudCode internal API call count
   • Global Property read count

We do not have an exact traffic estimate yet, so for now we would like to understand how usage count is calculated for this structure.

Thank you.

Hi,

Thank you for guiding me on how to check it.

I verified the indexes for the FOLLOW entity using CustomEntity > SysListIndexes in the API Explorer, and confirmed that unique: true is correctly applied to the followerId_followingId index.

The confirmed response is as follows:

{
  "name": "followerId_followingId",
  "key": {
    "data.followerId": 1,
    "data.followingId": 1
  },
  "background": true,
  "unique": true
}

Thank you for your help!

Hello,

Thank you for your reply and for adding the option to the FOLLOW entity.

I checked the custom index settings again, but I still cannot see the added option on my side.

In the FOLLOW entity, under Custom Indexes > followerId_followingId > Options, I only see the following:

{
  "name": "followerId_followingId"
}

Could you please let me know if there is another place where I should check this option, or if there is any additional step required for it to appear?

Thank you.

Hello, thank you for the clarification.

Based on your answer, I understand the following:

• GetSocialLeaderboard returns the full set of friends + self + pacers, and there is no hidden max result limit.
• GetMultiSocialLeaderboard can return only the Top N results using leaderboardResultCount, after social filtering and score sorting.
• However, there is no page/offset-based pagination API for social leaderboards like GetGlobalLeaderboardPage.
• leaderboardResultCount is limited by the app property maxMultipleLeaderboardScoreLimit, whose default value is 10.
• Friend IDs are stored as an array in the UserProfile, so very large friend lists may affect read/write performance.

I have two follow-up questions:

1. How can we increase the maxMultipleLeaderboardScoreLimit value?
   Is this app property something we can change directly in the Console, or does it require a request to brainCloud Support?
   If a Support request is required, could you let us know what information we need to provide and whether there is a recommended maximum value?

2. We are planning to build a friends-based social leaderboard for up to around 10,000 friends.
   In this case, is the recommended approach to call GetSocialLeaderboard, retrieve the full friends leaderboard, and then handle paging on the client/server side?
   Or, at this scale, would you recommend using a separate Custom Entity, Cloud Code, external ranking cache, or another leaderboard structure instead?

To clarify, our requirement is not just to fetch the Top 50 users.
We want to continuously page through a friends-based leaderboard like this:

rank 1–50
rank 51–100
rank 101–150
...

Based on your previous answer, I understand that social leaderboard pagination is currently not supported.
Could you please advise on the recommended architecture or best practice for implementing this kind of UX with a friends leaderboard of up to 10,000 users?

Thank you.

Hello brainCloud team,

We would like to request a unique compound index for our Custom Entity type FOLLOW.

Our App ID is 15389.

The FOLLOW entity stores follow relations with the following data shape:

{
  "followerId": "profileId_A",
  "followingId": "profileId_B",
  "createdAt": 1770000000000
}

We want to prevent duplicate follow relations for the same follower/following pair.

Entity Type: FOLLOW

Unique index name: followerId_followingId_unique

Keys:

{ "data.followerId": 1, "data.followingId": 1 }

Options:

{ "unique": true, "background": true }

We already have a non-unique index with the same key pattern:

Index name: followerId_followingId

Keys:

{ "data.followerId": 1, "data.followingId": 1 }

If needed, please replace this existing non-unique index with the unique version.

This feature has not been released to production yet, so we can clean up or reset the FOLLOW data before the unique index is applied if necessary.

We also have a few questions:

1. If this unique index is manually added to the Development app, will it be included automatically when we deploy or migrate to Staging/Production?
2. Or does this unique index need to be manually applied per app/environment?
3. If it must be applied per environment, can we provide the appIds for Development, Staging, and Production so you can add the same index to each app?
4. Are manually added Custom Entity indexes included in brainCloud deploy/migrate/export-import workflows?
5. If there are existing duplicate rows for the same data.followerId + data.followingId pair, will the unique index creation fail?
6. Is there any expected downtime, lock, write failure, or performance impact while this index is being created?
7. After the index is applied, what is the recommended way to verify that the unique index exists in each environment?

Thank you.

Context

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.

Hello BrainCloud Support Team,

I would like to ask about using unique indexes with Custom Entities.

We are currently using Custom Entity with the entityType FOLLOW, and we tried to create an index named test_index with the unique option enabled.

However, the following error occurred:

Error Code: 3010308
Error Message: Error adding custom entity index test_index for entityType FOLLOW
Exception: Index cannot be created with 'unique' option as prevents sharding of custom collection.
Exception message: Index cannot be created with 'unique' option as prevents sharding of custom collection.

We would like to prevent duplicate values for a specific field in this Custom Entity.

Could you please confirm whether Custom Entity indexes support the unique option?

If unique indexes are not supported due to sharding, could you recommend the best alternative approach to enforce uniqueness for a field in Custom Entity?

Thank you.

Best regards,
Gyutae Lee

Thank you for your kind response.

Hello BrainCloud team,

I previously posted a question about when the timer starts for users who already meet the conditions of a newly deployed Automated Promotion.

After testing this again, we found that if a user already satisfies the Promotion conditions, the Promotion duration appears to start counting from the deployment time, even if the user does not log in. In other words, the Promotion timer seems to be based on backend timing, regardless of whether the client has connected.

Our desired behavior is that, for offers such as starter packages, the Promotion duration should start only after the user actually logs in. For example, even if a user already meets the conditions, we would like the Promotion to remain active for 24 hours, or for the configured duration, starting from the user’s first login after the Promotion is deployed.

The solution we are currently considering is to refresh or reset the Promotion duration from the client when the user logs in. However, based on what we have checked so far, there does not seem to be an API available for this.

Is there any recommended way to support this use case with Automated Promotions?
If there is a better approach than refreshing or resetting the Promotion duration from the client, we would appreciate your guidance.

Thank you for your help.

@Paul-Winterhalder , could you please respond to @noah 's inquiry?

Thanks for the reply.

I checked the Deployment settings and tested the behavior, but it looks like there is currently no option to prevent Promotions from being overwritten during deployment.

The available “Do Not overwrite product/pricing information” option does not seem to apply to Promotions.

Thanks again for checking this.

Thank you for your kind response as always.
Have a great day!

Hello,

We're currently using the Deployment feature to propagate configuration from our dev environment to staging and production. We noticed that the deployment options allow us to exclude certain categories (e.g., Item Catalog, Leaderboards, Global Entities), which is very helpful.

However, we ran into an issue: a "Remove Ads" promotion that only exists in our dev environment was accidentally deployed to staging, and it immediately triggered a popup for users because the promotion conditions were met right away.

We'd like to ask:

1. Is there currently any way to exclude specific promotions (by name or ID) from a deployment, similar to how individual Custom Entities can be controlled per-record?

2. If this is not currently supported, would it be possible to add a per-promotion deployment toggle — similar to the Custom Entities behavior — as a feature request?

As a workaround, we're manually deleting the unwanted promotion from staging/production after each deployment, but this is error-prone and easy to miss.

Thank you!

Hi BrainCloud team, we have two questions about features we're trying to build.

---

1. One-Way Follow

We want Player A to follow Player B, but B doesn't have to follow back.

The Friend API requires both players to agree, so it doesn't work for us.
Is there a BrainCloud API designed for one-way follow relationships?

Also — can GetPresenceOfUsers(profileIds[]) fetch profile data for any player,
or does a Friend relationship need to exist first?

---

2. Referral Rewards for Both Players

Our referral flow:

1. Player A shares their referral code
2. Player B enters the code
3. When B reaches level 3, both A and B receive a diamond reward

The challenge is rewarding A (the referrer). We store A's profile ID in a
Custom Entity when B registers the code, so we always know who referred whom.

Two questions:

a) Does BrainCloud support running a CloudCode script when a Milestone is
completed? If yes, we could use a Milestone to reward B automatically at
level 3, and use that script to look up A's profile ID and reward A as well —
no client-side trigger needed.

b) If not, is there any other server-side mechanism in BrainCloud that can
reward a different player when a specific event occurs?

---

Thanks!