Knowledge Base

Last updated on September 20, 2023

Developers FAQ​

This section contains common developer questions and answers when building a game using AccelByte Gaming Services.

Admin Portal​

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

    Navigate to User Management / Users, then change the Search User entry to by Creation Date. Then set the date to a time before your namespace was created. Then you can view every player.

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

    If you are a super admin on the admin portal, navigate to Platform Configurations / Admins / Invite Admins. From there you input the invitee's email address and set them up as a super admin, or game admin, 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 by clicking on Platform Configurations and then Log Viewer.

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

    Currently, we're not providing an indicator to see the Server Image Upload progress and the remaining upload time. Only the build status is reported.

  6. Will a users' 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?

    Retrying at least once would be a good approach, before throwing an error to the service side.

  2. Does the AccelByte OSS support Blueprints?

    By design, the OSS doesn't support Blueprints. To use OSS in Blueprints, you will need to use some plugins, or create your own wrappers for the Blueprints.

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

    Checking the Service Logs is one method 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?

    Currently, no.

  5. We are new to cloud-based backend systems, and are struggling with all the terminology?

    We have added an AGS Glossary to our new doc portal. Please do give us feedback on new terms you would like to see added to this glossary.

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 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 type defines what type is being reported (for example: user, or content) and the object ID record is it's unique ID.

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

    No.

  3. When I am calling an API command/trying to login, 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 a 400 response, which indicates that the API call was malformed. If this is using 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 was properly configured. It should look similar to the following, ensuring that there is no trailing slash 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 2000 limit, with a players friends, this can overload if the player has more than about 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, our APIs let game admins grant and revoke multiple entitlements at once.

  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.

Best Practices​

Questions from users about the best way to go about things

Dedicated Server​

  1. My dedicated servers do not start creating, what could I have done wrong?

    One possible reason could be your configurations. 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 little, there won't be enough resources for your server. Too much and the Virtual Machine running your server would not be able to run it. Typically virtual machines we use by default have 5GHz of CPU and 8GiB of memory (AWS EC2 Instance m5a.large), so tailor your pod configuration with those 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 creating, 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 that your creation and session timeouts are appropriate. Timeouts are needed to ensure our dedicated server builder, or a dedicated server itself, does not end up running indefinitely. This is in case any issues arise. For creation timeout, we recommend at least 300 seconds (5 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 session timeout, we recommend at least twice the amount of time a game session should normally take to finish.

E-commerce​

Questions from users on monetization, product store, etc.

Errors and Exceptions​

  1. When accessing our Lobby Server we got an error code. How 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 to double check that you have the correct Client ID and Client Secret for the namespace you are uploading to.

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

    This error comes from having the improper permissions on the IAM Client being used. Double check the permissions in the docs guide [LINK].

  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. Double check the permissions of the IAM Client, and make sure it matches our documentation on Permissions.

  8. I have set up my PlayStation Login for PS4 and/or PS5, but when I try to login, it 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 do a couple things to whitelist your environment with Sony's:

    1. Request AccelByte for the Static IP Address of your environment's IAM Service for whitelisting purposes.

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

    3. Go on 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.

  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 namespace, I get the error Default Region is required. Both the Publisher and Game namespaces already have the same region and language settings. What is the issue here?

    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. We have a problem when uploading our Dedicated Server to Armada - we are getting the error "errorMessage": "access forbidden: insufficient permissions. Required permission: NAMESPACE:{namespace}:DSM:CONFIG [READ]"?

    Note that the error message includes a definition of the missing permission.

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

    That is expected behavior, you should enter the template name, not the template Id.

Feature Requests​

  1. Are you going to support chat rooms for a region?

    That is not currently on our roadmap. A chat room for an entire region would require a large number of players to be added to the session that the chat room is tied to.

Incident Recovery​

  1. As I've been working to setup AccelByte Multiplayer Servers I ran into a bug in my code that resulted in a V2 session getting stuck. This results in my find sessions function breaking. I tried using destroy session to clean it up but I got an error saying I couldn't destroy a session locally. How do I destroy a hung V2 sessions 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-password login and get an access token, and the access token is usable to access other services?

    Yes.

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

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

  3. 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 login, but not username-password login. With third-party login, 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 image upload 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, our system will then change the selected deployment image version to the latest image.

Performance​

Questions from users who want to know how to improve performance of AGS

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 following permissions. Action 2 means Read access, so your players are automatically granted View privilege.

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

Release​

Questions from users about how to release a complete game

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 role 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, 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?

    The API, and the Admin Portal, are able to grant or revoke multiple entitlements. Go to User Management > Users 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 ID's for playtesting?

    There are two ways to approach this issue.

    • If you want the users that participate in this playtest to have their progress and entitlements carry over, then the best thing to do would be swapping App ID's in the namespace you are already using.

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

  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. Check the places where you usually store your digital or physical backup codes.

  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 that 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.

Last updated on

On this page