Get started with the Extend SDK
Overview
The AccelByte Extend SDK is provided to help developers invoke AccelByte Gaming Services (AGS) endpoints from within their backend code. The Extend SDK is generated from AGS OpenAPI specs and provides required functions such as login, refreshing tokens, validating tokens, and retrying HTTP requests. It is easy to use so developers can focus on what they want to do instead of spending time thinking on how to invoke endpoints.
The AccelByte Extend SDK is available in multiple selected programming languages. We will show you the basics using the Extend SDK in several different languages (Go, Python, C#, Java).
Goals
In this guide you will:
- Create an application project.
- Add the Extend SDK as a project dependency.
- Use the Extend SDK to invoke an AGS endpoint.
- Run the application.
Prerequisites
In order to start on this guide, you should have:
- Go
- Python
- C#
- Java
- TypeScript
- Access to the AccelByte Gaming Services (AGS) (demo environment):
- Use
<your environment's domain URL>
forAB_BASE_URL
environment variable.- Example for AGS Shared Cloud customer:
https://spaceshooter.prod.gamingservices.accelbyte.io
- Example for AGS Private Cloud customer:
https://dev.customer.accelbyte.io
- Example for AGS Shared Cloud customer:
- Create an Oauth Client with client type Confidential.
- Use Client ID value for
AB_CLIENT_ID
environment variable. - Use Client Secret value for
AB_CLIENT_SECRET
environment variable.
- Use Client ID value for
- Use
- AccelByte Go Extend SDK
- Access to the following tools:
- Git
- Go 1.18 or later.
- Go IDE
- Access to the AccelByte Gaming Services (AGS) (demo environment):
- Use
<your environment's domain URL>
forAB_BASE_URL
environment variable.- Example for AGS Shared Cloud customer:
https://spaceshooter.prod.gamingservices.accelbyte.io
- Example for AGS Private Cloud customer:
https://dev.customer.accelbyte.io
- Example for AGS Shared Cloud customer:
- Create an OAuth Client with client type Confidential.
- Use Client ID value for
AB_CLIENT_ID
environment variable. - Use Client Secret value for
AB_CLIENT_SECRET
environment variable.
- Use Client ID value for
- Use
- AccelByte Python Extend SDK
- Access to the following tools:
- Git
- Python 3.10
- Python IDE
- Access to the AccelByte Gaming Services (AGS) (demo environment):
- Use
<your environment's domain URL>
forAB_BASE_URL
environment variable.- Example for AGS Shared Cloud customer:
https://spaceshooter.prod.gamingservices.accelbyte.io
- Example for AGS Private Cloud customer:
https://dev.customer.accelbyte.io
- Example for AGS Shared Cloud customer:
- Create an Oauth Client with client type Confidential.
- Use Client ID value for
AB_CLIENT_ID
environment variable. - Use Client Secret value for
AB_CLIENT_SECRET
environment variable.
- Use Client ID value for
- Use
- AccelByte .NET (C#) Extend SDK
- Access to the following tools:
- Git
- .NET SDK 6.0
- C# IDE
- Access to the AccelByte Gaming Services (AGS) (demo environment):
- Use
<your environment's domain URL>
forAB_BASE_URL
environment variable.- Example for AGS Shared Cloud customer:
https://spaceshooter.prod.gamingservices.accelbyte.io
- Example for AGS Private Cloud customer:
https://dev.customer.accelbyte.io
- Example for AGS Shared Cloud customer:
- Create an Oauth Client with client type Confidential.
- Use Client ID value for
AB_CLIENT_ID
environment variable. - Use Client Secret value for
AB_CLIENT_SECRET
environment variable.
- Use Client ID value for
- Use
- AccelByte Java Extend SDK
- Access to the following tools:
- Git
- Java Development Kit (JDK) 8
- Gradle 7
- Java IDE
Typescript SDK is still under development. Some Extend SDK features may not be available yet
- Access to the AccelByte Gaming Services (AGS) (demo environment):
- Use
<your environment's domain URL>
forAB_BASE_URL
environment variable.- Example for AGS Shared Cloud customer:
https://spaceshooter.prod.gamingservices.accelbyte.io
- Example for AGS Private Cloud customer:
https://dev.customer.accelbyte.io
- Example for AGS Shared Cloud customer:
- Create an Oauth Client with client type Confidential.
- Use Client ID value for
AB_CLIENT_ID
environment variable. - Use Client Secret value for
AB_CLIENT_SECRET
environment variable.
- Use Client ID value for
- Use
- AccelByte TypeScript SDK
- Access to the following tools:
- Git
- Node.js 18 or later
- npm or preferred package manager
Create a project
- Go
- Python
- C#
- Java
- TypeScript
Create a folder and use go mod init
to create a new Go application project:
$ mkdir getting-started
$ cd getting-started/
$ go mod init golang-application
Create a folder and use venv
to create a Python virtual environment.
For macOS or Linux (Bash) user:
$ mkdir myproject
$ cd myproject/
$ python -m venv venv
$ source venv/bin/activate
$ python -c "import sys; print(sys.executable)" # Check which Python executable is active
For Windows(PowerShell) user:
C:\> mkdir myproject
C:\> cd myproject/
C:\> python -m venv venv
C:\> venv\Scripts\Activate.ps1
C:\> python -c "import sys; print(sys.executable)" # Check which Python executable is active
Create a new solution and a new console project inside the solution using dotnet
CLI.
$ mkdir -p /path/to/mysolution
$ cd /path/to/mysolution
$ dotnet new sln --name mysolution # Create a new solution: mysolution
$ dotnet new console -o myproject # Create a new console project myproject
$ dotnet sln add myproject/myproject.csproj # Add myproject to mysolution
Create a folder and use gradle init
to create a Java project.
$ mkdir myproject
$ cd myproject/
$ gradle init --type java-application --dsl groovy --test-framework junit-jupiter
Welcome to Gradle 7.4.2!
Here are the highlights of this release:
- Aggregated test and JaCoCo reports
- Marking additional test source directories as tests in IntelliJ
- Support for Adoptium JDKs in Java toolchains
For more details see https://docs.gradle.org/7.4.2/release-notes.html
Starting a Gradle Daemon (subsequent builds will be faster)
Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no]
Project name (default: myproject):
Source package (default: myproject):
> Task :init
Get more help with your project: https://docs.gradle.org/7.4.2/samples/sample_building_java_applications.html
BUILD SUCCESSFUL in 19s
2 actionable tasks: 2 executed
Create a folder and use npm init -y
to create a new JavaScript application project:
$ mkdir getting-started
$ cd getting-started
$ npm init -y
Add to project dependency
- Go
- Python
- C#
- Java
- TypeScript
Add the Go Extend SDK in the newly created
go.mod
file.Replace
{VERSION}
in thego.mod
file with a specific release version tag without the leadingv
character, then rungo mod tidy
.module golang-application
go 1.18
require (
github.com/AccelByte/accelbyte-go-sdk {VERSION}
)
We recommended using the Go Extend SDK version that matches your AGS version.
Install the SDK dependencies.
$ pip install requests httpx websockets pyyaml
Install the SDK.
$ pip install git+https://github.com/AccelByte/accelbyte-python-sdk.git@{VERSION}#egg=accelbyte_py_sdk
We recommended using the Python Extend SDK version that matches your AGS version.
Get a release version of the AccelByte C# Extend SDK and add it as a C# project dependency.
Replace
{VERSION}
with a specific release version tag.$ git clone https://github.com/AccelByte/accelbyte-csharp-sdk.git # Clone AccelByte C# Extend SDK
$ cd accelbyte-csharp-sdk
$ git checkout {VERSION} # Switch to a specific release {VERSION}
$ cp -rv AccelByte.Sdk /path/to/mysolution/AccelByte.Sdk # Copy AccelByte C# Extend SDK source code
$ cd /path/to/mysolution
$ dotnet sln add AccelByte.Sdk/AccelByte.Sdk.csproj # Add AccelByte C# Extend SDK to solution
$ cd myproject
$ dotnet add reference ../AccelByte.Sdk/AccelByte.Sdk.csproj # Add AccelByte C# Extend SDK as a dependency of C# project
We recommended using the .NET (C#) Extend SDK version that matches your AGS version.
Add the required configuration in
build.gradle
.Replace
{VERSION}
with a specific release version tag without the leadingv
character.
// build.gradle
repositories {
mavenCentral()
...
}
dependencies {
...
implementation 'net.accelbyte.sdk:sdk:{VERSION}'
}
We recommended using the Java Extend SDK version that matches your AGS version.
We recommend installing the TypeScript SDK via npm using your preferred package manager. Open your terminal and run this command:
npm install @accelbyte/sdk @accelbyte/sdk-iam @accelbyte/sdk-basic # Add more SDK packages as needed
Next, ensure "type": "module"
is set in your package.json
.
Important: You must specifically install @accelbyte/sdk
in your project as it has been moved to peerDependencies
in other @accelbyte/sdk-*
packages. This ensures that the core SDK is shared across all related modules.
Optional: If you plan to use our generated React Query hooks, you’ll also need to install @tanstack/query
. Note that we currently only support v4.
npm install @tanstack/react-query@4.36.1
Refer to the AGS APIs section to see the full list of services and SDK offered by AccelByte.
Use in code
- Go
- Python
- C#
- Java
- TypeScript
- Create an SDK instance, log in using client credentials, and call an AGS API in
main.go
. - The
DefaultConfigRepositoryImpl
gets its values fromAB_BASE_URL
,AB_CLIENT_ID
, andAB_CLIENT_SECRET
environment variables.
package main
import (
"github.com/AccelByte/accelbyte-go-sdk/iam-sdk/pkg/iamclient/o_auth2_0_extension"
"github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/utils/auth"
"github.com/sirupsen/logrus"
"github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/factory"
"github.com/AccelByte/accelbyte-go-sdk/services-api/pkg/service/iam"
)
var (
// Use the default Go Extend SDK config and token repository implementation
configRepo = *auth.DefaultConfigRepositoryImpl()
tokenRepo = *auth.DefaultTokenRepositoryImpl()
)
func main() {
// Prepare the IAM Oauth service which contains the `LoginClient` function
oauth := &iam.OAuth20Service{
Client: factory.NewIamClient(&configRepo),
ConfigRepository: &configRepo,
TokenRepository: &tokenRepo,
}
clientId := oauth.ConfigRepository.GetClientId()
clientSecret := oauth.ConfigRepository.GetClientSecret()
// Login using Oauth Client credentials
err := oauth.LoginClient(&clientId, &clientSecret)
if err != nil {
logrus.Error("failed login client")
} else {
logrus.Info("successful login")
}
// Print out access token we get after login
token, _ := oauth.TokenRepository.GetToken()
logrus.Infof("print %v", *token.AccessToken)
// Prepare the IAM's Oauth 2.0 Extension service which contains the `GetCountryLocationV3` function
oAuth20ExtensionService := &iam.OAuth20ExtensionService{
Client: factory.NewIamClient(&configRepo),
TokenRepository: &tokenRepo,
}
input := &o_auth2_0_extension.GetCountryLocationV3Params{}
// Call the AGS endpoint `GetCountryLocationV3`
ok, errLoc := oAuth20ExtensionService.GetCountryLocationV3Short(input)
if errLoc != nil {
logrus.Error(errLoc.Error())
} else {
logrus.Infof("Country name: %s", *ok.CountryName)
}
}
- Create an SDK instance, log in using client credentials, and call an AGS API in
app.py
. - The
EnvironmentConfigRepository
gets its values fromAB_BASE_URL
,AB_CLIENT_ID
, andAB_CLIENT_SECRET
environment variables.
# app.py
import accelbyte_py_sdk
from accelbyte_py_sdk.core import (
RequestsHttpClient,
EnvironmentConfigRepository,
InMemoryTokenRepository,
)
import accelbyte_py_sdk.services.auth as auth_service
import accelbyte_py_sdk.api.iam as iam_service
def main():
# Create default HTTP client, token repository, and config repository instances
http_client = RequestsHttpClient()
config_repository = EnvironmentConfigRepository()
token_repository = InMemoryTokenRepository()
# Initialize the SDK
accelbyte_py_sdk.initialize(
options={
"config": config_repository,
"token": token_repository,
"http": http_client,
}
)
# Login using client credentials
token, error = auth_service.login_client()
if error:
exit(1) # Login failed
# Call an AccelByte Cloud API e.g. GetCountryLocationV3
response, error = iam_service.get_country_location_v3()
if error:
exit(1) # Response error
print(response.country_name)
if __name__ == "__main__":
main()
- Create an SDK instance, log in using user credentials, and call an AccelByte Basic API in
program.cs
. - The
DefaultConfigRepository
gets its values fromAB_BASE_URL
,AB_CLIENT_ID
, andAB_CLIENT_SECRET
environment variables.
using System;
using System.Collections.Generic;
using AccelByte.Sdk.Core;
using AccelByte.Sdk.Api;
using AccelByte.Sdk.Api.Legal.Model;
namespace AccelByteExample
{
internal class Program
{
static int Main(string[] args)
{
AccelByteSDK sdk = AccelByteSDK.Builder
.UseDefaultHttpClient()
.UseDefaultConfigRepository()
.UseDefaultTokenRepository()
.Build();
bool login = sdk.LoginUser("myUsername", "myPassword");
if (!login)
{
Console.WriteLine("Login failed");
return 1;
}
try
{
List<RetrieveAcceptedAgreementResponse>? response = sdk.Legal.Agreement.RetrieveAgreementsPublicOp.Execute();
if (response == null)
throw new Exception("Response is null");
foreach (var agreement in response)
Console.WriteLine(agreement.PolicyName);
}
catch (HttpResponseException e)
{
Console.WriteLine(e.Message);
return 2;
}
bool logout = sdk.Logout();
if (!logout)
{
Console.WriteLine("Logout failed");
return 1;
}
return 0;
}
}
}
- Create an SDK instance, log in using client credentials, and call an AGS API in
App.java
. - The
DefaultConfigRepository
gets its values fromAB_BASE_URL
,AB_CLIENT_ID
, andAB_CLIENT_SECRET
environment variables.
// App.java
package myproject;
import net.accelbyte.sdk.api.iam.models.OauthmodelCountryLocationResponse;
import net.accelbyte.sdk.api.iam.operations.o_auth2_0_extension.GetCountryLocationV3;
import net.accelbyte.sdk.api.iam.wrappers.OAuth20Extension;
import net.accelbyte.sdk.core.AccelByteSDK;
import net.accelbyte.sdk.core.client.OkhttpClient;
import net.accelbyte.sdk.core.repository.DefaultConfigRepository;
import net.accelbyte.sdk.core.repository.DefaultTokenRepository;
public class App {
public static void main(String[] args) throws Exception {
// Create default HTTP client, token repository, and config repository instance
OkhttpClient httpClient = new OkhttpClient();
DefaultTokenRepository tokenRepository = new DefaultTokenRepository();
DefaultConfigRepository configRepository = new DefaultConfigRepository();
// Create SDK instance
AccelByteSDK sdk = new AccelByteSDK(
httpClient,
tokenRepository,
configRepository);
// Login using client credentials
boolean isLoginOk = sdk.loginClient();
if (!isLoginOk) {
System.exit(1); // Login failed
}
// Call an AccelByte Cloud endpoint e.g. GetCountryLocationV3
OAuth20Extension wrapper = new OAuth20Extension(sdk);
GetCountryLocationV3 operation = GetCountryLocationV3.builder()
.build();
OauthmodelCountryLocationResponse response = wrapper.getCountryLocationV3(operation);
System.out.println(response.getCountryName());
}
}
To begin using the AGS TypeScript SDK, you'll need to instantiate it with some basic configuration, including an IAM Client ID (clientId
) and other core settings. Depending on your application, you may want to store environment variables in a .env
file and load them using your development tools (e.g., via process.env.ENV_KEY
).
// index.mjs
import { AccelByte } from '@accelbyte/sdk';
import { OAuth20Api } from '@accelbyte/sdk-iam';
import { CurrencyApi, ItemApi } from '@accelbyte/sdk-platform'
const sdk = AccelByte.SDK({
coreConfig: {
baseURL: process.env.AB_BASE_URL || '',
clientId: process.env.AB_CLIENT_ID || '',
redirectURI: process.env.AB_REDIRECT_URI || '',
namespace: process.env.AB_NAMESPACE || ''
}
});
const main = async () => {
try {
const response = await OAuth20Api(sdk, {axiosConfig: {request: {
headers: {
Authorization: `Basic ${Buffer.from(`${process.env.AB_CLIENT_ID}:${process.env.AB_CLIENT_SECRET}`).toString('base64')}`
}
}}}).postOauthToken_v3({ grant_type: 'client_credentials' })
if (!response.data.access_token) {
throw new Error('Login failed')
}
sdk.setToken({accessToken: response.data.access_token, refreshToken: response.data.refresh_token})
const currenciesResponse = await CurrencyApi(sdk).getCurrencies()
console.log(currenciesResponse.data)
const itemResponse = await ItemApi(sdk).getItemsByCriteria()
console.log(itemResponse.data)
} catch (error) {
console.error(error)
}
}
main()
Note: When setting up IAM Clients, ensure that you include an additional Redirect URI with the format {namespace}.prod.gamingservices.accelbyte.io
(e.g., accelbyte.prod.gamingservices.accelbyte.io
).
Run the code
- Go
- Python
- C#
- Java
- TypeScript
Set the required environment variables and run the application, using go run main.go
.
$ export AB_BASE_URL="<your environment's domain URL>" # AccelByte Cloud Base URL e.g. demo environment
$ export AB_CLIENT_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # Put AccelByte Cloud OAuth Client ID
$ export AB_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # Put AccelByte Cloud OAuth Client Secret
$ go run main.go
Set the required environment variables and run the code using the Python interpreter.
$ export AB_BASE_URL="<your environment's domain URL>" # AccelByte Cloud Base URL e.g. demo environment
$ export AB_CLIENT_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # AccelByte Cloud OAuth Client ID
$ export AB_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # AccelByte Cloud OAuth Client Secret
$ python app.py
Set the required environment variables and run the code using dotnet run
.
$ export AB_BASE_URL="<your environment's domain URL>" # AccelByte Cloud Base URL e.g. demo environment
$ export AB_CLIENT_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # AccelByte Cloud OAuth Client ID
$ export AB_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # AccelByte Cloud OAuth Client Secret
$ cd /path/to/mysolution/myproject
$ dotnet run
Set the required environment variables and run the code using gradle run
.
$ export AB_BASE_URL="<your environment's domain URL>" # AccelByte Cloud Base URL e.g. demo environment
$ export AB_CLIENT_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # AccelByte Cloud OAuth Client ID
$ export AB_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # AccelByte Cloud OAuth Client Secret
$ gradle run
Set the required environment variables and run the code using node index.mjs
.
$ export AB_BASE_URL="<your environment's domain URL>" # AccelByte Cloud Base URL e.g. demo environment
$ export AB_CLIENT_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # AccelByte Cloud IAM Client ID
$ export AB_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # AccelByte Cloud IAM Client Secret
$ export AB_NAMESPACE="<your created namespace>" # AccelByte Namespace
$ export AB_REDIRECT_URI="<your redirect uri>" # AccelByte IAM Client's Redirect URI
$ node index.mjs
Additional resources
- Go
- Python
- C#
- Java
- TypeScript
- Go Extend SDK README for Extend SDK setup and usage
- Go Extend SDK common use cases for a selection of common use cases for customizing your game
- Go Extend SDK sample projects for some sample projects that use Extend SDK
- Go Extend SDK reference for code examples of all operations supported by Extend SDK
- Python Extend SDK README for Extend SDK setup and usage
- Python Extend SDK common use cases for a selection of Extend SDK common use cases for customizing your game
- Python Extend SDK sample projects for some sample projects that use Extend SDK
- Python Extend SDK reference for code examples of all operations supported by Extend SDK
- .NET (C#) Extend SDK README for Extend SDK setup and usage
- .NET (C#) Extend SDK common use cases for a selection of Extend SDK common use cases for customizing your game
- .NET (C#) Extend SDK sample projects for some sample projects that use Extend SDK
- .NET (C#) Extend SDK reference for code examples of all operations supported by Extend SDK
- Java Extend SDK README for Extend SDK setup and usage
- Java Extend SDK common use cases for a selection of Extend SDK common use cases for customizing your game
- Java Extend SDK sample projects for some sample projects that use Extend SDK
- Java Extend SDK code examples for code examples of all operations supported by Extend SDK
- TypeScript SDK README for Extend SDK setup and usage
- TypeScript SDK example projects for some sample projects that use Extend SDK