Overview
Simple example showing how to integrate ZKScore SDK into a basic web application.Setup
Installation
Copy
npm install @zkscore/sdk
Basic Configuration
Copy
import { ZKScoreClient } from '@zkscore/sdk';
const client = new ZKScoreClient({
apiKey: process.env.ZKSCORE_API_KEY,
environment: 'mainnet'
});
Basic Usage
Get User Score
Copy
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
Copy
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
Copy
<!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
Copy
// 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
Copy
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
- Error Handling: Always handle errors gracefully
- Loading States: Show loading indicators during API calls
- Caching: Cache frequently accessed data
- Rate Limiting: Implement proper rate limiting
- User Feedback: Provide clear feedback to users