Import Options

@verse8/platform ships three entry points. The VXShop API is identical across all three — only the import shape differs.

This page is a side-by-side reference. For end-to-end integration walkthroughs, see Implement Shop (React) or Implement Shop (Vanilla).

React Apps

import { useVXShop } from '@verse8/platform';

A thin React 18 hook around the shared VXShop store. Auto-refreshes on first mount; subsequent mounts read from the cached store. Pulls react as a peer dependency.

Vanilla ESM / CJS — No React Peer

import { VXShop } from '@verse8/platform/vanilla';

Use this from any bundler (Vite, webpack, esbuild, Rollup) when you don’t want to install React. The /vanilla subpath is React-free at module-load time. Tree-shakable — import { init, getItem } from '@verse8/platform/vanilla' drops the unused methods.

Script Tag (CDN, no build step)

<script src="https://unpkg.com/@verse8/platform/dist/index.global.js"></script>
<script>
  // `window.VXShop` is now available
  VXShop.init();
  VXShop.buyItem('remove-ads');
</script>

For plain HTML pages, prototypes, single-file games, or host pages around a Unity WebGL / non-JS engine. Also published via jsdelivr — swap unpkg.com for cdn.jsdelivr.net/npm/... if preferred.

Two Namespaces: VXShop and Verse8

@verse8/platform exposes two namespaces, both available on every entry point above (the script-tag bundle attaches both to window):

• VXShop — the shop API. See Implement Shop (React) or Implement Shop (Vanilla).
• Verse8 — small auth helpers (getUser / parseAuthToken) that read and cryptographically verify the ?auth= token. See Auth Helpers.

VXShop.init() already consumes the ?auth= token internally — you don’t need to wire Verse8 into it manually. The Verse8 helpers exist for cases where you need to read those values yourself.

VXShop API Equivalence

The eight methods on VXShop (and the seven hook return-values on useVXShop) behave identically regardless of import path. Both surfaces share a single in-memory store, so calling VXShop.refresh() from a vanilla page updates state observed by a mounted useVXShop hook in the same page, and vice versa.

Choosing an Entry Point

Parameter Resolution

Each entry point resolves verseId and account from a different set of sources. The biggest gotcha is script-tag mode cannot read build-time environment variables — there’s no build context for a CDN-loaded <script>.

Priority order (highest first):

• verseId: explicit opts → env → query
• account: explicit opts → query → env

The env source for account is only honored on agent8-games.verse8.io and agent8-container.* hostnames; for other hosts you must use opts or query.

If either field cannot be resolved, the next refresh() records an error in getState().error and subscribe listeners are notified — no exception is thrown.

VXShop.init({ verseId: 'my-verse', account: 'my-account' });

A Note on Compatibility

Next Steps

• Implement Shop (React)
• Implement Shop (Vanilla)
• Premium Subscription Example
• Gacha System Example