Thanks Paul, that makes sense.

For now, we’ll keep using a dedicated internal/service profile with getSessionForProfile() + callAPIForSession() as a temporary workaround for our monthly transaction reporting job.

Could you please confirm whether this workaround is safe to use temporarily in production, as long as we do not include a profileId in the search criteria and only use the session to authorize the request?

Also, we’d appreciate it if you could let us know once the S2S proxy hookup for SYS_GET_TRANSACTIONS_PAGE has been reviewed or fixed.

Thanks again for checking into this.

Hi brainCloud team,

We are implementing an internal monthly revenue settlement tool and need to retrieve App Store IAP transactions for a specific month.

We observed different behavior depending on how the Cloud Code script is executed.

Environment

• App: dev
• Cloud Code script: S2S callable
• Service: appStore
• Operation: SYS_GET_TRANSACTIONS_PAGE

Case 1: S2S script/RUN without a player session

Our backend calls the Cloud Code script through S2S script/RUN.

Inside the script, we tried:

var appStoreProxy = bridge.getAppStoreServiceProxy();
var response = appStoreProxy.sysGetTransactionsPage({
  pagination: { rowsPerPage: 50, pageNumber: 1 },
  searchCriteria: {
    type: "itunes",
    pending: false,
    createdAt: { "$gte": monthStart, "$lt": monthEnd }
  },
  sortCriteria: { createdAt: -1 }
});

This failed with:

Processing exception: Unrecognized request: service=appStore, operation=SYS_GET_TRANSACTIONS_PAGE.

Case 2: Same script from the brainCloud console after Quick Auth

When we ran the same Cloud Code script from the brainCloud web console, after Quick Auth created a player session, the request succeeded.

Case 3: S2S script/RUN, but the script creates a player session explicitly

We changed the script to create a session from a known dedicated service profileId:

var userSession = bridge.getSessionForProfile(sessionProfileId);
var response = bridge.callAPIForSession(userSession, "appStore", "SYS_GET_TRANSACTIONS_PAGE", {
  context: {
    pagination: { rowsPerPage: 50, pageNumber: 1 },
    searchCriteria: {
      type: "itunes",
      pending: false,
      createdAt: { "$gte": monthStart, "$lt": monthEnd }
    },
    sortCriteria: { createdAt: -1 }
  }
});

This succeeded.

Questions

1. Is SYS_GET_TRANSACTIONS_PAGE expected to require a player session, even when called from S2S Cloud Code?
2. Is there an official or recommended way to retrieve app-wide IAP transactions for a monthly settlement report without using an arbitrary player profile session?
3. If a player session is required, is it safe to use a dedicated internal/service profileId and omit profileId from searchCriteria to retrieve app-wide transactions?
4. Is the Unrecognized request error expected in this case, or should this be reported as a bug, permission issue, or app configuration issue?

Thanks.

Thank you for your helpful response.

Unfortunately, since this feature does not align with the specifications we are currently planning, we have decided not to use it for the time being.

We will contact you again if we need it in the future.
Thank you.

@Paul-Winterhalder @JasonL

I have a few additional questions.

1. Is there any plan or possibility to support pagination for GetSocialLeaderboard or other social leaderboard APIs?

We are considering cases where some high-degree / influencer-like users may have 10,000+ friends.

In that case, retrieving the full friends leaderboard at once could increase response size and server load. We would like to know whether there is a way to retrieve the friends leaderboard in ranges such as rank 1-50, 51-100, 101-150, etc.

2. If social leaderboard pagination is not feasible, would it be possible to raise maxMultipleLeaderboardScoreLimit to 100?

As an alternative, we are considering a design where we retrieve the Top 100 friends by score for the current user.

We are considering using:

GetMultiSocialLeaderboard([leaderboardId], 100, replaceName)

If 100 is not possible, could you let us know the maximum value that would be available?

3. Is there any API or recommended approach to retrieve only the current player’s own rank and score within their friends leaderboard without retrieving the full friends leaderboard?

For example, we are considering showing a separate “My Rank” row in the UI in addition to the Top 50 or Top 100 list.

Thank you.

@Paul-Winterhalder Thank you!

Hello @JasonL @Paul-Winterhalder ,

I have an additional request.

Could you please apply the unique: true option to the following two indexes on the Custom Entity REFERRAL_CODE for App ID 15389?

• code
• referrerId

It would be appreciated if you could keep the existing index names and key patterns unchanged, and only add the unique option.

Thank you for your help.

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