Skip to main content

​
Overview

The Analytics API provides powerful insights into your community’s engagement, helping you measure success, identify trends, and optimize your gamification strategies. Access real-time and historical data across all aspects of your platform.

​
Base URL

https://{subdomain}.nudj.cx/api/v2/analytics
Replace {subdomain} with your organization’s subdomain (e.g., acme-corp.nudj.cx).

​
Authentication

x-api-token: YOUR_ANALYTICS_TOKEN
Analytics tokens require read-only analytics scope. Data is automatically filtered to your organization based on the subdomain + token binding. See the Authentication guide for setup instructions.

​
Available Analytics

User Analytics

Track user engagement, activity patterns, and progression metrics

Community Insights

Monitor overall community health, growth, and activity trends

Challenge Performance

Analyze challenge completion rates, participation, and user journeys

Achievement Tracking

Measure achievement unlock rates and milestone progression

Rewards Analytics

Track reward distributions, redemptions, and inventory management

​
Key Metrics Available

​
Engagement Metrics

  • Daily/weekly/monthly active users
  • Session duration and frequency
  • Feature adoption rates
  • User retention cohorts

​
Gamification Performance

  • Points and XP distribution
  • Challenge completion funnels
  • Achievement unlock patterns
  • Leaderboard dynamics

​
Rewards & Incentives

  • Reward redemption rates
  • Inventory turnover
  • Distribution efficiency
  • User satisfaction scores

​
Community Health

  • Content creation volume
  • Social interaction rates
  • Community growth velocity
  • User lifecycle stages

​
Quick Start

import { createAnalyticsClient } from '@nudj-digital/api/analytics';

const analytics = createAnalyticsClient({
  baseUrl: 'https://acme-corp.nudj.cx/api/v2/analytics',
  headers: {
    'x-api-token': process.env.NUDJ_ANALYTICS_TOKEN
  }
});

// Get community overview
const stats = await analytics.community.statsOverview();

// Get user metrics with pagination
const users = await analytics.users.overview({
  params: { limit: 100, skip: 0 }
});

​
Common Use Cases

Combine community overview, user metrics, and rewards analytics to create comprehensive executive dashboards showing ROI and engagement trends.
Use user analytics endpoints to segment users by activity level, achievement progress, and reward redemption patterns for targeted campaigns.
Analyze challenge funnel metrics to identify drop-off points and optimize difficulty curves for better completion rates.
Track reward redemption velocity and forecast inventory needs using rewards analytics endpoints.
Generate automated weekly/monthly reports showing user activity, content creation, and community growth metrics.

​
Response Format

All Analytics API responses follow a consistent structure: 
{
  "data": {
    // Metric-specific data
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "cached": false,
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-15T23:59:59Z"
    }
  },
  "pagination": {
    "limit": 100,
    "skip": 0,
    "total": 2500,
    "hasMore": true
  }
}

​
Best Practices

  • Use pagination for large datasets
  • Cache responses client-side for dashboard displays
  • Batch requests when fetching multiple metrics
  • Handle rate limits gracefully with exponential backoff

​
Privacy & Compliance

The Analytics API provides operational data necessary for rewards management and user engagement tracking. Access to user data is controlled through role-based permissions and audit logging.

​
Data Access Levels

​
Analytics API (This API)

  • Operational data: Includes user identifiers, emails, and activity data necessary for:
    • Reward distribution and redemption tracking
    • Winner selection and giveaway management
    • User engagement monitoring and support
    • Fraud detection and prevention
  • Access control: Requires admin-level API tokens with analytics scope
  • Audit trail: All data access is logged for compliance

​
Public/Integration APIs

  • Anonymized data: No PII exposed to end users
  • User-specific data: Only accessible via authenticated user sessions
  • Aggregated metrics: Statistics presented without individual identification

​
Compliance Framework

Access to user data through the Analytics API is justified under legitimate business interests for platform administration and service delivery.
  • Contract fulfillment: Required for reward delivery and service provision
  • Legitimate interests: Platform administration, fraud prevention, and user support
  • Consent: Users agree to data processing via Terms of Service
  • Legal obligations: Tax reporting for high-value rewards, anti-money laundering

​
Security Controls

  • Role-based access: Only authorized administrators can access PII
  • API token scoping: Tokens limited to specific operations and data sets
  • Encryption: Data encrypted in transit (TLS 1.3) and at rest (AES-256)
  • Access logging: Comprehensive audit trail of all data access
  • Data minimization: Only necessary fields exposed for each use case

​
Compliance Features

  • GDPR compliance:
    • Data portability exports available
    • Right to erasure supported via Admin API
    • Privacy-by-design architecture
  • Geographic controls: Data residency options for EU/US/APAC
  • SOC 2 Type II: Annual audits for security controls
  • ISO 27001: Information security management certification

​
Best Practices for PII Handling

  • Access Control
  • Data Handling
  • Compliance Monitoring
  • Implement principle of least privilege
  • Rotate API tokens regularly (90 days recommended)
  • Use separate tokens for different environments
  • Enable IP allowlisting for production access
  • Require MFA for admin accounts that generate tokens

​
Reward-Specific Compliance

For reward distribution and redemption:
  • Tax reporting: Requirements vary by jurisdiction and prize value
  • Audit trails: Complete history of reward allocations and redemptions
  • Fraud prevention: Pattern detection and manual review capabilities

​
Need Help?

API Reference

Explore all available endpoints

Support

Contact our support team
⌘I