playsout-web-sdk 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,226 @@
+# Playsout Web SDK
+
+Playsout Web SDK provides a game list widget, SDK initialization, platform login, login state access, locale switching, and user points display for HTML, React, and Vue projects.
+
+## Installation
+
+```bash
+npm install playsout-web-sdk
+```
+
+## Supported Locales
+
+```ts
+'zh' | 'en' | 'ja' | 'ko' | 'vi' | 'th' | 'id' | 'ms'
+```
+
+## Login Platform Parameters
+
+`appId` is not required.
+
+The public login method is:
+
+```ts
+Playsout.Login(params)
+```
+
+Supported platform values:
+
+| Platform | `platform` |
+| --- | --- |
+| Grab | `grab` |
+| Eros | `eros` |
+
+Login parameters:
+
+```ts
+await Playsout.Login({
+  platform: 'eros',
+  platformUserId: '10',
+  platformToken: 'platform_token',
+  username: 'TestUser',
+});
+```
+
+`platform` should be lowercase. `grab` and `eros` require `platformUserId` and `platformToken`.
+
+## HTML Usage
+
+Use the IIFE build from a CDN or a local copy.
+
+```html
+<div id="game-container"></div>
+
+<script src="https://unpkg.com/playsout-web-sdk/index.iife.js"></script>
+<script>
+  window.Playsout.init({ locale: 'zh' }).then(function () {
+    window.Playsout.mount('#game-container', {
+      theme: 'dark',
+      locale: 'zh',
+      detailMode: 'iframe'
+    });
+
+    document
+      .querySelector('playsout-widget')
+      ?.setAttribute('user-points', '1000');
+  });
+</script>
+```
+
+Login:
+
+```js
+await window.Playsout.Login({
+  platform: 'eros',
+  platformUserId: '10',
+  platformToken: 'platform_token',
+  username: 'TestUser'
+});
+```
+
+Login state:
+
+```js
+window.Playsout.isLoggedIn;
+window.Playsout.getToken();
+window.Playsout.getUser();
+```
+
+Locale:
+
+```js
+window.Playsout.setLocale('en');
+window.Playsout.getLocale();
+```
+
+Auth expiration:
+
+```js
+window.Playsout.on('authExpired', function () {
+  // Get a new platform credential, then call Playsout.Login() again.
+});
+```
+
+## React Usage
+
+Import the Web Component once and initialize the SDK through `PlaysoutProvider`.
+
+```tsx
+import 'playsout-web-sdk/web-components';
+import { PlaysoutProvider } from 'playsout-web-sdk/react';
+
+export function App() {
+  return (
+    <PlaysoutProvider config={{ locale: 'zh' }}>
+      <GamePage />
+    </PlaysoutProvider>
+  );
+}
+
+function GamePage() {
+  return (
+    <playsout-widget
+      locale="zh"
+      user-points="1000"
+      detail-mode="iframe"
+    />
+  );
+}
+```
+
+Use SDK APIs in React:
+
+```tsx
+import { usePlaysout } from 'playsout-web-sdk/react';
+
+function LoginButton() {
+  const { Login, isLoggedIn, user, setLocale } = usePlaysout();
+
+  async function handleLogin() {
+    await Login({
+      platform: 'eros',
+      platformUserId: '10',
+      platformToken: 'platform_token',
+      username: 'TestUser',
+    });
+  }
+
+  return <button onClick={handleLogin}>Login</button>;
+}
+```
+
+## Vue Usage
+
+Initialize the SDK with the Vue plugin.
+
+```ts
+import { createApp } from 'vue';
+import { createPlaysoutPlugin } from 'playsout-web-sdk/vue';
+import 'playsout-web-sdk/web-components';
+import App from './App.vue';
+
+const app = createApp(App);
+
+app.use(createPlaysoutPlugin({
+  config: {
+    locale: 'zh',
+  },
+}));
+
+app.mount('#app');
+```
+
+Use the widget:
+
+```vue
+<template>
+  <playsout-widget
+    locale="zh"
+    user-points="1000"
+    detail-mode="iframe"
+  />
+</template>
+```
+
+Use SDK APIs in Vue:
+
+```vue
+<script setup>
+import { usePlaysout } from 'playsout-web-sdk/vue';
+
+const { Login, isLoggedIn, user, setLocale } = usePlaysout();
+
+async function handleLogin() {
+  await Login({
+    platform: 'eros',
+    platformUserId: '10',
+    platformToken: 'platform_token',
+    username: 'TestUser',
+  });
+}
+</script>
+
+<template>
+  <button @click="handleLogin">Login</button>
+</template>
+```
+
+## User Points
+
+`user-points` is a UI display value passed by the host application.
+
+The SDK does not fetch the user's points balance from the backend.
+
+```html
+<playsout-widget user-points="1000"></playsout-widget>
+```
+
+## Token Expiration
+
+The SDK retries protected requests after refreshing the access token.
+
+If the refresh token is also invalid, the SDK clears local auth data, changes the login state to logged out, and emits `authExpired`. The host application should get a new platform credential and call `Login()` again.
+
+## Image Loading
+
+The SDK uses online image URLs directly. Persistent SDK image caching is disabled by default.