@globalleaderboards/sdk

中文文档
0.5.0发布于 2025/08/01MITTypeScriptESM + CJS近 30 天下载 3985

GlobalLeaderboards.net的官方SDK - 在任何应用程序中加入竞争性领导牌

中文使用文档
文档目录35 节
  1. 安装
  2. 认证
  3. 快速启动
  4. 特征
  5. API 参考
  6. 构造器
  7. 计分方法
  8. 领导板方法
  9. 卫生和信息方法
  10. 服务器事件方法
  11. 网络安全套方法
  12. 网页实例方法
  13. SSE 对 WebSocket
  14. 方法
  15. 离线支持
  16. 如何运作
  17. 基本用途
  18. 队列事件监测
  19. 队列管理
  20. 存储细节
  21. 队列限制和行为
  22. 高级示例
  23. 重要说明
  24. 处理错误
  25. 常见错误代码
  26. 类型脚本支持
  27. 实例
  28. 反应钩子示例
  29. SSE 实时显示示例
  30. 游戏整合示例
  31. API 利率限制
  32. 最佳做法
  33. 文档
  34. 支助
  35. 许可证

@ globalleaderboards/ sdk 页面存档备份,存于互联网档案馆

GlobalLeaderboards.net的官方SDK - 任意添加竞争性领导板 5分钟后申请.

安装

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

认证

SDK采用行业标准 Authorization: Bearer <api-key> 标题 认证。 您的 API 密钥可以从 Global Leader boards 获取 仪表板。 每个 API 密钥与一个特定的应用程序相关联,确保适当的数据 隔离.

const leaderboard = new GlobalLeaderboards('your-api-key')

快速启动

import {GlobalLeaderboards} from '@globalleaderboards/sdk'

// Initialize the SDK
const leaderboard = new GlobalLeaderboards('your-api-key', {
  defaultLeaderboardId: 'your-default-leaderboard' // Optional
})

// Submit a score - three ways
await leaderboard.submit('player-id', 1250) // Uses default leaderboard
await leaderboard.submit('player-id', 1250, 'specific-leaderboard')
await leaderboard.submit('player-id', 1250, {
  leaderboardId: 'your-leaderboard-id',
  userName: 'PlayerOne',
  metadata: { level: 5 }
})

// Get leaderboard
const scores = await leaderboard.getLeaderboard('your-leaderboard-id', {
  limit: 10
})

// Connect to real-time updates

// Recommended: Server-Sent Events (simpler, auto-reconnect, firewall-friendly)
const sse = leaderboard.connectSSE('your-leaderboard-id', {
  onLeaderboardUpdate: (data) => {
    // Same enhanced format as WebSocket
    console.log('Full leaderboard:', data.leaderboard.entries)
    console.log('What changed:', data.mutations)
    console.log('Triggered by:', data.trigger)
  }
})

// Alternative: WebSocket (only use if you specifically need WebSocket compatibility)
// Note: Currently only receives updates, doesn't send data to server
const ws = leaderboard.connectWebSocket({
  onLeaderboardUpdate: (data) => {
    // New enhanced format with full state and mutations
    console.log('Full leaderboard:', data.leaderboard.entries) // Top 100 entries
    console.log('What changed:', data.mutations) // Array of changes
    console.log('Triggered by:', data.trigger) // What caused the update
  },
  onUserRankUpdate: (data) => {
    console.log('Rank changed:', data)
  }
})
ws.subscribe('your-leaderboard-id')

特征

  • 🚀 简单 API - 几分钟后开始
  • 🌍 全球业绩 - 全世界响应次数 < 100ms
  • 🔄 实时更新 - WebSocket和SSE对领导牌直播的支持
  • 📱 离线支持 - 离线时自动排队 存储. sync
  • 🛡️ 类型安全 - 全部类型脚本支持
  • 🔒 安全 - API 密钥认证,并限制费率
  • 🎮 游戏准备 - 为游戏和竞争性应用程序所建
  • 🏗️ 可靠性 - 自动重试和错误处理

API 参考

构造器

const leaderboard = new GlobalLeaderboards(apiKey, options)

参数:

  • apiKey (字符串,需要) - 您的 API 密钥来自 Global Leaderboards.net
  • options (对象,可选) - 配置选项

