@accelbyte/sdk 4.1.1 → 4.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +127 -50
- package/dist/global/index.global.js +13 -13
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -14,12 +14,12 @@ We recommend installing the TypeScript SDK via npm using your preferred package
|
|
|
14
14
|
npm install @accelbyte/sdk @accelbyte/sdk-iam @accelbyte/sdk-basic # Add more SDK packages as needed
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
> **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.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
_Optional_: If you plan to use our generated React Query hooks, you'll also need to install `@tanstack/react-query`.
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
|
-
npm install @tanstack/react-query
|
|
22
|
+
npm install @tanstack/react-query
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
Refer to the [AccelByte APIs](#accelbyte-apis) section to see the full list of services and SDK offered by AccelByte.
|
|
@@ -39,7 +39,7 @@ const sdk = await AccelByte.SDK({
|
|
|
39
39
|
namespace: "<Your publisher namespace, e.g. 'accelbyte'>"
|
|
40
40
|
},
|
|
41
41
|
axiosConfig: {
|
|
42
|
-
interceptors: [
|
|
42
|
+
interceptors: [
|
|
43
43
|
{
|
|
44
44
|
type: 'response',
|
|
45
45
|
name: 'disconnected',
|
|
@@ -62,9 +62,10 @@ const sdk = await AccelByte.SDK({
|
|
|
62
62
|
|
|
63
63
|
### Configuration breakdown
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
> **Note:** When setting up IAM Clients, ensure that you include an additional Redirect URI with the format `{studio-namespace}.prod.gamingservices.accelbyte.io` (e.g., `accelbyte.prod.gamingservices.accelbyte.io`).
|
|
66
66
|
|
|
67
67
|
- **coreConfig**:
|
|
68
|
+
|
|
68
69
|
- `baseURL`: The base URL for your AGS deployment. This is the starting point for all API requests.
|
|
69
70
|
- `clientId`: The client ID. This is required for authentication with the IAM service. For more information about creating IAM clients, refer to the [AGS Documentation Portal](https://docs.accelbyte.io/gaming-services/services/access/authorization/manage-access-control-for-applications/#create-an-iam-client).
|
|
70
71
|
- `redirectURI`: The URL to which users will be redirected after logging in.
|
|
@@ -79,17 +80,17 @@ const sdk = await AccelByte.SDK({
|
|
|
79
80
|
This is a sample code snippet demonstrating how to use the SDK to interact with AGS:
|
|
80
81
|
|
|
81
82
|
```js
|
|
82
|
-
import { IamUserAuthorizationClient } from '@accelbyte/sdk-iam'
|
|
83
|
-
import { UserProfileApi } from '@accelbyte/sdk-basic'
|
|
83
|
+
import { IamUserAuthorizationClient } from '@accelbyte/sdk-iam'
|
|
84
|
+
import { UserProfileApi } from '@accelbyte/sdk-basic'
|
|
84
85
|
// Log in to IAM using an authorization code
|
|
85
|
-
const token = await new IamUserAuthorizationClient(sdk).loginWithAuthorizationCode({ code, codeVerifier })
|
|
86
|
+
const token = await new IamUserAuthorizationClient(sdk).loginWithAuthorizationCode({ code, codeVerifier })
|
|
86
87
|
// Retrieve the current user profile
|
|
87
|
-
const userProfile = await UsersAdminApi(sdk).getUsersMe_v3()
|
|
88
|
+
const userProfile = await UsersAdminApi(sdk).getUsersMe_v3()
|
|
88
89
|
```
|
|
89
90
|
|
|
90
91
|
## Integrating React Query
|
|
91
92
|
|
|
92
|
-
|
|
93
|
+
> **Note:** This is a browser-only integration.
|
|
93
94
|
|
|
94
95
|
If you're using `@tanstack/react-query` to manage server state, the AGS SDK offers seamless integration through generated queries and mutations. This allows you to efficiently fetch, update, and manage data while leveraging React Query's powerful features like caching, automatic retries, and query invalidation.
|
|
95
96
|
|
|
@@ -98,17 +99,17 @@ If you're using `@tanstack/react-query` to manage server state, the AGS SDK offe
|
|
|
98
99
|
To retrieve data using a generated query, you can use one of the SDK's hooks. The query key used in invalidation can be found within the generated queries.
|
|
99
100
|
|
|
100
101
|
```js
|
|
101
|
-
import { useUsersAdminApi_GetUsersMe_v3 } from '@accelbyte/sdk-iam'
|
|
102
|
+
import { useUsersAdminApi_GetUsersMe_v3 } from '@accelbyte/sdk-iam'
|
|
102
103
|
|
|
103
104
|
const usersQuery = useUsersAdminApi_GetUsersMe_v3(
|
|
104
105
|
sdk,
|
|
105
106
|
{ coreConfig: { namespace }, axiosConfig: {} },
|
|
106
107
|
{
|
|
107
|
-
retry: 2
|
|
108
|
+
retry: 2 // Retry the request twice before failing
|
|
108
109
|
}
|
|
109
|
-
)
|
|
110
|
+
)
|
|
110
111
|
|
|
111
|
-
console.log(usersQuery.data)
|
|
112
|
+
console.log(usersQuery.data)
|
|
112
113
|
```
|
|
113
114
|
|
|
114
115
|
Each generated query comes with unique query keys that you can use for query invalidation when it's necessary to refresh the data. You can view these keys by hovering over the generated query, as shown below:
|
|
@@ -151,11 +152,11 @@ The SDK exposes public endpoints for common operations, but if you need to make
|
|
|
151
152
|
```js
|
|
152
153
|
async function customNetworkCall() {
|
|
153
154
|
try {
|
|
154
|
-
const url = '/iam/v3/public/users/me'
|
|
155
|
-
const network = Network.create(sdk.assembly().axiosConfig.request)
|
|
156
|
-
return await network.get(url)
|
|
155
|
+
const url = '/iam/v3/public/users/me'
|
|
156
|
+
const network = Network.create(sdk.assembly().axiosConfig.request)
|
|
157
|
+
return await network.get(url)
|
|
157
158
|
} catch (err) {
|
|
158
|
-
console.error(err)
|
|
159
|
+
console.error(err)
|
|
159
160
|
}
|
|
160
161
|
}
|
|
161
162
|
```
|
|
@@ -172,10 +173,11 @@ When creating an instance of the AGS SDK using `AccelByte.SDK(config)`, you need
|
|
|
172
173
|
export interface SdkConstructorParam {
|
|
173
174
|
coreConfig: MakeOptional<CoreConfig, 'useSchemaValidation'>
|
|
174
175
|
axiosConfig?: AxiosConfig
|
|
176
|
+
webSocketConfig?: WebSocketConfig
|
|
175
177
|
}
|
|
176
178
|
```
|
|
177
179
|
|
|
178
|
-
This configuration
|
|
180
|
+
This configuration includes three main sections: `coreConfig`, `axiosConfig`, and `webSocketConfig`. Here's a detailed breakdown of each section:
|
|
179
181
|
|
|
180
182
|
#### coreConfig
|
|
181
183
|
|
|
@@ -193,14 +195,13 @@ export interface CoreConfig {
|
|
|
193
195
|
|
|
194
196
|
The following table describes each parameter's function, type, and default value.
|
|
195
197
|
|
|
196
|
-
|
|
197
198
|
| Parameter | Type | Description | Default Value |
|
|
198
|
-
|
|
199
|
-
| `clientId` (required)
|
|
200
|
-
| `redirectURI ` (required)
|
|
201
|
-
| `baseURL` (required)
|
|
202
|
-
| `namespace` (required)
|
|
203
|
-
| `useSchemaValidation`
|
|
199
|
+
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
|
|
200
|
+
| `clientId` (required) | string | The client ID associated with your SDK. You can obtain this from the AGS Admin Portal under OAuth Clients **Game Setup** > **Games and Apps** > **IAM Clients**. | |
|
|
201
|
+
| `redirectURI ` (required) | string | The URI to redirect to after a successful login. This value is crucial for generating a valid login URL to IAM and should match the redirect URI configured in the Admin Portal. | |
|
|
202
|
+
| `baseURL` (required) | string | The URI to redirect to after a successful login. This value is crucial for generating a valid login URL to IAM and should match the redirect URI configured in the Admin Portal. | |
|
|
203
|
+
| `namespace` (required) | string | The namespace associated with your AGS deployment. | |
|
|
204
|
+
| `useSchemaValidation` | boolean | Determines whether the SDK enforces the Zod schema validation at runtime. Setting this to `false` will bypass validation, which might be useful to prevent throwing errors if there are schema mismatches between the Zod model and the backend response. | true |
|
|
204
205
|
|
|
205
206
|
#### axiosConfig (optional)
|
|
206
207
|
|
|
@@ -212,7 +213,9 @@ export interface AxiosConfig {
|
|
|
212
213
|
request?: AxiosRequestConfig;
|
|
213
214
|
}
|
|
214
215
|
```
|
|
215
|
-
|
|
216
|
+
|
|
217
|
+
- `request` (`AxiosRequestConfig`, optional): A configuration object that allows you to set default properties for Axios request, such as headers, timeout settings, or credentials handling. For more information, refer to the [Axios documentation](https://axios-http.com/docs/req_config).
|
|
218
|
+
|
|
216
219
|
- `interceptors` (`Interceptor[]`, optional): An array of interceptor objects that can modify requests or responses. These interceptors provide hooks for adding custom behavior before a request is sent or after a response is received.
|
|
217
220
|
|
|
218
221
|
```js
|
|
@@ -233,15 +236,31 @@ export interface AxiosConfig {
|
|
|
233
236
|
|
|
234
237
|
The following table describes each parameter's function, type, and default value.
|
|
235
238
|
|
|
236
|
-
| Parameter
|
|
237
|
-
|
|
238
|
-
| `type` (required)
|
|
239
|
-
| `name` (required)
|
|
240
|
-
| `onRequest`
|
|
241
|
-
| `onError`
|
|
242
|
-
| `onSuccess`
|
|
239
|
+
| Parameter | Type | Description | Default Value |
|
|
240
|
+
| ----------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
|
|
241
|
+
| `type` (required) | `'request' \| 'response'` | Specifies whether the interceptor should handle requests or responses. | |
|
|
242
|
+
| `name` (required) | string | A unique name for the interceptor. This helps in identifying the interceptor, especially if you have multiple interceptors. | |
|
|
243
|
+
| `onRequest` | `(config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig \| Promise<InternalAxiosRequestConfig>` | A function that processes the request configuration before the request is sent. This can be used to modify the request (e.g., adding headers) or to log the request details. | |
|
|
244
|
+
| `onError` | `(error: unknown) => unknown` | A function that handles errors during the request or response process. This is useful for logging errors or retrying requests under certain conditions. | |
|
|
245
|
+
| `onSuccess` | `(response: AxiosResponse<unknown>) => AxiosResponse<unknown>` | A function that processes the response before it’s passed back to the calling code. This can be used to transform the response data or log successful requests. | |
|
|
243
246
|
|
|
244
|
-
|
|
247
|
+
#### webSocketConfig (optional)
|
|
248
|
+
|
|
249
|
+
This configuration allows customization of the WebSocket reconnection behavior when an abnormal disconnection occurs. By default, the WebSocket connection will attempt to reconnect if it closes unexpectedly.
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
export interface WebSocketConfig {
|
|
253
|
+
allowReconnect?: boolean;
|
|
254
|
+
maxReconnectAttempts?: number;
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
The following table describes each parameter's function, type, and default value.
|
|
259
|
+
|
|
260
|
+
| Parameter | Type | Description | Default Value |
|
|
261
|
+
|-------------------------|-----------|---------------------------------------------------------------------------------------------------------|---------------|
|
|
262
|
+
| `allowReconnect` | `boolean` | Enables automatic reconnection attempts when the WebSocket disconnects unexpectedly. | `true` |
|
|
263
|
+
| `maxReconnectAttempts` | `number` | Sets the maximum number of reconnection attempts. Use `0` for unlimited retries. Only accepts integers. | `0` |
|
|
245
264
|
|
|
246
265
|
### API Class
|
|
247
266
|
|
|
@@ -255,10 +274,70 @@ constructor(sdk: AccelByteSDK, args?: SdkSetConfigParam)
|
|
|
255
274
|
|
|
256
275
|
The following table describes each parameter's function, type, and default value.
|
|
257
276
|
|
|
258
|
-
| Parameter
|
|
259
|
-
|
|
260
|
-
| `sdk` (required)
|
|
261
|
-
| `args`
|
|
277
|
+
| Parameter | Type | Description | Default Value |
|
|
278
|
+
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
|
|
279
|
+
| `sdk` (required) | `AccelByteSDK` | An instance of the AGS SDK | |
|
|
280
|
+
| `args` | `SdkSetConfigParam` | An optional parameter that allows you to override or extend the configuration of the SDK. This includes the core configuration and Axios configuration. | |
|
|
281
|
+
|
|
282
|
+
## WebSocket Client
|
|
283
|
+
|
|
284
|
+
The AGS TypeScript SDK includes support for connecting to the Lobby WebSocket Service, allowing real-time communication and interaction. In addition to connecting, disconnecting, and listening for events, the WebSocket client allows configuration for automatic reconnection on unexpected closures. Here’s an example of how to configure and use the WebSocket client:
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
import { AccelByte } from '@accelbyte/sdk'
|
|
288
|
+
import { Lobby } from '@accelbyte/sdk-lobby'
|
|
289
|
+
|
|
290
|
+
const sdk = AccelByte.SDK({
|
|
291
|
+
coreConfig: {
|
|
292
|
+
baseURL: process.env.AB_BASE_URL || '',
|
|
293
|
+
clientId: process.env.AB_CLIENT_ID || '',
|
|
294
|
+
redirectURI: process.env.AB_REDIRECT_URI || '',
|
|
295
|
+
namespace: process.env.AB_NAMESPACE || ''
|
|
296
|
+
},
|
|
297
|
+
webSocketConfig: {
|
|
298
|
+
// Enable reconnection on abrupt disconnects. Defaults to true.
|
|
299
|
+
allowReconnect: true,
|
|
300
|
+
// Maximum number of reconnect attempts. Set to 0 for unlimited attempts.
|
|
301
|
+
maxReconnectAttempts: 3
|
|
302
|
+
}
|
|
303
|
+
})
|
|
304
|
+
|
|
305
|
+
// Ensure login is complete before connecting
|
|
306
|
+
const lobbyWs = Lobby.WebSocket(sdk)
|
|
307
|
+
|
|
308
|
+
// Connect to WebSocket
|
|
309
|
+
lobbyWs.connect()
|
|
310
|
+
lobbyWs.onOpen(() => console.log("Connected to WebSocket."))
|
|
311
|
+
// Listen for all incoming messages through a single handler
|
|
312
|
+
lobbyWs.onMessage(message => {
|
|
313
|
+
console.log(message)
|
|
314
|
+
})
|
|
315
|
+
lobbyWs.onClose((ev) => {
|
|
316
|
+
console.log("Disconnected from WebSocket.", ev)
|
|
317
|
+
if (sdk.webSocketConfig.allowReconnect) {
|
|
318
|
+
console.log("Attempting reconnection, max attempts:", sdk.webSocketConfig.maxReconnectAttempts)
|
|
319
|
+
}
|
|
320
|
+
})
|
|
321
|
+
|
|
322
|
+
// Disconnect from WebSocket
|
|
323
|
+
await lobbyWs.disconnect()
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
### WebSocket Methods and Properties
|
|
327
|
+
|
|
328
|
+
The `WebSocket` class offers several methods and event listeners for managing WebSocket connections and handling messages. The table below provides details on each available method and property.
|
|
329
|
+
|
|
330
|
+
| Method/Property | Type | Description |
|
|
331
|
+
|----------------------|---------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
|
|
332
|
+
| `connect` | `() => void` | Initiates a connection to the WebSocket server. |
|
|
333
|
+
| `disconnect` | `() => void` | Closes the WebSocket connection, ending communication. |
|
|
334
|
+
| `onOpen` | `(cb: () => void) => void` | Event listener triggered when the WebSocket connection is successfully opened. |
|
|
335
|
+
| `onMessage` | `(cb: (message?: object \| string, raw?: boolean) => void) => void` | Event listener for incoming messages. Messages are parsed into typed objects, unless `raw` is set to true. |
|
|
336
|
+
| `onError` | `(cb: (err?: Error) => void) => void` | Event listener for errors in the WebSocket connection, such as message send failures. |
|
|
337
|
+
| `onClose` | `(cb: (ev?: CloseEvent) => void) => void` | Event listener for connection closure events, which may occur due to errors or manual disconnection. |
|
|
338
|
+
| `send` | `(message?: object) => void` | Sends a message to the WebSocket server. |
|
|
339
|
+
| `send${methodName}` | `(message?: object) => void` | Type-specific `send` methods for predefined messages (e.g., `sendPartyInfo(data)`, `sendPartyCreate(data)`, etc.). |
|
|
340
|
+
| `instance` | `WebSocket` | Provides direct access to the [WebSocket instance](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket) for lower-level control.| |
|
|
262
341
|
|
|
263
342
|
## AGS APIs
|
|
264
343
|
|
|
@@ -288,7 +367,7 @@ TypeScript SDK supports the following AGS APIs:
|
|
|
288
367
|
- [Session History](https://docs.accelbyte.io/api-explorer/#Session%20History): `@accelbyte/sdk-history`
|
|
289
368
|
- **Social**
|
|
290
369
|
- [Chat](https://docs.accelbyte.io/api-explorer/#Chat): `@accelbyte/sdk-chat`
|
|
291
|
-
- [Lobby](https://docs.accelbyte.io/api-explorer/#Lobby%20-%20Friends,%20Presence%20and%20Notifications): `@accelbyte/sdk-lobby`
|
|
370
|
+
- [Lobby](https://docs.accelbyte.io/api-explorer/#Lobby%20-%20Friends,%20Presence%20and%20Notifications): `@accelbyte/sdk-lobby` with websocket support
|
|
292
371
|
- [Groups](https://docs.accelbyte.io/api-explorer/#Groups): `@accelbyte/sdk-groups`
|
|
293
372
|
- **Storage**
|
|
294
373
|
- [CloudSave](https://docs.accelbyte.io/api-explorer/#CloudSave): `@accelbyte/sdk-cloudsave`
|
|
@@ -401,7 +480,7 @@ const sdk = AccelByte.SDK({
|
|
|
401
480
|
return Promise.reject(error)
|
|
402
481
|
}
|
|
403
482
|
},
|
|
404
|
-
// Add more interceptors
|
|
483
|
+
// Add more interceptors
|
|
405
484
|
],
|
|
406
485
|
requests: {}
|
|
407
486
|
}
|
|
@@ -446,7 +525,7 @@ We now offer custom interceptors to replace certain events or options. Here's a
|
|
|
446
525
|
|
|
447
526
|
- **onUserEligibilityChange**
|
|
448
527
|
|
|
449
|
-
|
|
528
|
+
> **Note**: Since there's no dependency on the Internal SDK and it's specific to the application level, we have not created a custom wrapper for it.
|
|
450
529
|
|
|
451
530
|
```js
|
|
452
531
|
{
|
|
@@ -469,7 +548,7 @@ We now offer custom interceptors to replace certain events or options. Here's a
|
|
|
469
548
|
|
|
470
549
|
- **onTooManyRequest**
|
|
471
550
|
|
|
472
|
-
|
|
551
|
+
> **Note**: Since there's no dependency on the Internal SDK and it's specific to the application level, we have not created a custom wrapper for it.
|
|
473
552
|
|
|
474
553
|
```js
|
|
475
554
|
{
|
|
@@ -511,9 +590,9 @@ The `ApiArgs` (the second `*Api` argument) has been replaced by partial `coreCon
|
|
|
511
590
|
|
|
512
591
|
```js
|
|
513
592
|
// Before
|
|
514
|
-
const data = await UsersAdminApi(sdk, { namespace, config: {} }).getUsersMe_v3()
|
|
593
|
+
const data = await UsersAdminApi(sdk, { namespace, config: {} }).getUsersMe_v3()
|
|
515
594
|
// After
|
|
516
|
-
const { data } = await UsersAdminApi(sdk, { coreConfig: { namespace }, axiosConfig }).getUsersMe_v3()
|
|
595
|
+
const { data } = await UsersAdminApi(sdk, { coreConfig: { namespace }, axiosConfig }).getUsersMe_v3()
|
|
517
596
|
```
|
|
518
597
|
|
|
519
598
|
### Admin Class Endpoints
|
|
@@ -521,8 +600,7 @@ const { data } = await UsersAdminApi(sdk, { coreConfig: { namespace }, axiosConf
|
|
|
521
600
|
Admin endpoints that have the "Admin" tag in Swagger will only generate one "Admin" keyword. The `AdminPlayerRecordAdmin` has been replaced by `PlayerRecordAdmin`.
|
|
522
601
|
|
|
523
602
|
```js
|
|
524
|
-
|
|
525
|
-
+ PlayerRecordAdminApi(sdk).getRecords_ByUserId(userId)
|
|
603
|
+
;-AdminPlayerRecordAdminApi(sdk).getRecords_ByUserId(userId) + PlayerRecordAdminApi(sdk).getRecords_ByUserId(userId)
|
|
526
604
|
```
|
|
527
605
|
|
|
528
606
|
### (Extend Functionality) Token Repository
|
|
@@ -549,8 +627,7 @@ getToken() {
|
|
|
549
627
|
The `refreshTokens` method is now replaced by `setToken({ accessToken, refreshToken })` with the same behavior.
|
|
550
628
|
|
|
551
629
|
```js
|
|
552
|
-
|
|
553
|
-
+ sdk.refreshTokens({ accessToken, refreshToken })
|
|
630
|
+
;-sdk.refreshTokens(accessToken, refreshToken) + sdk.refreshTokens({ accessToken, refreshToken })
|
|
554
631
|
```
|
|
555
632
|
|
|
556
633
|
## TypeScript SDK Playground
|
|
@@ -571,4 +648,4 @@ npm install @accelbyte/sdk @accelbyte/sdk-ams @accelbyte/sdk-achievement @accelb
|
|
|
571
648
|
|
|
572
649
|
Thank you for your interest in contributing to the AGS TypeScript SDK. We value your input and appreciate your input to enhancing the AGS TypeScript SDK project. However, please note that direct contributions via GitHub are not currently accepted.
|
|
573
650
|
|
|
574
|
-
Instead, we encourage you to submit your ideas and suggestions as feature requests through the [AccelByte Customer Support Portal](https://accelbyte.atlassian.net/servicedesk/customer/portal/6) or via your Account Manager. This process helps us manage contributions effectively and ensures that each idea is carefully reviewed and considered by our team.
|
|
651
|
+
Instead, we encourage you to submit your ideas and suggestions as feature requests through the [AccelByte Customer Support Portal](https://accelbyte.atlassian.net/servicedesk/customer/portal/6) or via your Account Manager. This process helps us manage contributions effectively and ensures that each idea is carefully reviewed and considered by our team.
|