Board gaming apps and websites can provide an easy way to post results of completed plays to Board Game Stats. This way the player doesn’t have to copy the play details manually. Show the button if BG Stats is installed (see bottom of the page how to check that).

Suggested button to use:

When tapping the link, if the user has BG Stats (version 3.3.2 or higher) installed on their iOS or Android device, the app will automatically open and show the import dialog. In this dialog the games and players can be matched to existing entries in the app, after which the play is saved.

The app will automatically suggest matches, based on the provided game’s BGG id (if any), name, and player names. Matches made by the user are saved for the next import, so each match only has to be done once. The location is set to the Board gaming app or website providing the link.

If the user is authenticated with their BGG account in BG Stats and has Auto-post enabled, the play will be posted to their BGG account after import.

The link is a simple request URL with this format:
https://app.bgstatsapp.com/createPlay.html?data=<data>

Alternatively, bgstats://app.bgstatsapp.com/createPlay.html?data=<data> works as well.

On Android, users might need to enable ‘Open supported links’ in the ‘Open by default’ settings available in the App info.

<data> is an url-encoded json-string with this format:

{
  "board": "", 
  "durationMin": 36, 
  "comments": "Such a close play!", 
  "game": {
    "bggId": 132531, 
    "highestWins": true, 
    "name": "Roll for the Galaxy",
    "noPoints": false, 
    "sourceGameId": "21df231"
  },
  "location": "Home",
  "playDate": "2020-10-23 19:16:58", 
  "players": [
    {
      "startPlayer": true, 
      "name": "Eerko", 
      "rank": 1, 
      "role": "", 
      "score": 47.3, 
      "sourcePlayerId": "23432", 
      "winner": true
    }, 
    {
      "startPlayer": false, 
      "name": "Suzan", 
      "rank": 2, 
      "role": "", 
      "score": 36.3, 
      "sourcePlayerId": "23433", 
      "winner": false
    }
  ], 
  "sourceName": "App name", 
  "sourcePlayId": "2222427"
}

Description of elements:

sourceName: the name for your app or website, required
sourcePlayId: your unique id for the play, required
playDate: UTC ending date and time in format yyyy-MM-dd HH:mm:ss, required
durationMin: play duration in minutes, optional
comments: comments to add to the play (limit the length to avoid too long request urls) (4.1+)
board: the board or variant selected for this play, optional
location: name of the play location, optional; sourceName is used if omitted (3.15+)
game: details of the played game, required
– name: the name of the played game, required
– sourceGameId: your id for the game, required (used for re-matching)
– bggId: BGG id for the game, recommended but optional
– highestWins: boolean, determines if a higher or lower score is better
– noPoints: boolean, determines if only win/loss is registered and no scores
players: array of players and their scores, required
– name: name of a player, required
– sourcePlayerId: your unique id for the player, required
– startPlayer: boolean, determines if this is the starting player
– winner: boolean, determines if this player is a winner
– score: integer or decimal (with . as decimal point) score for this player, optional
– rank: ranking for this player in this play, starting at 1 (best ranked), optional
– role: role for this player in this play, optional

Example complete request URL:

https://app.bgstatsapp.com/createPlay.html?data=%7B%22board%22%3A%22%22%2C%22durationMin%22%3A36%2C%22game%22%3A%7B%22bggId%22%3A132531%2C%22highestWins%22%3Atrue%2C%22name%22%3A%22Roll%20for%20the%20Galaxy%22%2C%22noPoints%22%3Afalse%2C%22sourceGameId%22%3A%2221df231%22%7D%2C%22playDate%22%3A%222020-10-23%2019%3A16%3A58%22%2C%22players%22%3A%5B%7B%22startPlayer%22%3Atrue%2C%22name%22%3A%22Eerko%22%2C%22rank%22%3A1%2C%22role%22%3A%22%22%2C%22score%22%3A47.3%2C%22sourcePlayerId%22%3A%2223432%22%2C%22winner%22%3Atrue%7D%2C%7B%22startPlayer%22%3Afalse%2C%22name%22%3A%22Suzan%22%2C%22rank%22%3A2%2C%22role%22%3A%22%22%2C%22score%22%3A37.3%2C%22sourcePlayerId%22%3A%2223433%22%2C%22winner%22%3Afalse%7D%5D%2C%22sourceName%22%3A%22App%22%2C%22location%22%3A%22Home%22%2C%22sourcePlayId%22%3A%222222427%22%7D

Example iOS (Swift) code to post the play from an app (this doesn’t open a browser first, but opens the app directly) below:

if let appURL = URL(string: requestString) {
    UIApplication.shared.open(appURL) { success in
        if success {
            print("The URL was delivered successfully.")
        } else {
            print("The URL failed to open.")
        }
    }
} else {
    print("Invalid URL specified.")
}

Example Android (Kotlin) code to post the play from an app (the user will have to choose the first time whether to open this link in BG Stats or in a browser) below:

try {
    val openUrlIntent = Intent(Intent.ACTION_VIEW, Uri.parse(requestString))
    startActivity(openUrlIntent)
} catch (e: ActivityNotFoundException) {
    Log.d("BGStats", "No application can handle this request.")
}

Checking if BG Stats is installed

From a website it can’t be determined if a specific app is installed, other than trying to open the app (by linking to bgstats://… and trying to catch the error). It might be preferable to have the user enable the Post to BG Stats button in their settings.

On iOS (Swift) you can check if BG Stats is installed by calling canOpenURL:

func isBGStatsInstalled() -> Bool {
    if let appURL = URL(string: "https://app.bgstatsapp.com") {
        return UIApplication.shared.canOpenURL(appURL)
    } else {
        return false
    }
}

On Android (Kotlin) you can check if BG Stats is installed as follows:

fun isBGStatsInstalled(): Boolean {
    val openUrlIntent = Intent(Intent.ACTION_VIEW, Uri.parse("https://app.bgstatsapp.com"))
    val resolvedActivities = requireActivity().packageManager.queryIntentActivities(openUrlIntent, 0)
    return resolvedActivities.any {
        "nl.eerko.boardgamestats" == it.activityInfo.packageName
    }
}

Starting a new Play in BG Stats

You can launch BG Stats with the New Play screen by calling one of:

To preselect the game to play, provide the bggId of the game as such:

If the game doesn’t exist yet, it will be added to the app, if it can be found on BGG.

To preselect the location to play, provide the name of the location as such: