Linking with a pre-existing users database


Over the years, the platform has welcomed a larger and larger number of games. Some of these games already existed before coming to the platform, and sometimes used their own database of users - for example to play online.

This guide explains how to perform account linking and import these pre-existing users into the database as smoothly as possible. It might sound like a boring problem, but it is an important one! Dealing with accounts, login, password, etc. is always a source of headaches for users. So it is paramount to spend good efforts to provide the best experience to users as much as possible.

About the Partner ID and the Partner User ID

An account can be attached (“linked”) to a user record from an external database (called a “Partner”) simply by storing the Partner’s user identifier inside the database. This identifier is called the Partner User ID. It is usually a number, but it can be any alpha-numerical string.

And because we want to accommodate several Partners, we give to each Partner a specific Partner ID. It is simply an arbitrary number.

The platform already defines a preset list of Partners:

Partner ID
Boardgame Geek 10
Steam 12
Facebook 14
Amazon 15
Google Play 16

So for example, the user Yakka1 (id=1109397) is linked to Steam with: Partner ID=12 and Partner User ID=76561197991864939 (his Steam ID).

If you need a Partner ID, please contact us at We will assign a Partner ID to your Studio and it will appear under your Studio description in the Studio Manager .

Linking end-points

There are a number of API end-points that deal with the pair Partner ID + Partner User ID. For example, you can search for a user by using a Partner ID and a Partner User ID. There is also an end-point to link (or unlink) one or more users.

Importing + Logging Workflow

Now that we covered the basics, we can discuss about the job at hand: importing and logging a user to the platform using a pre-existing users database from a Studio.

We will assume that the game already existed before being ported to the platform, and that the user would connect using some login name and password. We also assume that the Studio wants to keeps its infrastructure, because it contains some data specific to the game. But at the same time, the Studio wants to adapt the game to the platform by allowing its users to use (or create) accounts for additional benefits and features.

The problem is that a user may already have an account. In the board game market, it is actually likely. So you don’t want to lead the user to create a new account by mistake, this would be a disaster.

The idea is to first check if the user is not already known and linked in the database. If not, let’s try to find the user using the e-mail (assuming you have it in your database, which is likely). If we are still out of luck, we must rely on the user to log in or create an account. This is accomplished using the Sign-up and Login workflow (aka “SSO”). Make sure you read it in details.

Here is the complete workflow:

Linking Flow

Important Notes about this workflow

As always, the Devil lies in the details.

  • It is important that you fully understand and implement the the Sign-up and Login workflow. It is the result of numerous trials and mistakes, and proved to be the easiest way for users to find and login with their account.
  • We highly advise you to explain to your users the benefits of using an account, and always make things very clear in your user interface whether you are talking about their original account or about their account. Dealing with one account is already complicated for most users, so imagine what it can be with two linked accounts.
  • If you decide to drop your own infrastructure and move everything to the platform, it is obviously possible. In this case, the above workflow would be used only once, and presented as an importation/migration procedure. However keep in mind that users could start your game years after you switched your app to the platform, so it is likely that you won’t be able to completely drop your former infrastructure. In any case, you need to think about this and be prepared. As an example, four years after we terminated the “Pocket” version of Ticket to Ride on iOS, we were still receiving messages from players who were just discovering it and asking how to migrate to the full version of Ticket to Ride…
  • There are two little optimisations that you can do inside the Sign-up and Login workflow:
    • If you are in the case where you create a new account, you can link him/her immediately to your Partner ID and Partner User ID: you can give these parameters to the account creation end-point: see the partner and the partner_user parameters. This will allow you to skip the step at the end of the workflow where you test and link the user - it’s already done.
    • If you are in the case where you create a new account, you can pre-fill the user’s e-mail field in the “Welcome” dialog. A nice touch for the user.
  • Last but not least, you may have noticed the last step that checks if the account is confirmed. This is something that we advise to do as a rule of thumb. The idea is to force the user to check his/her mailbox and use the confirmation message to validate the account. This is important because failing to do so will result in the cancellation of the account 7 days later. We found that many users simply forget to do this in their rush to get done with the boredom of creating an account, and when they see the confirmation e-mail later on, they just ignore it. Since it is now a legal requirement to verify the user’s e-mail in many jurisdictions, it is advisable to force it as quickly as possible. See the Restrict access to particular feature section for a detailed description.

API End-points used in the workflow