VIVERSE SDK

📝 Requirements

• Node.js v20.19.0 or higher

📦 Installation

ES Module

npm install @viverse/sdk

🛠️ Usage

Client

The main client for handling authentication and user information.

Initialization

import { Client } from '@viverse/sdk';

const viverseClient = new Client({
  clientId: 'YOUR_APP_ID', // APP ID
  domain: 'account.htcvive.com', // HTC Account domain
  cookieDomain: 'YOUR_COOKIE_DOMAIN', // Optional — if not provided, the current domain will be used.
});

Login

Login With Worlds:

/**
 * If successful, the `Result` value will be returned.
 * It will also automatically refresh the token if expires_in is less than 180 seconds.
 */

interface Result {
  access_token: string; // The access token to be used in API requests
  account_id: string; // The unique user account ID
  expires_in: number; // Remaining token lifetime in seconds
  state: string; // Optional custom state value from the original login
}

// Step 1: Use loginWithWorlds to login
viverseClient.loginWithWorlds({
  state: '{"page":"/items/123456"}', // Optional — this variable is returned upon successful login.
});

// Step 2: If login successfully, iframe will be refreshed. please use the following functions to check the login status
window.addEventListener('load', async function () {
  const result = await viverseClient.checkAuth() as Result | undefined;
  if (result && result.access_token) {
    // already login
  } else {
    // no logged in
  }
});

Get Token

type TokenResponse = {
  access_token: string;
  account_id: string;
  expires_in: number;
  scope?: string;
  token_type?: string;
  created_at?: number;
  state?: string;
};

// Get the access token
const token = await viverseClient.getToken() as string | undefined;

// Get detailed token response
const detailedToken = await viverseClient.getToken({ detailedResponse: true }) as TokenResponse | undefined;

Avatar

Get user profile and avatar data

Initialization

import { Avatar } from '@viverse/sdk';

const avatarClient = new Avatar({
  baseURL: 'https://sdk-api.viverse.com/',
  token: 'USER_ACCESS_TOKEN', // from viverseClient.getToken()
});

Get User Profile

const profile = await avatarClient.getProfile();

Get User Avatar List

const avatarList = await avatarClient.getAvatarList();

Get User Active Avatar

const activeAvatar = await avatarClient.getActiveAvatar();

Get Public Avatar List

const publicAvatarList = await avatarClient.getPublicAvatarList();

Get Public Avatar By ID

const publicAvatar = await avatarClient.getPublicAvatarByID('PUBLIC_AVATAR_ID');

Get Public Avatar By ID

const avatarArrayBuffer = await avatarClient.getAvatarFileWithSDK('AVATAR_URL');

Game Dashboard

Provides access to game-related features like leaderboards and achievements.

Initialization

import { GameDashboard } from '@viverse/sdk';

const gameDashboardClient = new GameDashboard({
  baseURL: 'https://www.viveport.com/',
  communityBaseURL: 'https://www.viverse.com/',
  token: 'USER_ACCESS_TOKEN', // from viverseClient.getToken()
});

Get Leaderboard Ranking:

const ranking = await gameDashboardClient.getLeaderboard(
  'YOUR_APP_ID',
  {
    name: 'LEADERBOARD_NAME',
    range_start: 0,
    range_end: 100,
    region: 'global', // or 'local'
    time_range: 'alltime', // or 'daily', 'weekly', 'monthly'
    around_user: false,
  }
);

Get Guest Leaderboard Ranking:

const ranking = await gameDashboardClient.getGuestLeaderboard(
  'YOUR_APP_ID',
  {
    name: 'LEADERBOARD_NAME',
    range_start: 0,
    range_end: 100,
    region: 'global', // or 'local'
    time_range: 'alltime', // or 'daily', 'weekly', 'monthly'
    country_code: 'US', // ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'JP', 'TW')
  }
);

Upload Score:

await gameDashboardClient.uploadLeaderboardScore(
  'YOUR_APP_ID',
  [{ name: 'LEADERBOARD_NAME', value: '100.0' }]
);

Get User Achievements:

const achievements = await gameDashboardClient.getUserAchievement('YOUR_APP_ID');

Upload User Achievements:

await gameDashboardClient.uploadUserAchievement(
  'YOUR_APP_ID',
  [{ api_name: 'ACHIEVEMENT_API_NAME', unlock: true }]
);

Play

Handles real-time gameplay features.

Initialization

import { Play } from '@viverse/sdk';

const playClient = new Play();

Matchmaking

const matchmakingClient = playClient.newMatchmakingClient('YOUR_APP_ID');

Multiplayer

const multiplayerClient = playClient.newMultiplayerClient('YOUR_ROOM_ID', 'YOUR_APP_ID', 'USER_SESSION_ID');

Storage

Manages cloud save data.

Initialization

import { Storage } from '@viverse/sdk';

const storageClient = new Storage();

Cloud Save

const cloudSaveClient = storageClient.newCloudSaveClient('YOUR_APP_ID');

📚 Documentation

For further API details, please refer to the VIVERSE Documentation site.

Introduction to Developer Tools