AGS Best Practices

Last updated on December 17, 2024

This article covers some best practices to use for game integration. These game integration best practices can help prevent issues from occurring, minimize the impact of issues that do occur, and provide players a better user experience.

The Basics

Document link

Get your copy of the Best Practices document here.

---

• Implement logins before calling any AGS APIs.
  Details

  An error will occur when an API is called without a login auth token.

  
  

  Step to Check :

  1. Enable AGS Game SDK logs.
  2. Open the game logs.
  3. Verify login is called before any other API call.
  

  Reference :

  Introduction to Authentication
  Byte Wars - Access - (Unreal Engine modules)
  
• Implement login queue (AGS Private Cloud only).
  • Enable login queue.
    Details

    Login queues only allow players to enter the game when space is available, preventing an influx of players from overloading the server during peak play hours.

    
    

    Step to Check:

    1. In the AGS Admin Portal under your game namespace, go to Live Service Utilities > Login Queue.
    2. Ensure the Feature Status under the page title says Active.
    3. If its Inactive, press the Activate button to the right.
    4. Verify your product versions match what's shown on the Activate Login Queue popup.
    5. Click Confirm.
    6. Verify your Feature Status has been updated to Active.
    

    Reference :

    Login Queue
    Byte Wars - Login Queue (Unreal Engine module)
    
  • Set appropriate login queue limits.
    Details

    Login queue limits that are set above your server's capability increases the risk of your server being overloaded.

    
    

    Step to Check:

    1. In the AGS Admin Portal under your game namespace, go to Live Service Utilities > Login Queue.
    2. Verify Max Concurrency, Max Login Rate per Second, and the Advanced Configuration options are set appropriately.
    3. Click Edit to make any desired changes and click Save.
    

    Reference :

    Login Queue
    Byte Wars - Login Queue (Unreal Engine module)
    
• Connect to AGS Lobby after login.
  Details

  An AGS Lobby connection is needed to deliver notifications and access social and matchmaking features.

  
  

  Step to Check:

  1. Enable AGS Game SDK logs.
  2. Open the game logs.
  3. Verify the AGS Lobby connection after a successful login.
  

  Reference:

  Configure Lobby with the SDK
  Implement Lobby using the Unity SDK
  Implement Lobby with Unreal Engine SDK
  
• Ensure party retention.
  • Create or restore a party when the game is launched.
    Details

    Placing the player in a party—either alone or as part of a previous party ensures seamless interactions with party features.

    
    

    Step to Check :

    1. Verify that a player's party information is checked on game launch.
    2. If the check returns party information, either restore that party or disband it and have the player join a new party.
    3. If the check doesn't return party information, have the player join a new party.
    

    Reference :

    Byte Wars - Implement party utilities - Implement a party session (Unreal Engine module)
    Byte Wars - Implement party creation - Implement a party session (Unreal Engine module)
    Create a party - Integrate Party into your game
    
  • Create a new party when the player leaves or is kicked from a party.
    Details

    A player should always be in a party—even a party of just themselves—to ensure seamless interactions with party features.

    
    

    Step to Check:

    1. Verify players are placed in a party when they play the game.
    2. Verify players are placed in a new party after they leave or are kicked from a party.
    

    Reference :

    Byte Wars - Implement party creation - Implement a party session (Unreal Engine module)
    Byte Wars - Implement leave party - Implement a party session (Unreal Engine module)
    Create a party - Integrate Party into your game
    Leave a party - Integrate Party into your game
    Kick a player from a party
    