选项 :

  • defaultLeaderboardId (字符串) - 用于简化提交()调用的默认领导板
  • baseUrl (字符串) - API 基础 URL( 默认 : https://api.globalleaderboards.net(中文(简体) )
  • wsUrl (字符串) - WebSocket URL(默认: wss://api.globalleaderboards.net(中文(简体) )
  • timeout (数字) - 请求超时 ms( 默认 ): 30000(中文(简体) )
  • autoRetry (boolean) - 启用自动重试( 默认 ): true(中文(简体) )
  • maxRetries (数字) - 最大重试尝试( 默认 ): 3(中文(简体) )

计分方法

提交( 用户ID、 分数、 选项)

将分数提交有验证的导板 .

const result = await leaderboard.submit('user-123', 1500, {
  leaderboardId: 'leaderboard-456',
  userName: 'PlayerOne',
  metadata: {level: 5, character: 'warrior'}
})

// Returns: { operation: 'insert', rank: 42, previous_score?: 1000, improvement?: 500 }

参数:

  • userId (字符串) - 唯一用户标识符
  • score (数量) - 分数值(必须是 QQ 0)
  • options.leaderboardId (字符串) - 目标头板ID
  • options.userName (字符串) - 显示名称(1-50个字符,字母数字+) 发音)
  • options.metadata (对象) - 可选元数据

提交分数( playerId, 分数, 领导板Id?, 选项 ?)

简化分数提交 API.

// Using default leaderboard from config
await leaderboard.submitScore('player-123', 2500)

// Or specify leaderboard
await leaderboard.submitScore('player-123', 2500, 'leaderboard-456')

提交 Bulk( 提交)

以灵活格式提交多个分数。 智能分批按领导板.

const results = await leaderboard.submitBulk([
  // Array format with default leaderboard
  ['user-123', 1000],
  
  // Array format with specific leaderboard
  ['user-456', 2000, 'leaderboard-789'],
  
  // Full object format
  {
    userId: 'user-789',
    score: 3000,
    leaderboardId: 'leaderboard-789',
    userName: 'TopPlayer',
    metadata: { level: 10 }
  }
])

// Returns: { results: [...], summary: { total: 3, successful: 3, failed: 0 } }

参数:

  • submissions - 以上述任何一种形式提交材料的组合:
    • [userId, score] - 使用默认标头板
    • [userId, score, leaderboardId]
    • 有完整选项的对象

领导板方法

获得领导板( 领导板, 选项 )

获取 Pagation 领导板条目 .

const data = await leaderboard.getLeaderboard('leaderboard-456', {
  page: 1,
  limit: 20,
  aroundUser: 'user-123' // Center results around this user
})

// Returns: { data: [...], pagination: {...}, leaderboard: {...} }

选项 :

  • page (数目) - 页号(默认:1)
  • limit (数目) - 每页结果(默认:20,最大:100)
  • aroundUser (字符串) - 中心结果围绕特定用户

获取用户评分( 用户ID, 选项)

为用户获得所有分数 .

const userScores = await leaderboard.getUserScores('user-123', {
  page: 1,
  limit: 50
})

// Returns: { data: [...], pagination: {...}, user: { total_scores: 10, best_rank: 1 } }

卫生和信息方法

卫生()

基本健康检查(不需要认证).

const health = await leaderboard.health()
// Returns: { status: 'healthy', version: '0.1.10', timestamp: '...' }

详细健康( )

附有服务状况的详细健康检查(不需要认证).

const detailed = await leaderboard.healthDetailed()
// Returns: { 
//   status: 'healthy',
//   services: { database: {...}, cache: {...}, storage: {...} },
//   system: { memoryUsage: 128, uptime: 3600, environment: 'production' }
// }

获取 ApiInfo ()

获取API信息和可用的端点(不需要认证).

const info = await leaderboard.getApiInfo()
// Returns API version, endpoints, documentation URL, etc.

服务器事件方法

服务器- Sent Evolution 提供了WebSocket接收的更简单的替代品 实时更新。 SSE是理想的,只要您需要从中获取更新 服务器(单向通信).

连接 SSE( 铅板ID、 处理器、 选项 )

连接到领导板的SSE流进行实时更新.

const connection = leaderboard.connectSSE('leaderboard-456', {
  onConnect: () => {
    console.log('SSE connected')
  },
  onLeaderboardUpdate: (data) => {
    // Enhanced format with full state and mutations (same as WebSocket)
    console.log('Full leaderboard:', data.leaderboard.entries) // Top 100 entries
    console.log('What changed:', data.mutations) // Array of changes
    console.log('Triggered by:', data.trigger) // What caused the update
  },
  onError: (error) => {
    console.error('SSE error:', error)
  },
  onDisconnect: () => {
    console.log('SSE disconnected')
  }
}, {
  userId: 'user-123',              // For personalized updates
  includeMetadata: true,           // Include metadata in updates
  topN: 10                         // Number of top scores in refresh events
})

// Later: close the connection
connection.close()

事件处理器 :

  • onConnect - 已建立连接
  • onDisconnect - 连接已关闭
  • onError - 发生了错误
  • onLeaderboardUpdate - 用增强格式更改了领导板数据(见下文增强信件格式)
  • onHeartbeat - 服务器发出的动态信号(可选)
  • onMessage - 原始信件处理器(可选)

选项 :

  • userId - 个人化等级更新用户ID
  • includeMetadata - 在分数更新中包含元数据( 默认: 真)
  • topN - 刷新事件包含的最高分数( 默认: 10)

断开SSE ()

断开所有SSE连接.

leaderboard.disconnectSSE()

增强 SSE 信件格式

V.5.27中的新内容:SSE和WebSocket现在都使用相同的增强消息格式. 这个 onLeaderboardUpdate 处理器接收 :

{
  leaderboardId: "01K1AKF9NMZFX8FK8XA81QYK2J",
  updateType: "score_update", // or "full_refresh", "bulk_update"
  
  // Complete current state (top 100 entries)
  leaderboard: {
    entries: [
      {
        rank: 1,
        userId: "user123",
        userName: "Alice",
        score: 1000,
        timestamp: "2025-07-29T08:15:37.197Z",
        metadata: { /* custom data */ }
      },
      // ... up to 100 entries
    ],
    totalEntries: 150,
    displayedEntries: 100
  },
  
  // What changed (for animations)
  mutations: [
    {
      type: "new_entry",
      userId: "user456",
      newRank: 3,
      score: 850,
      userName: "Bob"
    },
    {
      type: "rank_change",
      userId: "user789",
      previousRank: 3,
      newRank: 4,
      score: 800
    }
    // ... other mutations
  ],
  
  // What triggered this update
  trigger: {
    type: "score_submission",
    submissions: [
      {
        userId: "user123",
        userName: "Alice",
        score: 1000,
        previousScore: 950,
        timestamp: "2025-07-29T08:15:37.197Z"
      }
    ]
  },
  
  sequence: 42 // For ordering/deduplication
}

网络安全套方法

说明: SSE和WebSocket都收到相同的增强消息格式. SSE被推荐给大多数使用的案例,因为它更简单更方便防火墙.

连接WebSocket( 处理器, 选项 )

通过WebSocket连接到实时更新.

const ws = leaderboard.connectWebSocket({
  onConnect: () => console.log('Connected'),
  onDisconnect: (code, reason) => console.log('Disconnected'),
  onError: (error) => console.error('Error:', error),
  onLeaderboardUpdate: (data) => console.log('Leaderboard update:', data),
  onUserRankUpdate: (data) => console.log('Rank changed:', data),
  onMessage: (message) => console.log('Raw message:', message)
}, {
  leaderboardId: 'leaderboard-456',
  userId: 'user-123',
  maxReconnectAttempts: 5,
  reconnectDelay: 1000
})

处理者 :

  • onConnect - 建立联系时呼叫
  • onDisconnect - 连接关闭时调用
  • onError - 找错人了
  • onLeaderboardUpdate - 当领导板数据改变时调用(见下文增强信件格式)
  • onUserRankUpdate - 当用户的级别改变时调用
  • onMessage - 请求任何 WebSocket 消息
  • onReconnecting - 启动重联尝试时调用(包括尝试号、最大尝试和下一次延迟)

重新连接特征 :

WebSocket客户端包括智能重联:

  • 网络检测 - 离线时自动暂停,在线时恢复
  • 标志性反转 - 延迟与每次尝试的两倍(1,2,4,8...)
  • 抖动 - ±25%随机化可防止雷击群
  • 永久错误处理 - 在认证失败后不会重试
  • 手动控制 - 使用( I) ws.reconnect() 用于自定义重试逻辑
// Example: Handling reconnection events
const ws = leaderboard.connectWebSocket({
  onReconnecting: (attempt, maxAttempts, nextDelay) => {
    console.log(`Reconnecting... Attempt ${attempt}/${maxAttempts}`)
    console.log(`Next attempt in ${nextDelay}ms`)
    // Show reconnection UI to user
  },
  onConnect: () => {
    console.log('Connected!')
    // Hide reconnection UI
  }
})

增强的 WebSocket 信件格式

V.5.27中的新内容编号: onLeaderboardUpdate 处理器现在收到一个增强后的信件格式, 并带有完整的领导板状态和详细的突变 :

{
  leaderboardId: "01K1AKF9NMZFX8FK8XA81QYK2J",
  updateType: "score_update", // or "full_refresh", "bulk_update"
  
  // Complete current state (top 100 entries)
  leaderboard: {
    entries: [
      {
        rank: 1,
        userId: "user123",
        userName: "Alice",
        score: 1000,
        timestamp: "2025-07-29T08:15:37.197Z",
        metadata: { /* custom data */ }
      },
      // ... up to 100 entries
    ],
    totalEntries: 150,
    displayedEntries: 100
  },
  
  // What changed (for animations)
  mutations: [
    {
      type: "new_entry",
      userId: "user456",
      newRank: 3,
      score: 850,
      userName: "Bob"
    },
    {
      type: "rank_change",
      userId: "user789",
      previousRank: 3,
      newRank: 4,
      score: 800
    },
    {
      type: "score_update",
      userId: "user123",
      previousScore: 950,
      newScore: 1000,
      previousRank: 2,
      newRank: 1
    },
    {
      type: "username_change",
      userId: "user111",
      previousUsername: "Player111",
      newUsername: "ProPlayer",
      rank: 5
    },
    {
      type: "removed",
      userId: "user999",
      previousRank: 100,
      score: 100
    }
  ],
  
  // What triggered this update
  trigger: {
    type: "score_submission", // or "bulk_submission", "admin_action", "leaderboard_reset"
    submissions: [
      {
        userId: "user123",
        userName: "Alice",
        score: 1000,
        previousScore: 950,
        timestamp: "2025-07-29T08:15:37.197Z"
      }
    ]
  },
  
  sequence: 42 // For ordering/deduplication
}

突变类型 :

  • new_entry - 用户之前不在领导板上
  • rank_change - 用户的级别改变(但得分没有)
  • score_update - 用户的分数改变(也可能改变等级)
  • username_change - 用户的显示名已更改
  • removed - 用户退出已显示条目

动画使用突变 :

ws.onLeaderboardUpdate = (data) => {
  // Update display with full state
  updateLeaderboard(data.leaderboard.entries)
  
  // Animate changes
  data.mutations.forEach(mutation => {
    switch(mutation.type) {
      case 'new_entry':
        animateNewEntry(mutation.userId, mutation.newRank)
        break
      case 'rank_change':
        animateRankChange(mutation.userId, mutation.previousRank, mutation.newRank)
        break
      case 'score_update':
        animateScoreUpdate(mutation.userId, mutation.previousScore, mutation.newScore)
        break
    }
  })
}

断开WebSocket ()

从 WebSocket 断开连接 .

leaderboard.disconnectWebSocket()

网页实例方法

一旦连接, 在 WebSocket 实例中使用这些方法 :

订阅( 领导板 Id, userId? )

订阅领导板更新 .

ws.subscribe('leaderboard-456', 'user-123')

未订阅( 领导板) (d) 国家

从头板更新取消订阅 .

ws.unsubscribe('leaderboard-456')

断开( )

关闭 WebSocket 连接 .

ws.disconnect()

重新连接( c)

手动触发重接尝试. 用于执行自定义重试逻辑 .

try {
  ws.reconnect()
} catch (error) {
  // Will throw if offline or permanent error occurred
  console.error('Cannot reconnect:', error.message)
}

SSE 对 WebSocket

为您的使用选择正确的实时技术 :

特性证监会网络安全套
通讯单向(服务器-客户端)双向(双向)*
复杂性简单更为复杂
浏览器支持不错不错
自动重接内建手动
防火墙友好对有时被封锁
使用大小写显示更新互动特性*

*注:目前的WebSocket执行只接收数据,不向服务器发送命令.

为什么要推荐SSE:

由于我们的 WebSocket 执行目前只接收更新(没有发送能力),SSE 提供相同的功能有:

  • 更简单的执行
  • 自动重接
  • 更好的防火墙/代理兼容性
  • 资源使用减少
  • 容易调试

当 :

  • 您需要实时领导板更新
  • 你想要最简单的融合
  • 防火墙/代理兼容性很重要
  • 你正在建造一个唯一的显示板

当 :

  • 您特别需要WebSocket来兼容现有的基础设施
  • 您已经在应用程序的其他地方使用 WebSocket
  • 计划未来双向功能(目前没有)

方法

生成Id ()

生成新的 ULID( 通用唯一可排序的 Lexic 标识符) .

const id = leaderboard.generateId()
// Returns: '01ARZ3NDEKTSV4RRFFQ69G5FAV'

离线支持

SDK提供强力下线支持,自动排队并同步提交分数. 当应用程序下线时,分数会自动排队并持续,然后在恢复连接时同步.

如何运作

  1. 自动检测: SDK 使用浏览器 API 监视网络连接
  2. 智能排队: 离线时, submit() 操作立即返回已排队的响应
  3. 持久性存储:队列被保存到chrome.storage.sync(带有本地Storage倒置)
  4. 自动同步: 返回在线时自动排队
  5. 智能击打: 同一主板的多分分数一起分出

基本用途

// Score submission works seamlessly online or offline
const result = await leaderboard.submit('user-123', 1000, {
  leaderboardId: 'game-scores',
  userName: 'Player'
})

// When offline, you'll get a queued response
if (result.queued) {
  console.log(`Score queued with ID: ${result.queueId}`)
  console.log(`Queue position: ${result.queuePosition}`)
}

队列事件监测

// Monitor queue events
leaderboard.on('queue:added', (data) => {
  console.log('Score queued:', data)
})

leaderboard.on('queue:processed', (data) => {
  console.log('Queued score submitted:', data)
})

leaderboard.on('queue:failed', (data) => {
  console.log('Queued score failed:', data)
  // data.permanent indicates if the failure is permanent (won't retry)
})

leaderboard.on('queue:progress', (data) => {
  console.log(`Progress: ${data.processed}/${data.total}`)
})

队列管理

// Check queue status
const status = leaderboard.getQueueStatus()
console.log(`Queue size: ${status.size}`)
console.log(`Processing: ${status.processing}`)
console.log('Queued items:', status.items)

// Manually trigger queue processing
await leaderboard.processQueue()

// Clear the queue (use with caution)
// Note: This requires direct access to offlineQueue
// leaderboard.offlineQueue.clear()

存储细节

下行队列使用混合存储方式:

  1. Chrome 扩展环境: 用途 chrome.storage.sync 用于交叉设备同步
  2. 普通网络环境: 倒计时 localStorage 持久性
  3. 存储密钥: 使用散列孤立的每个 API 密钥(gl_queue_${hash}(中文(简体) )

队列限制和行为

  • 最大队列大小: 1 000件物品
  • 项目 TTL: 24小时(过期物品自动清理)
  • 批量大小: 每批最多100分
  • 重试逻辑: 以增量重试计数重试提交失败
  • 永久失败: 401, 403, 404 个错误标记项目为永久失效

高级示例

// Complete offline-capable game integration
class OfflineCapableGame {
  constructor(apiKey) {
    this.leaderboard = new GlobalLeaderboards(apiKey)
    this.setupQueueMonitoring()
  }

  setupQueueMonitoring() {
    // Show UI indicator when scores are queued
    this.leaderboard.on('queue:added', (data) => {
      this.showNotification('Score saved offline - will sync when online')
    })

    // Update UI when scores are synced
    this.leaderboard.on('queue:processed', (data) => {
      this.showNotification('Offline scores synced!')
    })

    // Handle permanent failures
    this.leaderboard.on('queue:failed', (data) => {
      if (data.permanent) {
        this.showError('Score sync failed permanently')
      }
    })

    // Show sync progress
    this.leaderboard.on('queue:progress', (data) => {
      const percent = (data.processed / data.total) * 100
      this.updateProgressBar(percent)
    })
  }

  async submitScore(score) {
    try {
      const result = await this.leaderboard.submit(
        this.playerId,
        score,
        {
          leaderboardId: this.leaderboardId,
          userName: this.playerName
        }
      )

      if (result.queued) {
        // Score was queued for later
        return { 
          success: true, 
          offline: true, 
          queueId: result.queueId 
        }
      } else {
        // Score was submitted immediately
        return { 
          success: true, 
          offline: false, 
          rank: result.rank 
        }
      }
    } catch (error) {
      return { success: false, error: error.message }
    }
  }
}

重要说明

  • 散装操作:目前,提交批量分数submitBulk()) 离线时不排队,并将丢出错误
  • 队列处理:重新连接时自动发生,不需要人工干预
  • 数据完整性: 分数永远不会丢失 - 要么成功提交,要么保持队列
  • 业绩: 队列操作是同步操作, 不会屏蔽您的应用程序

处理错误

SDK抛出 GlobalLeaderboardsError 对所有 API 错误 :

try {
  await leaderboard.submit('user-123', -100, {
    leaderboardId: 'leaderboard-456'
  })
} catch (error) {
  if (error instanceof GlobalLeaderboardsError) {
    console.error('Error:', error.message)
    console.error('Code:', error.code)
    console.error('Status:', error.statusCode)
    console.error('Details:', error.details)
  }
}

常见错误代码

  • INVALID_SCORE - 分数验证失败
  • INVALID_USERNAME - 用户名验证失败
  • INVALID_USERNAME_LENGTH - 用户名长度验证失败
  • MISSING_LEADERBOARD_ID - 需要头板身份证明
  • TIMEOUT - 请求超时
  • HEALTH_CHECK_FAILED - 健康检查失败
  • WS_NOT_CONNECTED - WebSocket 没有连接
  • WS_MAX_RECONNECT - 实现最大重联尝试

类型脚本支持

SDK是用 TypeScript 编写的, 提供了完整的类型定义 :

import {
  GlobalLeaderboards,
  SubmitScoreResponse,
  LeaderboardEntriesResponse,
  LeaderboardEntry,
  GlobalLeaderboardsError,
  SSEScoreUpdateEvent,
  SSELeaderboardRefreshEvent,
  SSEEventHandlers,
  // New WebSocket types
  LeaderboardUpdateMessage,
  LeaderboardMutation,
  NewEntryMutation,
  RankChangeMutation,
  ScoreUpdateMutation,
  UsernameChangeMutation,
  RemovedMutation,
  UpdateTrigger
} from '@globalleaderboards/sdk'

// All methods are fully typed
const leaderboard = new GlobalLeaderboards('api-key')

const response: SubmitScoreResponse = await leaderboard.submit(
  'user-123',
  1000,
  {
    leaderboardId: 'leaderboard-456',
    userName: 'Player'
  }
)

// TypeScript will provide full IntelliSense for mutations
ws.onLeaderboardUpdate = (data: LeaderboardUpdateMessage['payload']) => {
  data.mutations.forEach((mutation: LeaderboardMutation) => {
    if (mutation.type === 'new_entry') {
      // TypeScript knows this is NewEntryMutation
      console.log(mutation.newRank)
    }
  })
}

实例

反应钩子示例

import {useEffect, useState} from 'react'
import {GlobalLeaderboards} from '@globalleaderboards/sdk'

function useLeaderboard(leaderboardId) {
  const [entries, setEntries] = useState([])
  const [loading, setLoading] = useState(true)

  const leaderboard = new GlobalLeaderboards(process.env.REACT_APP_API_KEY)

  useEffect(() => {
    // Fetch initial data
    leaderboard.getLeaderboard(leaderboardId, {limit: 10})
      .then(data => {
        setEntries(data.data)
        setLoading(false)
      })

    // Connect to real-time updates
    const ws = leaderboard.connectWebSocket({
      onLeaderboardUpdate: (data) => {
        // New format provides full leaderboard state
        setEntries(data.leaderboard.entries)
        
        // Optionally use mutations for animations
        data.mutations.forEach(mutation => {
          if (mutation.type === 'new_entry') {
            // Animate new entry appearing
          } else if (mutation.type === 'rank_change') {
            // Animate rank movement
          }
        })
      }
    })

    ws.subscribe(leaderboardId)

    return () => ws.disconnect()
  }, [leaderboardId])

  return {entries, loading}
}

SSE 实时显示示例

import {GlobalLeaderboards} from '@globalleaderboards/sdk'

function LeaderboardDisplay({leaderboardId}) {
  const [scores, setScores] = useState([])
  const [latestScore, setLatestScore] = useState(null)

  useEffect(() => {
    const leaderboard = new GlobalLeaderboards(process.env.REACT_APP_API_KEY)

    // Connect to SSE for real-time updates
    const connection = leaderboard.connectSSE(leaderboardId, {
      onConnect: () => {
        console.log('Connected to real-time updates')
      },
      onLeaderboardUpdate: (data) => {
        // Update the leaderboard display
        setScores(data.topScores)

        // Show the latest score if available
        if (data.topScores.length > 0) {
          const newestScore = data.topScores[0]
          setLatestScore(newestScore)
        }
      },
      onUserRankUpdate: (data) => {
        // Handle user rank changes if needed
        console.log(`User ${data.userName} rank changed to ${data.newRank}`)
      },
      onError: (error) => {
        console.error('Real-time connection error:', error)
      }
    }, {
      topN: 10  // We're displaying top 10
    })

    // Fetch initial leaderboard
    const fetchLeaderboard = async () => {
      const data = await leaderboard.getLeaderboard(leaderboardId, {limit: 10})
      setScores(data.data)
    }

    fetchLeaderboard()

    // Cleanup on unmount
    return () => connection.close()
  }, [leaderboardId])

  return (
    <div>
      {latestScore && (
        <div className="latest-score">
          New Score: {latestScore.userName} - {latestScore.score}
        </div>
      )}
      <div className="leaderboard">
        {scores.map((entry, index) => (
          <div key={entry.userId}>
            #{entry.rank} {entry.userName} - {entry.score}
          </div>
        ))}
      </div>
    </div>
  )
}

游戏整合示例

class GameLeaderboard {
  constructor(apiKey) {
    this.client = new GlobalLeaderboards(apiKey)
    this.leaderboardId = 'game-highscores'
  }

  async submitGameScore(playerId, playerName, score, level) {
    try {
      const result = await this.client.submit(playerId, score, {
        leaderboardId: this.leaderboardId,
        userName: playerName,
        metadata: {
          level,
          timestamp: Date.now(),
          version: '1.0.0'
        }
      })

      if (result.operation === 'update' && result.improvement > 0) {
        console.log(`New personal best! Improved by ${result.improvement} points`)
      }

      return result
    } catch (error) {
      console.error('Failed to submit score:', error.message)
      throw error
    }
  }

  async getTopPlayers(limit = 10) {
    const data = await this.client.getLeaderboard(this.leaderboardId, {limit})
    return data.data
  }
}

API 利率限制

SDK自动处理速率限制并重试. 现行费率 限制为1,000个请求/分钟.

当速率限制时, SDK 将自动重试, 以指数回放 若为 autoRetry 已启用.

最佳做法

  1. 重用 SDK 实例 - 创建一个实例并重新使用
  2. 处理错误优雅 - 总是把API的电话包起来
  3. 明智地使用元数据 - 存储关卡、字符等特定游戏数据, 包括:.
  4. 验证客户端 - SDK验证分数和用户名 自动
  5. 订阅更新 - 使用WebSocket进行实时领导板
  6. 生成标识 - 使用( I) generateId() 用于一致的ID格式

文档

完备的 API 文档 时间 页面存档备份,存于互联网档案馆. docs.globalleaderboards.net

支助

许可证

麻省理工学院

版本与发布记录

@globalleaderboards/sdk 共发布 16 个版本,首次发布于 2025/07/26;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.5.0latest2025/08/011.3 年前
0.4.102025/07/301.3 年前
0.4.92025/07/291.3 年前
0.4.82025/07/291.3 年前
0.4.72025/07/291.3 年前
0.4.62025/07/291.3 年前

关于 @globalleaderboards/sdk 的常见问题

@globalleaderboards/sdk 是什么?

GlobalLeaderboards.net的官方SDK - 在任何应用程序中加入竞争性领导牌

如何安装 @globalleaderboards/sdk?

在项目目录运行 npm install @globalleaderboards/sdk,或使用 pnpm add / yarn add / bun add。

@globalleaderboards/sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@globalleaderboards/sdk 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@globalleaderboards/sdk 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=16.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@globalleaderboards/sdk 可以商用吗?

@globalleaderboards/sdk 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@globalleaderboards/sdk 的下载量有多少?

根据 npm 官方下载统计,@globalleaderboards/sdk 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,985 次,日均约 133 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@globalleaderboards/sdk 还在维护吗?

最新版本 0.5.0 发布于 2025/08/01(1.3 年前);至今共发布 16 个版本,其中过去 12 个月发布了 0 个;首次发布于 2025/07/26。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。