Developer FAQ

Last updated on December 5, 2024

This article contains common developer questions and answers when building a game using AccelByte Gaming Services (AGS).

Admin Portal​

  1. How can I view all the players in my namespace?

    Navigate to Admin Task > Admin Management and change the Search User entry to by Creation Date. Then, set the date to a time before your namespace was created.

  2. How can I add other people to the Admin Portal?

    If you are a super admin in the AGS Admin Portal, go to your publisher namespace and navigate to Admin Task > Admin Management. From there, input the email addresses of your invitees and set them up as a super admins, game admins, or any other of the roles available.

  3. What is the difference between a Fulfillment and an Entitlement Grant?

    Fulfillments will actually invoke an entitlement grant, but the main difference is that a fulfillment will have the transaction information logged on the fulfillment tab of the Admin Portal. This allows you and your team to keep track of all the entitlements being granted.

  4. What is the Log Viewer?

    The Log Viewer is a tool built into the Admin Portal that allows you to see API calls made to the back end. There are filters to examine Trace ID, User ID, Response Status Code, and many more. The filters can also be used in tandem with each other. It can be accessed in the Admin Portal by going to Platform Configurations > Log Viewer.

  5. When uploading a Server Image, can we see the upload progress and the remaining upload time?

    The ability to see the Server Image upload progress and remaining upload time is not currently available. Only the build status viewable.

  6. Will a user's presence availability change to Offline as soon as they disconnect from a Lobby?

    Yes, it is immediately reset unless keepPresenceActivityOnDisconnect is enabled in the Lobby setup in the Admin Portal.

AGS architecture and behavior​

  1. What is the expected behavior of a service if it fails to get or refresh its access token? Should we just kill the service and let Kubernetes restart it, or should we keep retrying?

    It is recommended retrying at least once before throwing an error to the service side.

  2. Does the AGS OSS support Blueprints?

    By design, the AGS OSS doesn't support Blueprints. To use OSS in Blueprints, you will need a custom configuration by using plugins and/or creating your own wrappers.

  3. How would I know if a Lobby notification was successfully sent to a Client?

    You can check the Service Logs to see if the Lobby notification was sent successfully or not. Success notifications get logged only if "info" logs are available. However, if the target user happens to be offline, this will not be the case.

  4. Is there an upper limit on the number of friends a player can have?

    There is currently no limit on the number of friends a player can have.

  5. We are new to cloud-based backend systems. Where can we find descriptions of the terminology?

    The Glossary provides a list of common AGS and online gaming terms and their definitions. You can reach out to AccelByte if there are more terms you'd like defined.