• Handle WebSocket (Lobby and Chat) connection errors and reconnect conditions.
  • Handle internet connection loss error.
    Details

    Alleviate player frustration during connection issues.

    
    

    Step to Check:

    1. Run the game until a Lobby connection is established.
    2. Disconnect the device from the internet.
    3. When Lobby gives an error signal, take note of the callback.
    4. Reconnect the device to the internet.
    5. Ensure appropriate flow when the connection is reestablished.
    

    Reference :

    Handle connect and disconnect events - Configure Lobby with the SDK
    Websocket Reconnection Strategy
    
  • Handle connection errors caused by the game running in the background.
    Details

    Provide a continuous game experience for players as they swap between games, applications, and processes.

    
    

    Step to Check:

    1. Run the game until a Lobby connection is established.
    2. Switch to a new game or process (i.e., launch another game on console or press Alt + Tab on PC).
    3. Return to the original game.
    4. When Lobby gives an error signal, take note of the callback.
    5. Reconnect the device to the internet.
    6. Ensure appropriate flow when the connection is reestablished.
    

    Reference :

    Handle connect and disconnect events - Configure Lobby with the SDK
    Websocket Reconnection Strategy
    
  • Handle matchmaking connection errors.
    Details

    Prevent players from being stuck in the matchmaking process after a connection loss.

    
    

    Step to Check:

    1. Run the game until a Lobby connection is established.
    2. Start matchmaking.
    3. Disconnect the device from the internet during the matchmaking process.
    4. When Lobby gives an error signal, take note of the callback.
    5. Reconnect the device to the internet.
    6. Ensure appropriate flow when the connection is reestablished.
    

    Reference :

    Handle connect and disconnect events - Configure Lobby with the SDK
    Websocket Reconnection Strategy
    
  • Handle multiplayer match connection errors.
    Details

    Allow players to return to the match they were playing after a connection loss.

    
    

    Step to Check:

    1. Run the game until a Lobby connection is established.
    2. Start matchmaking and join a multiplayer match.
    3. Disconnect the device from the internet.
    4. When the Lobby gives an error signal, take note of the callback.
    5. Reconnect the device to the internet.
    6. Ensure appropriate flow when the connection is reestablished.
    

    Reference:

    Handle connect and disconnect events - Configure Lobby with the SDK
    Websocket Reconnection Strategy
    
  • Handle errors for simultaneous same account Lobby connection attempts (single point of presence).
    Details

    Prevent players from logging into the same account on multiple devices or clients.

    
    

    Step to Check:

    1. Run the game until a Lobby connection is established.
    2. Repeat on another device or client using the same account.
    3. Take note of the error triggered on the device or client.
    4. Handle the error and notify the clients that the account is already logged in.
    

    Reference :

    Handle connect and disconnect events - Configure Lobby with the SDK
    Websocket Reconnection Strategy
    
• Implement logouts when closing the game.
  • Implement logout when Close is pressed on the client window.
    Details

    Ensure the player is logged out when the player closes the window.

    
    

    Step to Check:

    1. Enable AGS Game SDK logs.
    2. Run the game.
    3. Log in and reach the main menu.
    4. Close the game using the Close button on the window.
    5. Open the game logs.
    6. Verify logout is called before the game ends.
    

    Reference:

    Logout - Authentication using the Unreal Engine SDK
    
  • Implement logout when there's an Exit option in the game menu.
    Details

    Ensure players can log out using the user interface.

    
    

    Step to Check:

    1. Enable AGS Game SDK logs.
    2. Run the game.
    3. Log in and reach the main menu.
    4. Close the game using an Exit or Close option in the game menu.
    5. Open the game logs.
    6. Verify logout is called before the game ends.
    

    Reference :

    Logout - Authentication using the Unreal Engine SDK
    
