playsout-web-sdk 1.0.5 → 1.0.61

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.
Files changed (26) hide show
  1. package/README.md +354 -389
  2. package/chunk-2GXDF6SL.js +2 -0
  3. package/chunk-5YDFNAVU.cjs +2 -0
  4. package/core/api.d.ts +2 -1
  5. package/core/api.d.ts.map +1 -1
  6. package/core/index.d.ts +4 -0
  7. package/core/index.d.ts.map +1 -1
  8. package/core/storage.d.ts +1 -0
  9. package/core/storage.d.ts.map +1 -1
  10. package/core/types.d.ts +1 -1
  11. package/core/types.d.ts.map +1 -1
  12. package/data/games.d.ts.map +1 -1
  13. package/index.cjs +1 -1
  14. package/index.global.js +37 -44
  15. package/index.iife.js +37 -44
  16. package/index.js +1 -1
  17. package/package.json +1 -1
  18. package/react/index.cjs +1 -1
  19. package/react/index.js +1 -1
  20. package/vue/index.cjs +1 -1
  21. package/vue/index.js +1 -1
  22. package/web-components/PlaysoutWidget.d.ts.map +1 -1
  23. package/web-components/index.cjs +0 -7
  24. package/web-components/index.js +0 -7
  25. package/chunk-5IONEDIP.cjs +0 -2
  26. package/chunk-OLKMPDGC.js +0 -2
package/README.md CHANGED
@@ -1,405 +1,370 @@
1
- # Playsout Web SDK Integration Guide
2
-
3
- Playsout Web SDK lets HTML, Vue 3, and React applications embed the Playsout game list widget. It also provides SDK initialization, platform login, login state, user information, locale switching, and user points display.
4
-
5
- This guide is organized so that integrators can select their project type and use the corresponding code directly.
6
-
7
- ## Key Points
8
-
9
- - `appId` is not required.
10
- - Game details use iframe mode by default, so `detailMode` does not need to be provided.
11
- - Persistent SDK image caching is currently disabled. Images use their online URLs directly.
12
- - `user-points` seeds the widget's frontend gem balance. The SDK does not fetch or persist the balance through a backend.
1
+ # Playsout Web SDK Integration Guide
2
+
3
+ Playsout Web SDK lets HTML, Vue 3, and React applications embed the Playsout game list widget. It also provides SDK initialization, platform login, login state, user information, and locale switching.
4
+
5
+ This guide is organized so that integrators can select their project type and use the corresponding code directly.
6
+
7
+ ## Key Points
8
+
9
+ - `appId` is not required.
10
+ - Game details use iframe mode by default, so `detailMode` does not need to be provided.
11
+ - Persistent SDK image caching is currently disabled. Images use their online URLs directly.
13
12
  - In iframe detail mode, games can request simulated gem payment through the `privy-bridge` postMessage protocol.
