Asmodee.net documentation » Guides

Best Practices

This is a detailed list of low-level technical recommendations. As always with software development, the devil is in the details. If some items are unclear, please contact us.

REST API

Reference: REST API documentation

  • The app obfuscates its “client secret” string in its code, so that its secret cannot be found easily by dumping its binary code.
  • The app does not store OAuth2 Access Tokens in a permanent storage area. The Access Token should be volatile, i.e. stored in RAM, and recreated using the Refresh Token if it has been lost (upon an app re-launch for example) or if it expired.
  • The app stores the OAuth2 Refresh Token in a secured area of the operating system (key chain or similar encrypted system).
  • The app supports the expiration date of the Refresh Token and takes the user to the Login workflow if it expires.
  • Since the Asmodee.net REST API is not case-sensitive (or accent sensitive) regarding Login Names, the app does not rely on the Login Name provided by the user for any logic, but on the one returned by the API.
  • The app supports international (UTF-8) Login Names for users.
  • When using the user’s credential (password) to log in, the app does it in a secure manner, i.e. using TLS and talking directly to the Asmodee.net API. It does not use an intermediate service, proxy or server, so that the user’s credentials are not exposed to any other system.
  • The app performs “Certificate and Public Key Pinning” to make sure it’s talking to the right Asmodee.net servers and not a counterfeit (to prevent “Man in the Middle” attacks). Read the TLS Public Key Pinning article in the Scalable Server documentation for more details.
  • The app provides a clear and easy workflow for the user to log in or create a new account. If possible, follow the recommended workflow explained in the documentation.
  • The app gives the option to subscribe or not to the Asmodee Newsletter when the user creates a new account (right next to the email field).
  • If the app can be used by children under 13 and that it provides an online experience, it follows the COPPA recommendations: confirm the user’s age when creating an account, and disable all users-to-users interactions (chat…) if the user has the COPPA flag activated in her Asmodee.net account.
  • The app provides a number of services to help users manage their accounts problems: reset password, go to their Asmodee.net profile on the web, see their Asmodee.net Login Name and User ID, etc. See the example of the Login Settings Panels in Ticket to Ride
  • The Steam version of the app connects transparently using the Steam ID linked to the Asmodee.net ID and using the Steam Session Ticket end-point of the OAuth2 REST API. If no Asmodee.net user is found, it asks the user to find her account or create a new one. All this process is accomplished only when the app absolutely needs an Asmodee.net account (like when going to the online gaming area). It is not forced on the user at startup.
  • The app supports the REST API error codes, i.e. it reacts to errors returned by the API and informs the user appropriately as needed.
  • This apps relies on the operating system to know if there is an Internet connectivity or not. It does not uses tricks such as pinging repeatedly a giving URL or relying on the Scalable Server ping service to do this. And by supporting properly the error codes and time-outs (as noted above), the apps is capable of recovering from any unexpected loss of connection.
  • If the app runs on multiple platforms (iOS and Android for example) and relies on the REST API for features such as Achievements, Leaderboards, sharing in-app purchases, etc, it does it in a cross-platform manner: these information pieces are synchronized using the REST API, preferably automatically or through a manual synchronization system made available to the user.
  • If the app runs on multiple platforms (iOS and Android for example), it uses a different Client ID and Client Secret on each platform (to do this, provision different Apps in the Studio Manager). This way, if a Client Secret gets compromised on one platform, only the binary for that platform has to be updated.

Scalable Server

Reference: Scalable Server documentation

Make sure you read the Best Practises chapter in the Scalable Server documentation.

  • The app connects to the Scalable Server using an OAuth2 Access Token returned by the REST API.
  • The app connects to the Scalable Server only when the user goes to the online gaming area. It does not do it at the app start-up.
  • When the user leaves the online gaming area, the app disconnects from the Scalable server automatically after a 1-minute time-out.
  • If the app supports asynchronous gaming, it allows notifications (like “it’s your turn” notifications).
  • The app supports the error codes returned by the Scalable Server protocol.
  • When implementing a turn-based game, the app sends the Game State updates to the other clients using the Commit messaging, NOT the Multicast messaging system - which should be used only for volatile and non-game data messages, such as in-game chat, User Interface (UI) updates to other clients, etc. There are situations where the Multicast system can be used to send the Game State to other clients (for exemple in games with 3 or more players) because it can be an easy way to tell the other clients how to update their UI, but the “truth” should be considered to be located in the commited Game State. This will resolve any synchronization issues, especially when a disconnected player resumes a game.

Miscellaneous

  • The app shows clearly its version number in the main screen.
  • All documents of the project (specifications, Game Design Document, flow-charts, pencil-drawings, etc.) should be in English.
  • All source code should be English: identifiers, comments, file names, etc.

Amplitude

This section is for apps that use the Amplitude analytics system.

  • The app does not send any personal information to Amplitude, such as the user’s e-mail. All information must be anonymized.
  • The app sends the basic “pack” of information recommended by Asmodee Digital.

HelpShift

This section is for apps that use the HelpShift support system.

  • If an Asmodee.net user is known, the app gives the Asmodee.net user_id to the HelpShift API, so that the user can be easily identified when she sends a request.
  • The app provides additional information about the user or app context and configuration. For example: in-app purchases, virtual currency, PlayFab ID, player’s experience, etc., i.e. information that can help troubleshoot the user’s problems.