Skip to main content

Overview

Simple example showing how to integrate ZKScore SDK into a basic web application.

Setup

Installation

npm install @zkscore/sdk

Basic Configuration

import { ZKScoreClient } from '@zkscore/sdk';

const client = new ZKScoreClient({
  apiKey: process.env.ZKSCORE_API_KEY,
  environment: 'mainnet'
});

Basic Usage

Get User Score

async function displayUserScore(userAddress) {
  try {
    const score = await client.getScore(userAddress);
    console.log(`User score: ${score.total}`);
    
    const breakdown = await client.getScoreBreakdown(userAddress);
    console.log('Score breakdown:', breakdown);
  } catch (error) {
    console.error('Error getting score:', error);
  }
}

Get User Identity

async function displayUserIdentity(userAddress) {
  try {
    const identity = await client.getIdentity(userAddress);
    
    if (identity) {
      console.log(`ZKS ID: ${identity.zksId}`);
      console.log(`Display Name: ${identity.displayName}`);
      console.log(`Avatar: ${identity.avatarUrl}`);
    } else {
      console.log('No identity found');
    }
  } catch (error) {
    console.error('Error getting identity:', error);
  }
}

Complete Example

HTML Structure

<!DOCTYPE html>
<html>
<head>
    <title>ZKScore Integration</title>
</head>
<body>
    <div id="app">
        <h1>ZKScore Dashboard</h1>
        <div id="user-info"></div>
        <div id="score-info"></div>
        <div id="achievements"></div>
    </div>
    <script src="app.js"></script>
</body>
</html>

JavaScript Implementation

// app.js
import { ZKScoreClient } from '@zkscore/sdk';

const client = new ZKScoreClient({
  apiKey: 'your_api_key_here',
  environment: 'mainnet'
});

class ZKScoreApp {
  constructor() {
    this.userAddress = null;
    this.init();
  }
  
  async init() {
    // Get user address from wallet connection
    this.userAddress = await this.getUserAddress();
    
    if (this.userAddress) {
      await this.loadUserData();
    }
  }
  
  async getUserAddress() {
    // This would typically come from wallet connection
    // For demo purposes, using a placeholder
    return '0x1234567890123456789012345678901234567890';
  }
  
  async loadUserData() {
    try {
      // Load identity
      await this.loadIdentity();
      
      // Load score
      await this.loadScore();
      
      // Load achievements
      await this.loadAchievements();
    } catch (error) {
      console.error('Error loading user data:', error);
    }
  }
  
  async loadIdentity() {
    const identity = await client.getIdentity(this.userAddress);
    const identityDiv = document.getElementById('user-info');
    
    if (identity) {
      identityDiv.innerHTML = `
        <h2>Identity</h2>
        <p><strong>ZKS ID:</strong> ${identity.zksId}</p>
        <p><strong>Display Name:</strong> ${identity.displayName}</p>
        <p><strong>Status:</strong> ${identity.isActivated ? 'Activated' : 'Not Activated'}</p>
      `;
    } else {
      identityDiv.innerHTML = '<p>No identity found</p>';
    }
  }
  
  async loadScore() {
    const score = await client.getScore(this.userAddress);
    const breakdown = await client.getScoreBreakdown(this.userAddress);
    const scoreDiv = document.getElementById('score-info');
    
    scoreDiv.innerHTML = `
      <h2>ZKScore</h2>
      <p><strong>Total Score:</strong> ${score.total}</p>
      <h3>Breakdown:</h3>
      <ul>
        <li>DeFi: ${breakdown.defi}</li>
        <li>NFT: ${breakdown.nft}</li>
        <li>Social: ${breakdown.social}</li>
        <li>Trading: ${breakdown.trading}</li>
        <li>Governance: ${breakdown.governance}</li>
        <li>Gaming: ${breakdown.gaming}</li>
        <li>Identity: ${breakdown.identity}</li>
        <li>Trust: ${breakdown.trust}</li>
      </ul>
    `;
  }
  
  async loadAchievements() {
    const achievements = await client.getAchievements(this.userAddress);
    const achievementsDiv = document.getElementById('achievements');
    
    if (achievements.length > 0) {
      achievementsDiv.innerHTML = `
        <h2>Achievements</h2>
        <div class="achievement-list">
          ${achievements.map(achievement => `
            <div class="achievement">
              <h3>${achievement.name}</h3>
              <p>${achievement.description}</p>
              <p><strong>Category:</strong> ${achievement.category}</p>
              <p><strong>Rarity:</strong> ${achievement.rarity}</p>
              <p><strong>Points:</strong> ${achievement.points}</p>
            </div>
          `).join('')}
        </div>
      `;
    } else {
      achievementsDiv.innerHTML = '<p>No achievements yet</p>';
    }
  }
}

// Initialize app
new ZKScoreApp();

Error Handling

Comprehensive Error Handling

class ZKScoreError extends Error {
  constructor(message, code, details) {
    super(message);
    this.name = 'ZKScoreError';
    this.code = code;
    this.details = details;
  }
}

async function safeApiCall(apiCall, ...args) {
  try {
    const result = await apiCall(...args);
    return { success: true, data: result };
  } catch (error) {
    let errorMessage = 'Unknown error';
    let errorCode = 'UNKNOWN_ERROR';
    
    if (error.message.includes('Identity not found')) {
      errorMessage = 'User has no identity';
      errorCode = 'NO_IDENTITY';
    } else if (error.message.includes('Score not found')) {
      errorMessage = 'User has no score';
      errorCode = 'NO_SCORE';
    } else if (error.message.includes('Rate limit exceeded')) {
      errorMessage = 'Rate limit exceeded. Please try again later.';
      errorCode = 'RATE_LIMIT';
    }
    
    return { 
      success: false, 
      error: new ZKScoreError(errorMessage, errorCode, error) 
    };
  }
}

// Usage
const { success, data, error } = await safeApiCall(client.getScore, userAddress);
if (success) {
  console.log('Score:', data);
} else {
  console.error('Error:', error.message);
}

Best Practices

  1. Error Handling: Always handle errors gracefully
  2. Loading States: Show loading indicators during API calls
  3. Caching: Cache frequently accessed data
  4. Rate Limiting: Implement proper rate limiting
  5. User Feedback: Provide clear feedback to users