@playpulse/sdk

Official JavaScript/TypeScript SDK for PlayPulse Gamification Framework.

Installation

npm install @playpulse/sdk
# or
pnpm add @playpulse/sdk
# or
yarn add @playpulse/sdk

Quick Start

Basic Usage

import { PlayPulse } from '@playpulse/sdk'

const playpulse = new PlayPulse({
  apiKey: 'pp_live_xxx',
  projectId: 'your-project-id',
})

// Identify a player
const player = await playpulse.identify('user-123', {
  displayName: 'John Doe',
})

// Track an event
await playpulse.trackEvent('purchase', {
  productId: 'item-456',
  amount: 9.99,
})

// Get player state
console.log(player.xp, player.level, player.currencies)

React Integration

import { PlayPulseProvider, usePlayer, useTrackEvent } from '@playpulse/sdk/react'

function App() {
  return (
    <PlayPulseProvider
      config={{
        apiKey: 'pp_live_xxx',
        projectId: 'your-project-id',
      }}
    >
      <GameUI />
    </PlayPulseProvider>
  )
}

function GameUI() {
  const { player, identify, isLoading } = usePlayer()
  const { trackEvent } = useTrackEvent()

  useEffect(() => {
    identify('user-123')
  }, [])

  if (isLoading) return <div>Loading...</div>
  if (!player) return <div>Not logged in</div>

  return (
    <div>
      <h1>Welcome, {player.displayName}!</h1>
      <p>Level: {player.level}</p>
      <p>XP: {player.xp}</p>
      <button onClick={() => trackEvent('button_click')}>
        Click me!
      </button>
    </div>
  )
}

API Reference

PlayPulse Client

const playpulse = new PlayPulse({
  apiKey: string,           // Required: Your API key
  projectId: string,        // Required: Your project ID
  baseUrl?: string,         // Optional: API base URL
  wsUrl?: string,           // Optional: WebSocket URL
  timeout?: number,         // Optional: Request timeout (ms)
  debug?: boolean,          // Optional: Enable debug logging
})

Core Methods

• identify(externalUserId, options?) - Identify/create a player
• trackEvent(eventName, properties?, idempotencyKey?) - Track an event
• trackEvents(events) - Track multiple events
• connect(token) - Connect to WebSocket
• disconnect() - Disconnect from WebSocket
• on(eventType, handler) - Listen to WebSocket events
• getPlayer() - Get current player
• reset() - Reset player state

API Modules

• playpulse.players - Player management
• playpulse.events - Event tracking
• playpulse.quests - Quest management
• playpulse.adventures - Adventure/season management
• playpulse.leaderboards - Leaderboard access
• playpulse.lobbies - Lobby management
• playpulse.chat - Chat functionality

React Hooks

• usePlayer() - Player state and actions
• useQuests() - Quest progress and actions
• useLeaderboard(id) - Leaderboard entries
• useLobby(id?) - Lobby state and actions
• useChat(channelId) - Chat messages and sending
• useWebSocket() - WebSocket connection state
• useTrackEvent() - Event tracking
• useEvent(type, handler) - Listen to specific events

WebSocket Events

Subscribe to real-time updates:

playpulse.on('xp_updated', (data) => {
  console.log('New XP:', data.newXp)
})

playpulse.on('level_up', (data) => {
  console.log('Leveled up to:', data.newLevel)
})

playpulse.on('quest_completed', (data) => {
  console.log('Quest completed:', data.questId)
})

License

MIT