JavaScript SDK for simple game saves and advanced runtime control.

npm install @persistlyapp/sdk

<script type="module">
  import { 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,
  });
</script>

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

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

const loaded = await PersistlyGameSaves.shared.loadData();

if (loaded.status === PersistlyGameSaveStatus.LocalFound && loaded.data) {
  console.log("Boot from local data:", loaded.data);
} else {
  console.log("Start new game.");
}

// Local write. This does not need a network request.
await PersistlyGameSaves.shared.saveData({
  level: 5,
  coins: 1200,
  checkpoint: "forest-gate",
}, {
  slotInfo: { characterName: "Astra", slot: "main" },
});

// First sync creates a Persistly account + slot if needed.
const sync = await PersistlyGameSaves.shared.forceSyncData();

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

if (sync.status === PersistlyGameSaveStatus.Conflict) {
  console.log("Show a local-vs-cloud recovery UI.");
}

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

await PersistlyGameSaves.shared.saveData(currentGameState);

window.addEventListener("beforeunload", () => {
  void PersistlyGameSaves.shared.forceSyncData();
});

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

await PersistlyGameSaves.shared.saveData(currentGameData);
const result = await PersistlyGameSaves.shared.forceSyncData();

if (result.status === PersistlyGameSaveStatus.Conflict) {
  const save = await PersistlyGameSaves.shared.inspectData();

  // Show local-vs-cloud UI in your game.
  const choice = await askPlayerHowToRecover({
    local: save.data,
    cloud: save.lastCloudData,
  });

  if (choice === "use-cloud") {
    await PersistlyGameSaves.shared.acceptCloudData();
  }

  if (choice === "keep-local") {
    await PersistlyGameSaves.shared.overwriteCloudData();
  }

  if (choice === "decide-later") {
    await PersistlyGameSaves.shared.keepLocalDataForLater();
  }
}

import {
  LocalStorageSaveCache,
  PersistlyClient,
  PersistlySyncStatus,
} from "@persistlyapp/sdk";

const client = new PersistlyClient({
  runtimeKey: process.env.PERSISTLY_RUNTIME_KEY!,
  cache: new LocalStorageSaveCache(),
});

const created = await client.createAccount({
  playerRef: "player-184",
  accountData: { displayName: "Ayla", diamonds: 1200 },
  slot: {
    slotId: "mage",
    slotInfo: {
      characterName: "Ayla"
    },
    data: {
      checkpoint: "vault",
      coins: 418
    }
  }
});

// Persist the account session immediately in your trusted account backend or durable local save store.
// Do not log or expose accountSessionToken in player UI, telemetry, or support screenshots.
const accountSession = {
  accountId: created.accountId,
  accountSessionToken: created.accountSessionToken
};

// Sync the active slot through the account session.
const result = await client.syncAccountSlot({
  accountId: accountSession.accountId,
  accountSessionToken: accountSession.accountSessionToken,
  slotId: "mage",
  slotInfo: created.slot.slotInfo,
  data: {
    checkpoint: "vault",
    coins: 612
  }
});

if (result.status === PersistlySyncStatus.Conflict) {
  const cloudSlot = result.slot;
  // App-specific recovery: show a UI, merge data, or retry local edits from cloudSlot.version.
  console.error("Conflict. Retry from cloud slot version:", cloudSlot.version);
}