JavaScript Setup

Install, validate, and configure the JavaScript SDK.

Install the public package, configure it with a runtime key, and start with PersistlyGameSaves before using lower-level runtime APIs.

Install

Install the public JavaScript package instead of building from a private checkout.

TERMINAL

npm install @persistlyapp/sdk

No Build Step

Use jsDelivr for plain HTML prototypes and quick demos.

For production apps, prefer npm plus your normal bundler. The jsDelivr ESM import is useful when a small browser demo should run from one HTML file.

HTML

<script type="module">
  import {
    PersistlyGameSaveStatus,
    PersistlyGameSaves,
  } from "https://cdn.jsdelivr.net/npm/@persistlyapp/sdk@1/+esm";

  await PersistlyGameSaves.configure({
    runtimeKey: "ps_test_replace_me",
  });

  await PersistlyGameSaves.shared.saveData({
    level: 1,
    coins: 50,
  });

  const sync = await PersistlyGameSaves.shared.forceSyncData();

  if (sync.status === PersistlyGameSaveStatus.Synced) {
    console.log("Synced to Persistly.");
  }
</script>

Configure

Use only a runtime key for the normal browser setup.

TYPESCRIPT

import { PersistlyGameSaves } from "@persistlyapp/sdk";

await PersistlyGameSaves.configure({
  runtimeKey: "ps_test_replace_me",
});

Package

Use the public package and repository as the integration source of truth.

Normal browser integrations only need a runtime key. Persistly uses its built-in localStorage adapter by default; pass storageHelper only if your game needs a custom local storage implementation.

Package

@persistlyapp/sdk

Install this package for browser games, Vite apps, and JavaScript wrappers.

Open npm package

Repository

persistly-sdk-js

Use the public GitHub repository for source, releases, and examples.

Open GitHub repo

CDN

jsDelivr ESM import

Use this import URL for plain HTML demos, quick browser prototypes, and no-build examples.

Open CDN module

Avoid These Mistakes

Set the integration boundary correctly from the first commit.

Do not use playerRef as a public runtime lookup key from shipped clients.

Do not start with raw create/load/sync unless you intentionally need the advanced runtime contract.

Do not compare raw status strings. Use PersistlyGameSaveStatus and PersistlySyncStatus constants.