• Implement friend sync.
  • Sync friends on game launch.
    Details

    Ensure the player's friend list is up to date when they start the game.

    
    

    Step to Check:

    1. Run the game in two separate clients.
    2. Log into each client with separate accounts, ensuring each has a profile in the same environment and namespace and they have each other as friends.
    3. Check each client's friend list in the game and verify they're on each other's list.
    4. Search for each player in the AGS Admin Portal under Lookup Users and verify they're on each other's friend list.
    

    Reference :

    Synchronize platform friends
    
  • Sync friends after player attempts to add friend in the platform interface.
    Details

    Ensure a player's friend list gets updated after players attempt to add a friend via the platform interface (e.g., Steam, PSN, Xbox) while the game is running.

    
    

    Step to Check:

    1. Enable AGS Game SDK logs.
    2. Run the game in two separate clients.
    3. Log into each client with separate accounts, ensuring each has a profile in the same environment and namespace.
    4. Use one account to add the other as a friend through the platform interface.
    5. Return to the game.
    6. Open the game logs.
    7. Verify friend sync was called.
    

    Reference :

    Synchronize platform friends
    
  • Sync friends after player accepts friend request in the platform interface.
    Details

    Ensure a player's friend list gets updated after players accept a friend request via the platform interface (e.g., Steam, PSN, Xbox) while the game is running.

    
    

    Step to Check:

    1. Run the game in two separate clients.
    2. Log into each client with separate accounts, ensuring each has a profile in the same environment and namespace.
    3. Use one account to add the other as a friend through the platform interface.
    4. Accept the friend request in the other client through the platform interface.
    5. Check each client's friend list in the game and platform interface to verify they're on each other's list.
    6. Search for each player in the AGS Admin Portal under Lookup Users and verify they're on each other's friend list.
    

    Reference :

    Synchronize platform friends
    
  • Sync friends after friend removal.
    Details

    Ensure a player's friend list gets updated after the player removes a friend from their list.

    
    

    Step to Check:

    1. Run the game in two separate clients.
    2. Log into each client with separate accounts, ensuring each has a profile in the same environment and namespace and they have each other as friends.
    3. Use one account to remove the other from their friend list using the unfriend AGS API.
    4. Verify the updated friend list in the game and the platform interface (e.g., Steam, PSN, Xbox).
    

    Reference:

    Synchronize platform friends
    
• Implement blocklist sync.
  • Sync blocked players after player block.
    Details

    Ensure a player's blocked players list is up to date when using the blocked players feature in the platform interface (e.g., Steam, PSN, Xbox).

    
    

    Step to Check:

    1. Run the game in two separate clients.
    2. Log into each client with separate accounts, ensuring each has a profile in the same environment and namespace.
    3. Use one account to block the other using the platform interface.
    4. Verify the updated blocklist in the game and the platform interface.
    

    Reference:

    Synchronize blocklist data with native platforms - Implement player blocking
    
  • Sync blocked players on game launch.
    Details

    Ensure the blocked player's list is up to date when they start the game.

    
    

    Step to Check:

    1. Run the game in two separate clients.
    2. Log into each client with separate accounts, ensuring each has a profile in the same environment and namespace.
    3. Close one of the clients.
    4. Use the open client to block the other account.
    5. Close the remaining client.
    6. Relaunch the game using the same two accounts.
    7. Verify the updated blocklist in the game and the platform interface.
    8. Search for each player in the AGS Admin Portal under Lookup Users and verify they're not in each other's friend list.
    

    Reference:

    Synchronize blocklist data with native platforms - Implement player blocking
    
• Set up third-party store.
  • Configure third-party store.
    Details

    Ensure third-party platform stores are properly synced with AGS Ecommerce.

    
    

    Step to Check:

    1. In the AGS Admin Portal, go to Game Setup > 3rd Party Configuration > Store.
    2. Click the desired third-party store's tab (e.g., PlayStation Store).
    3. Click Add Configuration.
    4. Complete the form and click Add.
    

    Reference:

    Manage third-party store integrations
    
  • Verify consumable items.
    Details

    Ensure consumable items are working properly and refunds are synced with the third-party platform store. Avoid including both consumable and durable items in the same bundle.

    
    

    Step to Check:

    1. In the AGS Admin Portal, go to Commerce > In App Purchase > Item Mapping.
    2. Ensure the items listed here are set to Consumable.
    

    Reference:

    Set up and sell consumables
    
  • Verify durable items.
    Details

    Ensure consumable items are working properly and refunds are synced with the third-party platform store. Avoid including both consumable and durable items in the same bundle.

    
    

    Step to Check:

    1. In the AGS Admin Portal, go to Commerce > In App Purchase > DLC Setting.
    2. Ensure the items listed here are set to Durable.
    

    Reference:

    Set up and sell DLCs