API endpoints​

  1. What is the Admin API to query all the player reports, and what permissions does the OAuth client need to make this call?

    There are two endpoints, depending on whether the query is based on Tickets or Reports.

    To query based on Tickets:

    GET /reporting/v1/admin/namespaces/{namespace}/tickets

    To query based on Reports:

    GET /reporting/v1/admin/namespaces/{namespace}/reports

    The relevant permission required is:

    Permission: ADMIN:NAMESPACE:{namespace}:TICKET [READ]

    Note that a Ticket is a model representing a single reported object. It contains a status that indicates whether it is open or closed. A ticket will be created for a new reported object. Subsequent reports with the same object will use the same ticket, unless there is no open ticket for the reported object.

    A Report is a user-submitted report on a single object. The Category defines what feature the report is for (for example: Chat, Matchmaking, UGC, etc.). The Object defines what type is being reported (for example: user or content) and the object ID record is its unique ID.

  2. Is the API call queryUserIAPOrders called by an Admin Portal function or menu?

    No.

  3. When I am calling an API command or trying to log in, I receive the following warning: LogAccelByte: INVALID RSP HTTP. What does this mean and what can I do to fix it?

    This error usually comes with an HTTP 400 error response, which indicates that the API call was malformed. If this is in Unreal Engine, this often means that the format of the API command you are calling could have an issue. Check that there are no double slashes (//) in the API call URL and that your defaultEngine.ini is properly configured. It should look similar to the example below, ensuring that there is no trailing slashes for the BaseUrl:

    [/Script/AccelByteUe4Sdk.AccelByteSettings]
    ClientId=<client_id>
    ClientSecret=
    Namespace=<namespace>
    PublisherNamespace=<publisher_namespace>
    RedirectURI="http://127.0.0.1"
    BaseUrl=<base_url>
    AppId=<app_id>

    [/Script/AccelByteUe4Sdk.AccelByteServerSettings]
    ClientId=<client_id>
    ClientSecret=<client_secret>
    Namespace=<namespace>
    PublisherNamespace=<publisher_namespace>
    RedirectURI="http://127.0.0.1""

  4. What does the linkedGames parameter return in a Get conflict result when linked to a headless account from the current full account?

    The linkedGames parameter returns the game namespace.

  5. What does the oneTimeLinkCode parameter return when linked to a headless account from the current full account?

    The oneTimeLinkCode parameter returns the game namespace.

  6. When using the query parameter, which has a 2,000 limit, with a player's friends, can this overload if the player has more than 64 friends?

    Yes, each player ID requires 32 characters, so the limit is around 64 IDs. The workaround is to either limit the number of friend IDs or to make multiple requests.

Authentication and authorization​

  1. Can I grant or revoke entitlements in bulk?

    Yes.

  2. For the IAM service and authenticating with Steam, where do I find information on steamopenid?

    Refer to User Authentication and Ownership on the Steam website.

Dedicated servers​

  1. My dedicated servers aren't being created. What could I have done wrong?

    One possible reason could be your configurations. In the Admin Portal under Dedicated Server Management > Configurations, you will want to check the deployment to see if the maximum is set to 0. Then, check your pod configurations.

    If these are too few, there won't be enough resources for your server. Too much and the virtual machine running your server won't be able to run it. Typically, virtual machines AGS uses have 5GHz of CPU and 8GB of memory (AWS EC2 Instance m5a.large), so tailor your pod configuration with those specifications in mind.

    In some cases, your company might request better EC2 instances, especially for production, so ask your organization or your AccelByte contact for information on how to request this.

  2. While my server is being created or running with users on it, the server seems to terminate. This often happens after some time has passed. What could be wrong?

    This is likely due to a timeout. You will want to ensure your creation and session timeouts are appropriate. Timeouts are needed to ensure the dedicated server builder, or a dedicated server itself, does not end up running indefinitely. This is in case any issues arise. For a creation timeout, we recommend at least 300 seconds (five minutes). When a new server image is uploaded, it will take more time for the builder and virtual machine to download and cache the server image. For a session timeout, we recommend at least twice the amount of time a game session should normally take to finish.

Errors and exceptions​

  1. We got an error code when accessing our Lobby Server. Where can I find an associated description for that code?

    Search the list of errors in Lobby Error Codes.

  2. What does error code 401 invalid_client mean?

    This error comes from the Client ID or Client Secret being incorrect. Make sure you have the correct Client ID and Client Secret for the namespace you are uploading to.

  3. What does the error message unable to grant client token mean?

    This error comes from having the improper permissions on the IAM Client being used. Make sure you have configured the proper permissions.

  4. What is the error message Docker file pushed to registry but unable to update DSM config. Please contact the Administrator referring to?

    This error code comes from a mismatched DS Uploader version and Environment version. Downloading the newest version of the DS Uploader from the Admin Portal should stop this error from occurring.

  5. What is error code 720743 unable to create image patch, invalid request: patch version is empty referring to?

    This error code comes from a mismatched DS Uploader version and Environment version. Downloading the newest version of the DS Uploader from the Admin Portal should stop this error from occurring.

  6. What does the error message "conflict image version" error=conflict mean?

    This error means that the version you are trying to upload your new image with already exists. If you want to keep the same version, you can add the --patch flag to your command. Otherwise, you will have to change the version in your upload command.

  7. What does the error code 20013 access forbidden: insufficient permissions mean?

    This error comes from having the incorrect permissions set in the IAM client being used to upload your server image. Make sure the permissions of the IAM client is configured properly.

  8. I have set up my PlayStation Login for PS4 and/or PS5, but when I try to log in, I am getting the following error: "unable to exchange auth code: unable to unmarshal error response: invalid character '\u003c' looking for beginning of value". How should I resolve this?

    \u003c is the numerical code for <, which means that an HTML page is being returned as a response. Usually, this page refers to an unauthorized access to Sony's environment. In order to gain access, you will need to whitelist your environment with Sony's by doing the following:

    1. Submit a request with AccelByte for the Static IP Address of your environment's IAM service for whitelisting purposes.

    2. Determine which of Sony's environment you will be accessing (e.g., sp-int or prod-qa).

    3. Go to the Playstation Partners support page for your organization.

    4. Submit a General Support Request to whitelist the IP address provided in the environment you require whitelisting for and follow the process outlined by PlayStation.

  9. What should I do if the publicBulkClaimUserRewards endpoint returns the error message 49124 Manual claim not supported?

    This endpoint will return a response based on the Automatically claim reward configuration. If enabled, you can't manually claim it, which will cause the endpoint to return the 49124 error message.

  10. When trying to clone a game item from the game namespace to the publisher (or studio) namespace, I get the error Default Region is required. Both the namespaces already have the same region and language settings. What is the issue?

    Make sure you have already set the regional price for the given item in your game namespace so the publisher namespace will know which base price to look for when cloning the item. To do this, go to Stores, open your item's details, and click Add New in the Pricing panel.

  11. Why are we getting the error "errorMessage": "access forbidden: insufficient permissions. Required permission: NAMESPACE:{namespace}:DSM:CONFIG [READ]" when uploading our server to Armada?

    You are missing the permission stated in the error message.

  12. When we enter the template ID, we get an error Cannot use dynamic template data with a legacy template ID. What is the correct value for variables such as APP_SUBSCRIPTION_EMAIL_TEMPLATE_SUBSCRIBED?

    You need to use the template name, not the template ID.

Feature requests​

Are you going to support chat rooms for a region?

We currently have no plans to develop support for region-specific chat rooms.

Incident recovery​

When setting up AccelByte Multiplayer Servers (AMS), I ran into a bug in my code that resulted in a V2 session getting stuck. This results in my function for finding sessions breaking. I tried destroying the sessions to clean it up, but I got an error saying I couldn't destroy a session locally. How do I destroy a hung V2 session so that I can resume testing?

Query all sessions you are part of and call LeaveRestoredSession for each of them during startup of the game. You should not call DestroySession, as the Session will be deleted when the user count goes to 0.

Login​

  1. If a user has a non-verified email, can they do email and password login and get an access token?

    Yes.

  2. Is the access token a non-verified email user acquires usable to access other services?

    Yes.

  3. Is it possible to grant or remove entitlements in bulk?

    Both the Admin Portal and the API are able to grant or revoke multiple entitlements. Go to Commerce > User Entitlements to locate the Entitlements settings. The API calls are grantUserEntitlement, and revokeUserEntitlements.

  4. Do we have a feature to autofill the user country, perhaps from the user's IP address?

    This is currently a feature of third-party logins, but not username and password logins. With third-party logins, the IAM will automatically set the user country based on the IP Address if the country field is blank.

Matchmaking​

  1. How do I set up uploaded image to be the default image for Armada server deployment?

    If you go to the Generate Command page, there is a Deployment dropdown. Fill the command generation form, select the deployment name, and generate the command. There will be a --deployment {deployment-name} argument. Upload the game server to Armada and the system will change the selected deployment image version to the latest image.

Player Portal​

  1. Is it possible to rebrand the AccelByte Player Portal with, for example, a customer's own banner?

    Yes, though currently this has to be done by contacting AccelByte. A Player Portal UI editor is on the roadmap for future release.

  2. Can my players have View access to see other players' stats?

    Yes, by default, all User roles come with the permissions shown below. "Action": 2 means Read access, so your players are automatically granted View privilege.

    "Resource": "NAMESPACE:{namespace}:USER:*:STATITEM", "Action": 2

Roles and permissions​

  1. What permissions are needed for a role in the Admin Portal to be able to give currency to users?

    The required permission is:

    resource="ADMIN:NAMESPACE:{namespace}:USER:{userId}:WALLET", action=4 (UPDATE)

  2. How should I determine what permissions I need?

    Permissions are required depending on what API endpoints you intend to use.

    You can check the list of API endpoints for the APIs you would like to use and find the permissions required for each call.

    Do note that if the API is Public, the permission is needed on the user role, while if the API is Admin, the permission is needed on the IAM/OAuth Client for your game.

  3. What Roles should I set my users up with?

    By default, we recommend using the Super Admin and Game Admin roles. The Super Admin role provides the user with full admin access to every namespace, which is good for developer leads. Game Admins have full admin access over assigned namespaces, not including anything that requires environment-wide access such as Super Admins. Once you are closer to launch, you may want to look towards having custom roles created for moderators and non-developers.

  4. How do I give Roles to Users?

    Roles can be given to specific users by going to their profile in the Admin Portal, clicking on the Roles tab, and selecting Add Role.

Security​

  1. Does the dsm-controller have Cross-Origin Resource Sharing (CORS) whitelisting functionality?

    CORS whitelisting is a system enabling a server to permit loading resources from certain specified origins. This is supported by the AccelByte dsm-controller.

  2. Is it possible to grant or remove entitlements in bulk?

    Both the Admin Portal and the API are able to grant or revoke multiple entitlements. Go to Commerce > User Entitlements to locate the Entitlements settings. The API calls are grantUserEntitlement, and revokeUserEntitlements.

  3. Is there a mechanism where a specified user can get sent email notifications if there's suspicious activity?

    Currently, notifications cannot be set for individual users.

Testing​

  1. What should I do if I have multiple App IDs for play testing?

    There are two ways to approach this issue:

    • If you want the users that participate in this play test to have their progress and entitlements carry over, the best thing to do would be swapping App IDs in the namespace you are already using.

    • If you want to keep users progress and entitlements separate just for this play test, a new namespace should be created, importing all of your settings as well as setting up the new App ID for the play test. This will keep all the data separate from your other namespaces.

  2. How do the logs get pulled from Nomad?

    Refer to Commands: alloc logs.

Two-factor authentication​

  1. Where can I get the Backup Codes?

    You will have received your Backup Codes when you first set up two-factor authentication (2FA) using the Backup Codes method.

  2. What if I lose my Backup Codes?

    If you have set up 2FA using the authenticator app, you can go back to the login menu and authenticate using the authenticator app. Once logged in, go to Password & Security, regenerate your Backup Codes, and store these codes in a safe place.

  3. Where can I get my Security Code?

    Open the authenticator app and input the Security Code in the login form when prompted.

  4. What if my Security Code is invalid?

    Recheck your security code and make sure the date and time on the phone where you have installed the authenticator app is synchronized with the date and time on your computer. If your security code keeps failing, try logging in using Backup Codes. If these steps fail, you can contact our support team.

Handling CORS (Cross-Origin Resource Sharing) in Web Development​

CORS is a security feature that blocks or restricts web requests from different origins (domains). While it’s crucial for security, it can be frustrating when developing web apps locally. Here are some ways to manage or bypass CORS.

Set up an allow list on the server​

info

If you're an AGS Private Cloud customer, you can request that your web domains be added to our allow list. Note: This feature isn’t available for AGS Shared Cloud yet.

If you have server access, configure the server to accept requests from specific origins. For example, you could allow requests from http://localhost:3030 and http://example.com.

You can bypass CORS using browser settings or extensions, but this method is risky. Here’s an example for Chrome:

chrome.exe --disable-web-security --disable-gpu --user-data-dir="[directory]"

This disables Chrome’s web security, allowing all requests to bypass CORS, and allowing cookies to persist across domains. This approach compromises security and stability, so we do not recommend it.

Alternatively, browser extensions can act as proxies to forward requests to the target server. But again, this is not secure for production or user-facing scenarios.

Setting up a local proxy is a safe and effective method for JavaScript development. Here's how to set it up.

Option 1: Using Vite’s built-In proxy​

Vite provides a simple configuration to set up a proxy:

export default defineConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://example.com',
        changeOrigin: true,
        cookieDomainRewrite: 'localhost',
        configure(proxy) {
          proxy.on('proxyReq', req => {
            req.setHeader('Referer', 'https://example.com')
          })
        },
        rewrite: path => {
          return path.replace(/^\/api/, '')
        }
      }
    },
  },
})

Explanation:

  • Requests to http://localhost:3000/api/test-route are forwarded to https://example.com/test-route.
  • The proxy changes the origin and sets the Referer header.
  • Cookies in the response are rewritten to use localhost instead of the original domain.

Option 2: Using http-proxy-middleware with Express​

const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

const apiProxy = createProxyMiddleware({
  target: 'http://example.com',
  changeOrigin: true,
  cookieDomainRewrite: 'localhost',
  configure(proxy) {
    proxy.on('proxyReq', req => {
      req.setHeader('Referer', 'https://example.com')
    })
  },
  rewrite: path => {
    return path.replace(/^\/api/, '')
  }
});

const app = express();

app.use('/api', apiProxy);
app.listen(3000);

As with Vite proxy, this setup forwards requests and rewrites cookies.

Recommendation​

  • For production: Set up a server-side allow list for your domains.
  • For local development: Use a local proxy (e.g., Vite or http-proxy-middleware).
  • Avoid browser extensions or disabling security settings as they can introduce risks.

By following these steps, you can manage CORS effectively without compromising security.

Last updated on

On this page