Construct Game Services script interface

The ICGSObjectType interface derives from IObjectType to add APIs specific to the Construct Game Services plugin. Construct Game Services is also written as CGS for short.

Using the REST APIs

Construct Game Services have a comprehensive set of REST APIs available. When writing code it is possible to use those entirely independently of this plugin. This option may be of interest to advanced users - see the Construct Game Services manual for details.

The CGS script interface also provides the sessionKey when signed in. This can be used to make REST API calls with the user's current authentication. This allows using the CGS script interface solely for authentication, and then using the resulting sessionKey to make REST API calls.

For completeness the CGS script interface does provide equivalent features to the plugin, but note this is a subset of all the available features in the REST API.

CGS APIs

isSignedIn

Read-only boolean indicating if the player is currently signed in.

canSignInPersistent

Read-only boolean indicating if persistent sign in with signInPersistent() is available.

playerId

A read-only string of the unique player ID when signed in.

playerName

A read-only string of the player display name when signed in.

gameId

A read-only string of the game ID signed in to when signed in.

sessionKey

When signed in, a string with the session key for this sign in. This can be used to make REST API calls using the same authentication.

signInWithProvider(provider, gameId, options)

Attempt to sign the user in with a third-party identity service like Google or Microsoft. provider must be one of: "Apple", "BattleNet", "BattleNetChina", "Discord", "Facebook", "Github", "Google", "ItchIO", "Microsoft", "Reddit", "Steam", "X", "Yandex". The game ID to sign in to from your Construct Game Services account must be provided. options is an optional object that may provide the following properties:

• allowPersisting: if true a successful sign in is remembered, and may be re-used in future with signInPersistent(). The default is true.


• expiryMins: the time in minutes that sessions remain active. The default is 1440 (24 hours).


• popupWindowWidth and popupWindowHeight: Signing in with a provider will open a popup window, and you can also specify the size of this popup window with these properties. The default is 800x800.

The method returns a Promise that resolves when sign in has completed successfully, or rejects if sign in fails or is cancelled.

signInPersistent(gameId)

Attempt to sign in re-using a previous successful sign in that allowed persisting. This can only be used when canSignInPersistent is true. This returns a Promise that resolves when the persistent sign in has completed.

signOut()

Sign out of any account the user is currently signed in to, and also delete any remembered sign in if it allowed persisting. Locally this operation completes immediately. For completeness signing out will send a request in the background to ensure the session is ended on the server-side as well, but that is optional and if it fails the session will time out anyway. This method returns a Promise that resolves when the background request completes, but failure should not be considered significant.

submitScore(score, leaderboardId)

Submit a score to a leaderboard. score must be an integer (fractional scores are not supported). leaderboardId may be omitted to submit a score on the Construct Arcade, which does not require authentication. Otherwise it must be set to the leaderboard ID to submit the score to, in which case authentication is required. This method returns a Promise that resolves when the score has been successfully submitted.

getLeaderboardScores(leaderboardId, options)

Request a page of scores from a given leaderboard ID. This does not require authentication. The returned scores can optionally be filtered with several options, which may include:

• resultsPerPage: the number of results to fetch. The default is 20.


• page: zero-based index of the page to fetch. The default is 0 to retrieve the first page.


• country: an ISO 3166-1 alpha-2 country code filter can be provided, e.g. "US" to only return scores submitted in the United States of America.


• range: a time range to filter results by, which if provided must be one of "Daily", "Weekly", "Monthly" or "Yearly". For example using "Daily" will return today's scores. Weekly leaderboards run from Monday to Sunday. If this property is omitted it returns all scores (which is the default).


• rangeOffset: an offset to return a prior time range when range is specified. For example specifying a "Daily" range with a rangeOffset of 1 will return yesterday's scores.


• culture: a locale to use for returned values. By default it will use the leaderboard's default culture.

This method returns a Promise that resolves with the following object upon success:

• totalPageCount: the total number of pages available


• scores: an array of returned scores, each being an object with the following properties:
  
  
  • score: a number representing this score.
  
  
  • formattedScore: a string with the score formatted according to the culture.
  
  
  • rank: a number representing the score rank.
  
  
  • formattedRank: a string with the rank formatted according to the culture.
  
  
  • country: a string of the ISO 3166-1 alpha-2 country code the score was submitted from.
  
  
  • playerId: a string of the unique player ID who submitted the score.
  
  
  • playerName: a string of the player display name who submitted the score.