14
- - Vue 3 projects built with Vite must configure `isCustomElement`.
15
- - React projects do not need Vue's `isCustomElement` configuration. Import `playsout-web-sdk/web-components` once instead.
16
-
17
- ## Installation
18
-
19
- ```bash
20
- npm install playsout-web-sdk
21
- ```
22
-
23
- ## Choose an Integration
24
-
25
- | Project type | Guide |
26
- | --- | --- |
27
- | HTML / IIFE | [HTML integration](#html-integration) |
28
- | Vue 3 + Vite | [Vue 3 integration](#vue-3-integration) |
29
- | React | [React integration](#react-integration) |
30
-
31
- ## Recommended Integration Flow
32
-
33
- Use the following sequence when the application starts:
34
-
35
- 1. Initialize the SDK.
36
- 2. Read the current login state.
37
- 3. If the user is not logged in, call `Login()`.
38
- 4. Render `<playsout-widget>`.
39
- 5. Use `locale` to control the language and `user-points` to display the gem amount.
40
-
41
- During initialization, the SDK checks `expiresAt` and `refreshExpiresAt`. It uses a valid access token directly, refreshes an expired access token when the refresh token is still valid, and clears the session when the refresh token has expired. Do not use `getUserInfo()` as a startup gate. Call it only when a page explicitly needs fresh backend user data, and handle that request error separately so the widget can still render.
42
-
43
- ## Login Parameters
44
-
45
- Grab and Eros use the same public login method:
46
-
47
- ```js
48
- await Playsout.Login(params);
49
- ```
50
-
51
- Required parameters:
52
-
53
- | Parameter | Description |
54
- | --- | --- |
55
- | `platform` | Platform identifier. Use `'grab'` or `'eros'`. |
56
- | `platformUserId` | Unique user ID from the host platform. |
57
- | `platformToken` | Random string. |
58
- | `username` | User display name. |
59
-
60
- Example:
61
-
62
- ```js
63
- await Playsout.Login({
64
- platform: 'eros',
65
- platformUserId: '10',
66
- platformToken: 'random-string',
67
- username: 'TestUser',
68
- });
69
- ```
70
-
71
- `platformToken` is a required, non-empty random string.
72
-
73
- ## HTML Integration
74
-
75
- Use this method for a page that does not use a Vue or React build setup.
76
-
77
- Place the following code in `index.html`:
78
-
79
- ```html
80
- <!doctype html>
81
- <html lang="en">
82
- <head>
83
- <meta charset="UTF-8" />
84
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
85
- <title>Playsout HTML Demo</title>
86
- </head>
87
- <body>
88
- <div id="game-container"></div>
89
-
90
- <script src="https://unpkg.com/playsout-web-sdk/index.iife.js"></script>
91
- <script>
92
- let loginPromise = null;
93
-
94
- function login() {
95
- if (!loginPromise) {
96
- loginPromise = window.Playsout.Login({
97
- platform: 'eros',
98
- platformUserId: '10',
99
- platformToken: 'random-string',
100
- username: 'TestUser'
101
- }).finally(function () {
102
- loginPromise = null;
103
- });
104
- }
105
-
106
- return loginPromise;
107
- }
108
-
109
- async function ensureLogin() {
110
- if (!window.Playsout.isLoggedIn) {
111
- return login();
112
- }
113
- }
114
-
115
- async function bootstrap() {
116
- await window.Playsout.init({ locale: 'zh' });
117
-
118
- window.Playsout.on('authExpired', function () {
119
- login().catch(function (error) {
120
- console.error('Playsout re-login failed:', error);
121
- });
122
- });
123
-
124
- await ensureLogin();
125
-
13
+ - Vue 3 projects built with Vite must configure `isCustomElement`.
14
+ - React projects do not need Vue's `isCustomElement` configuration. Import `playsout-web-sdk/web-components` once instead.
15
+
16
+ ## Installation
17
+
18
+ ```bash
19
+ npm install playsout-web-sdk
20
+ ```
21
+
22
+ ## Choose an Integration
23
+
24
+ | Project type | Guide |
25
+ | --- | --- |
26
+ | HTML / IIFE | [HTML integration](#html-integration) |
27
+ | Vue 3 + Vite | [Vue 3 integration](#vue-3-integration) |
28
+ | React | [React integration](#react-integration) |
29
+
30
+ ## Recommended Integration Flow
31
+
32
+ Use the following sequence when the application starts:
33
+
34
+ 1. Initialize the SDK.
35
+ 2. Read the current login state.
36
+ 3. If the user is not logged in, call `Login()`.
37
+ 4. Render `<playsout-widget>`.
38
+ 5. Use `locale` to control the language.
39
+
40
+ During initialization, the SDK checks the stored token and user information. `isLoggedIn` is `true` only when both are present. It uses a valid access token directly and tries the refresh endpoint when the access token has expired. If refresh is unavailable or fails, the SDK reuses the most recently saved Grab/Eros `Login()` parameters to re-login once. If that recovery also fails, it clears the local authentication state, emits `authExpired`, and rejects the operation. Do not use `getUserInfo()` as a startup gate. Call it only when a page explicitly needs fresh backend user data.
41
+
42
+ ## Login Parameters
43
+
44
+ Grab and Eros use the same public login method:
45
+
46
+ ```js
47
+ await Playsout.Login(params);
48
+ ```
49
+
50
+ Required parameters:
51
+
52
+ | Parameter | Description |
53
+ | --- | --- |
54
+ | `platform` | Platform identifier. Use `'grab'` or `'eros'`. |
55
+ | `platformUserId` | Unique user ID from the host platform. |
56
+ | `platformToken` | Any random non-empty string; there are no other requirements. |
57
+ | `username` | User display name. |
58
+
59
+ Example:
60
+
61
+ ```js
62
+ await Playsout.Login({
63
+ platform: 'eros',
64
+ platformUserId: '10',
65
+ platformToken: 'random-string',
66
+ username: 'TestUser',
67
+ });
68
+ ```
69
+
70
+ `platformToken` is required, but any random non-empty string is accepted.
71
+
72
+ ## HTML Integration
73
+
74
+ Use this method for a page that does not use a Vue or React build setup.
75
+
76
+ Place the following code in `index.html`:
77
+
78
+ ```html
79
+ <!doctype html>
80
+ <html lang="en">
81
+ <head>
82
+ <meta charset="UTF-8" />
83
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
84
+ <title>Playsout HTML Demo</title>
85
+ </head>
86
+ <body>
87
+ <div id="game-container"></div>
88
+
89
+ <script src="https://unpkg.com/playsout-web-sdk/index.iife.js"></script>
90
+ <script>
91
+ let loginPromise = null;
92
+
93
+ function login() {
94
+ if (!loginPromise) {
95
+ loginPromise = window.Playsout.Login({
96
+ platform: 'eros',
97
+ platformUserId: '10',
98
+ platformToken: 'random-string',
99
+ username: 'TestUser'
100
+ }).finally(function () {
101
+ loginPromise = null;
102
+ });
103
+ }
104
+
105
+ return loginPromise;
106
+ }
107
+
108
+ async function ensureLogin() {
109
+ if (!window.Playsout.isLoggedIn) {
110
+ return login();
111
+ }
112
+ }
113
+
114
+ async function bootstrap() {
115
+ await window.Playsout.init({ locale: 'en' });
116
+
117
+ await ensureLogin();
118
+
126
119
  window.Playsout.mount('#game-container');
127
-
128
- document
129
- .querySelector('playsout-widget')
130
- ?.setAttribute('user-points', '1000');
131
- }
132
-
133
- bootstrap().catch(function (error) {
134
- console.error('Playsout bootstrap failed:', error);
135
- });
136
- </script>
137
- </body>
138
- </html>
139
- ```
140
-
141
- Common HTML / IIFE APIs:
142
-
143
- ```js
144
- window.Playsout.init({ locale: 'zh' });
145
- window.Playsout.isLoggedIn;
146
- window.Playsout.Login(params);
147
- window.Playsout.getUserInfo();
148
- window.Playsout.getUser();
149
- window.Playsout.setLocale('en');
150
- window.Playsout.getLocale();
151
- ```
152
-
153
- ## Vue 3 Integration
154
-
155
- ### 1. Configure `vite.config.js`
156
-
157
- Add this configuration to `vite.config.js` or `vite.config.ts` in the Vue project.
158
-
159
- It tells the Vue compiler that `<playsout-widget>` is a native Web Component rather than a Vue component.
160
-
161
- ```js
162
- import { defineConfig } from 'vite';
163
- import vue from '@vitejs/plugin-vue';
164
-
165
- export default defineConfig({
166
- plugins: [
167
- vue({
168
- template: {
169
- compilerOptions: {
170
- isCustomElement: (tag) => tag.startsWith('playsout-'),
171
- },
172
- },
173
- }),
174
- ],
175
- });
176
- ```
177
-
178
- Without this configuration, Vue may report:
179
-
180
- ```text
181
- Failed to resolve component: playsout-widget
182
- ```
183
-
184
- ### 2. Initialize the SDK in `src/main.js`
185
-
186
- Place this code in the Vue entry file, usually `src/main.js` or `src/main.ts`.
187
-
188
- ```js
189
- import { createApp } from 'vue';
190
- import { createPlaysoutPlugin } from 'playsout-web-sdk/vue';
191
- import 'playsout-web-sdk/web-components';
192
- import App from './App.vue';
193
-
194
- const app = createApp(App);
195
-
196
- app.use(createPlaysoutPlugin({
197
- config: {
198
- locale: 'zh',
199
- },
200
- }));
201
-
202
- app.mount('#app');
203
- ```
204
-
205
- `createPlaysoutPlugin({ config })` automatically calls `init(config)` when the plugin is installed. Vue components normally should not call `init()` again.
206
-
207
- ### 3. Use the SDK in the game page
208
-
209
- Place this code in the page component that displays the game list. In a new Vue project, it can be placed directly in `src/App.vue`.
210
-
211
- ```vue
212
- <script setup>
213
- import { watch } from 'vue';
214
- import { usePlaysout } from 'playsout-web-sdk/vue';
215
-
216
- const {
217
- isInitialized,
218
- isLoggedIn,
219
- locale,
220
- Login,
221
- } = usePlaysout();
222
-
223
- let loginPromise = null;
224
-
225
- function login() {
226
- if (!loginPromise) {
227
- loginPromise = Login({
228
- platform: 'eros',
229
- platformUserId: '10',
230
- platformToken: 'random-string',
231
- username: 'TestUser',
232
- }).finally(() => {
233
- loginPromise = null;
234
- });
235
- }
236
-
237
- return loginPromise;
238
- }
239
-
240
- watch([isInitialized, isLoggedIn], ([initialized, loggedIn]) => {
241
- if (!initialized || loggedIn) return;
242
-
243
- login().catch((error) => {
244
- console.error('Playsout login flow failed:', error);
245
- });
246
- }, { immediate: true });
247
- </script>
248
-
249
- <template>
120
+ }
121
+
122
+ bootstrap().catch(function (error) {
123
+ console.error('Playsout bootstrap failed:', error);
124
+ });
125
+ </script>
126
+ </body>
127
+ </html>
128
+ ```
129
+
130
+ Common HTML / IIFE APIs:
131
+
132
+ ```js
133
+ window.Playsout.init({ locale: 'en' });
134
+ window.Playsout.isLoggedIn;
135
+ window.Playsout.Login(params);
136
+ window.Playsout.getUserInfo();
137
+ window.Playsout.getUser();
138
+ window.Playsout.setLocale('en');
139
+ window.Playsout.getLocale();
140
+ ```
141
+
142
+ ## Vue 3 Integration
143
+
144
+ ### 1. Configure `vite.config.js`
145
+
146
+ Add this configuration to `vite.config.js` or `vite.config.ts` in the Vue project.
147
+
148
+ It tells the Vue compiler that `<playsout-widget>` is a native Web Component rather than a Vue component.
149
+
150
+ ```js
151
+ import { defineConfig } from 'vite';
152
+ import vue from '@vitejs/plugin-vue';
153
+
154
+ export default defineConfig({
155
+ plugins: [
156
+ vue({
157
+ template: {
158
+ compilerOptions: {
159
+ isCustomElement: (tag) => tag.startsWith('playsout-'),
160
+ },
161
+ },
162
+ }),
163
+ ],
164
+ });
165
+ ```
166
+
167
+ Without this configuration, Vue may report:
168
+
169
+ ```text
170
+ Failed to resolve component: playsout-widget
171
+ ```
172
+
173
+ ### 2. Initialize the SDK in `src/main.js`
174
+
175
+ Place this code in the Vue entry file, usually `src/main.js` or `src/main.ts`.
176
+
177
+ ```js
178
+ import { createApp } from 'vue';
179
+ import { createPlaysoutPlugin } from 'playsout-web-sdk/vue';
180
+ import 'playsout-web-sdk/web-components';
181
+ import App from './App.vue';
182
+
183
+ const app = createApp(App);
184
+
185
+ app.use(createPlaysoutPlugin({
186
+ config: {
187
+ locale: 'en',
188
+ },
189
+ }));
190
+
191
+ app.mount('#app');
192
+ ```
193
+
194
+ `createPlaysoutPlugin({ config })` automatically calls `init(config)` when the plugin is installed. Vue components normally should not call `init()` again.
195
+
196
+ ### 3. Use the SDK in the game page
197
+
198
+ Place this code in the page component that displays the game list. In a new Vue project, it can be placed directly in `src/App.vue`.
199
+
200
+ ```vue
201
+ <script setup>
202
+ import { watch } from 'vue';
203
+ import { usePlaysout } from 'playsout-web-sdk/vue';
204
+
205
+ const {
206
+ isInitialized,
207
+ isLoggedIn,
208
+ locale,
209
+ Login,
210
+ } = usePlaysout();
211
+
212
+ let initialLoginChecked = false;
213
+
214
+ watch(isInitialized, (initialized) => {
215
+ if (!initialized || initialLoginChecked) return;
216
+ initialLoginChecked = true;
217
+ if (isLoggedIn.value) return;
218
+
219
+ Login({
220
+ platform: 'eros',
221
+ platformUserId: '10',
222
+ platformToken: 'random-string',
223
+ username: 'TestUser',
224
+ }).catch((error) => {
225
+ console.error('Playsout login flow failed:', error);
226
+ });
227
+ }, { immediate: true });
228
+ </script>
229
+
230
+ <template>
250
231
  <playsout-widget
251
232
  :locale="locale"
252
- user-points="1000"
253
233
  />
254
- </template>
255
- ```
256
-
257
- Vue notes:
258
-
234
+ </template>
235
+ ```
236
+
237
+ Vue notes:
238
+
259
239
  - The page waits for plugin initialization, then checks the login state and runs the login flow automatically.
260
240
  - `locale` controls the widget language.
261
- - For a fixed default language, `config: { locale: 'zh' }` in the entry file is sufficient. If the application later needs dynamic locale switching, call `setLocale('en')` and bind `locale`.
262
- - `user-points="1000"` seeds the widget's frontend gem balance. Iframe game payments can deduct from this in-session balance only.
241
+ - For a fixed default language, `config: { locale: 'en' }` in the entry file is sufficient. If the application later needs dynamic locale switching, call `setLocale()` and bind `locale`.
263
242
  - If the application already has a game page, place the logic in that page component.
264
-
265
- ## React Integration
266
-
267
- ### 1. Initialize the SDK in `src/main.jsx`
268
-
269
- Place this code in the React entry file, usually `src/main.jsx` or `src/main.tsx`.
270
-
271
- React does not require `isCustomElement` configuration. Tags containing a hyphen, such as `<playsout-widget>`, are handled as Custom Elements.
272
-
273
- ```jsx
274
- import { createRoot } from 'react-dom/client';
275
- import { PlaysoutProvider } from 'playsout-web-sdk/react';
276
- import 'playsout-web-sdk/web-components';
277
- import App from './App.jsx';
278
-
279
- createRoot(document.getElementById('root')).render(
280
- <PlaysoutProvider config={{ locale: 'zh' }}>
281
- <App />
282
- </PlaysoutProvider>
283
- );
284
- ```
285
-
286
- `PlaysoutProvider` automatically calls `init(config)` after receiving `config`. Page components normally should not call `init()` again.
287
-
288
- ### 2. Use the SDK in the game page
289
-
290
- Place this code in the page component that displays the game list. In a new React project, it can be placed directly in `src/App.jsx`.
291
-
292
- ```jsx
293
- import { useEffect, useRef } from 'react';
294
- import { usePlaysout } from 'playsout-web-sdk/react';
295
-
296
- export default function App() {
297
- const loginInFlight = useRef(false);
298
- const {
299
- isInitialized,
300
- isLoggedIn,
301
- locale,
302
- Login,
303
- } = usePlaysout();
304
-
305
- useEffect(() => {
306
- if (!isInitialized || isLoggedIn || loginInFlight.current) return;
307
- loginInFlight.current = true;
308
-
309
- Login({
310
- platform: 'eros',
311
- platformUserId: '10',
312
- platformToken: 'random-string',
313
- username: 'TestUser',
314
- })
315
- .catch((error) => {
316
- console.error('Playsout login flow failed:', error);
317
- })
318
- .finally(() => {
319
- loginInFlight.current = false;
320
- });
321
- }, [isInitialized, isLoggedIn, Login]);
322
-
243
+
244
+ ## React Integration
245
+
246
+ ### 1. Initialize the SDK in `src/main.jsx`
247
+
248
+ Place this code in the React entry file, usually `src/main.jsx` or `src/main.tsx`.
249
+
250
+ React does not require `isCustomElement` configuration. Tags containing a hyphen, such as `<playsout-widget>`, are handled as Custom Elements.
251
+
252
+ ```jsx
253
+ import { createRoot } from 'react-dom/client';
254
+ import { PlaysoutProvider } from 'playsout-web-sdk/react';
255
+ import 'playsout-web-sdk/web-components';
256
+ import App from './App.jsx';
257
+
258
+ createRoot(document.getElementById('root')).render(
259
+ <PlaysoutProvider config={{ locale: 'en' }}>
260
+ <App />
261
+ </PlaysoutProvider>
262
+ );
263
+ ```
264
+
265
+ `PlaysoutProvider` automatically calls `init(config)` after receiving `config`. Page components normally should not call `init()` again.
266
+
267
+ ### 2. Use the SDK in the game page
268
+
269
+ Place this code in the page component that displays the game list. In a new React project, it can be placed directly in `src/App.jsx`.
270
+
271
+ ```jsx
272
+ import { useEffect, useRef } from 'react';
273
+ import { usePlaysout } from 'playsout-web-sdk/react';
274
+
275
+ export default function App() {
276
+ const initialLoginChecked = useRef(false);
277
+ const {
278
+ isInitialized,
279
+ isLoggedIn,
280
+ locale,
281
+ Login,
282
+ } = usePlaysout();
283
+
284
+ useEffect(() => {
285
+ if (!isInitialized || initialLoginChecked.current) return;
286
+ initialLoginChecked.current = true;
287
+ if (isLoggedIn) return;
288
+
289
+ Login({
290
+ platform: 'eros',
291
+ platformUserId: '10',
292
+ platformToken: 'random-string',
293
+ username: 'TestUser',
294
+ })
295
+ .catch((error) => {
296
+ console.error('Playsout login flow failed:', error);
297
+ });
298
+ }, [isInitialized, isLoggedIn, Login]);
299
+
323
300
  return (
324
301
  <playsout-widget
325
302
  locale={locale}
326
- user-points="1000"
327
303
  />
328
304
  );
329
305
  }
330
- ```
331
-
332
- React notes:
333
-
334
- - `PlaysoutProvider` initializes the SDK.
335
- - After Provider initialization, the page checks the login state and runs the login flow once.
336
- - `usePlaysout()` provides the login state, login method, user information method, and locale APIs.
337
- - For a fixed default language, `<PlaysoutProvider config={{ locale: 'zh' }}>` is sufficient. If the application later needs dynamic locale switching, call `setLocale('en')` and bind `locale`.
338
- - React does not need Vue's `isCustomElement` configuration.
339
-
340
- ## Common API Reference
341
-
342
- | Capability | HTML / IIFE | Vue 3 | React |
343
- | --- | --- | --- | --- |
344
- | Initialize | `Playsout.init(config)` | `createPlaysoutPlugin({ config })` | `<PlaysoutProvider config={...}>` |
345
- | Check login state | `Playsout.isLoggedIn` | `isLoggedIn.value` | `isLoggedIn` |
346
- | Log in | `Playsout.Login(params)` | `Login(params)` | `Login(params)` |
347
- | Fetch latest user information | `Playsout.getUserInfo()` | `Playsout.getUserInfo()` | `getUserInfo()` |
348
- | Read locally stored user information | `Playsout.getUser()` | `Playsout.getUser()` | `user` |
349
- | Change locale | `Playsout.setLocale('en')` | `setLocale('en')` | `setLocale('en')` |
350
- | Read current locale | `Playsout.getLocale()` | `locale.value` | `locale` |
351
- | Log out | `Playsout.logout()` | `logout()` | `logout()` |
352
-
353
- ## Supported Locales
354
-
355
- ```ts
356
- 'zh' | 'en' | 'ja' | 'ko' | 'vi' | 'th' | 'id' | 'ms'
357
- ```
358
-
359
- ## User Points and Simulated Payment
360
-
361
- Pass the value through the `user-points` attribute:
362
-
363
- ```html
364
- <playsout-widget user-points="1000"></playsout-widget>
365
- ```
366
-
367
- The SDK currently does not fetch, persist, or recharge the user's gem amount through a backend. `user-points` is supplied by the host application and becomes the widget's in-session frontend balance.
306
+ ```
307
+
308
+ React notes:
309
+
310
+ - `PlaysoutProvider` initializes the SDK.
311
+ - After Provider initialization, the page checks the login state and runs the login flow once.
312
+ - `usePlaysout()` provides the login state, login method, user information method, and locale APIs.
313
+ - For a fixed default language, `<PlaysoutProvider config={{ locale: 'en' }}>` is sufficient. If the application later needs dynamic locale switching, call `setLocale()` and bind `locale`.
314
+ - React does not need Vue's `isCustomElement` configuration.
315
+
316
+ ## Common API Reference
317
+
318
+ | Capability | HTML / IIFE | Vue 3 | React |
319
+ | --- | --- | --- | --- |
320
+ | Initialize | `Playsout.init(config)` | `createPlaysoutPlugin({ config })` | `<PlaysoutProvider config={...}>` |
321
+ | Check login state | `Playsout.isLoggedIn` | `isLoggedIn.value` | `isLoggedIn` |
322
+ | Log in | `Playsout.Login(params)` | `Login(params)` | `Login(params)` |
323
+ | Fetch latest user information | `Playsout.getUserInfo()` | `Playsout.getUserInfo()` | `getUserInfo()` |
324
+ | Read locally stored user information | `Playsout.getUser()` | `Playsout.getUser()` | `user` |
325
+ | Change locale | `Playsout.setLocale('en')` | `setLocale('en')` | `setLocale('en')` |
326
+ | Read current locale | `Playsout.getLocale()` | `locale.value` | `locale` |
327
+ | Log out | `Playsout.logout()` | `logout()` | `logout()` |
328
+
329
+ ## Supported Locales
330
+
331
+ ```ts
332
+ 'zh' | 'en' | 'ja' | 'ko' | 'vi' | 'th' | 'id' | 'ms'
333
+ ```
334
+
335
+ ## Simulated Payment
368
336
 
369
337
  When a game is opened in iframe detail mode, the widget listens for `privy-bridge` `postMessage` requests from the current iframe only. Supported methods are:
370
-
371
- - `bridge.handshake`
372
- - `auth.getUser`
373
- - `pay.createOrder`
374
- - `pay.request`
375
- - `pay.query`
376
-
377
- `pay.request` opens a localized confirmation dialog. Confirm deducts gems from the in-session balance and emits `gem-balance-change`; cancel and insufficient balance do not deduct gems.
378
-
379
- ## Authentication Expiration
380
-
381
- The SDK handles an expired access token internally:
382
-
383
- 1. A protected API reports that the token is invalid.
384
- 2. The SDK automatically calls the refresh token endpoint.
385
- 3. After a successful refresh, the SDK stores the new token and retries the original request.
386
-
387
- If the refresh token is also invalid, the SDK:
388
-
389
- - Clears the local token.
390
- - Changes the login state to logged out.
391
- - Emits the `authExpired` event.
392
-
393
- HTML / IIFE example:
394
-
395
- ```js
396
- window.Playsout.on('authExpired', function () {
397
- // Get a new platform credential, then call Playsout.Login() again.
398
- });
399
- ```
400
-
401
- React and Vue adapters synchronize their reactive login state when `authExpired` is emitted. A watcher or effect that logs in whenever initialization is complete and `isLoggedIn` becomes false will therefore handle both startup and runtime expiration.
402
-
403
- ## Image Loading
404
-
405
- The SDK currently uses online image URLs directly. Persistent SDK image caching is disabled by default, so the SDK does not proactively store images in persistent browser storage.
338
+
339
+ - `bridge.handshake`
340
+ - `auth.getUser`
341
+ - `pay.createOrder`
342
+ - `pay.request`
343
+ - `pay.query`
344
+
345
+ `pay.request` opens a localized confirmation dialog. Confirm deducts gems from the in-session balance and emits `gem-balance-change`; cancel and insufficient balance do not deduct gems.
346
+
347
+ ## Authentication Expiration
348
+
349
+ The SDK handles authentication recovery internally:
350
+
351
+ 1. When a protected API reports that the access token is invalid, the SDK calls the refresh token endpoint.
352
+ 2. After a successful refresh, the SDK stores the new token and retries the original request.
353
+ 3. If the refresh token is expired or the refresh request fails, the SDK automatically reuses the most recently saved Grab/Eros `Login()` parameters and re-logs in once.
354
+ 4. After a successful re-login, the SDK stores both the new token and user information, then retries the original request.
355
+
356
+ The automatic re-login is attempted at most once for an authentication recovery. If it fails, the SDK clears the stored token, user information, and reusable login parameters, changes `isLoggedIn` to `false`, emits `authExpired`, and throws the error to the calling application. TikTok login parameters are not reused automatically.
357
+
358
+ `authExpired` is an optional final-failure notification. Do not start another automatic login loop from this event:
359
+
360
+ ```js
361
+ window.Playsout.on('authExpired', function () {
362
+ console.error('Playsout authentication recovery failed');
363
+ });
364
+ ```
365
+
366
+ React and Vue adapters synchronize their reactive login state after final recovery failure. The application should catch the failed SDK operation and decide how to present the error to the user.
367
+
368
+ ## Image Loading
369
+
370
+ The SDK currently uses online image URLs directly. Persistent SDK image caching is disabled by default, so the SDK does not proactively store images in persistent browser storage.