> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics API Overview

> Real-time analytics and reporting for community engagement, gamification metrics, and user behavior insights

## 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
```

> [!NOTE]
>
> Replace `{subdomain}` with your organization's subdomain (e.g., `acme-corp.nudj.cx`).

## Authentication

```bash theme={null}
x-api-token: YOUR_ANALYTICS_TOKEN
```

> [!NOTE]
>
> Analytics tokens require read-only `analytics` scope. Data is automatically filtered to your organization based on the subdomain + token binding. See the [Authentication guide](https://docs.nudj.cx/api-reference/authentication.md) for setup instructions.

## Available Analytics

> **[User Analytics](https://docs.nudj.cx/api-reference/analytics/get-users-overview.md)**
>
> Track user engagement, activity patterns, and progression metrics

> **[Community Insights](https://docs.nudj.cx/api-reference/analytics/get-community-stats-overview.md)**
>
> Monitor overall community health, growth, and activity trends

> **[Challenge Performance](https://docs.nudj.cx/api-reference/analytics/get-challenges-stats-overview.md)**
>
> Analyze challenge completion rates, participation, and user journeys

> **[Achievement Tracking](https://docs.nudj.cx/api-reference/analytics/get-achievements-stats-overview.md)**
>
> Measure achievement unlock rates and milestone progression

> **[Rewards Analytics](https://docs.nudj.cx/api-reference/analytics/get-rewards-stats-assets-overview.md)**
>
> 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

```typescript TypeScript theme={null}
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 }
});
```

```javascript JavaScript theme={null}
const response = await fetch('https://acme-corp.nudj.cx/api/v2/analytics/community/stats/overview', {
  headers: {
    'x-api-token': 'YOUR_ANALYTICS_TOKEN'
  }
});

const stats = await response.json();
```

```python Python theme={null}
import requests

response = requests.get(
    'https://acme-corp.nudj.cx/api/v2/analytics/community/stats/overview',
    headers={'x-api-token': 'YOUR_ANALYTICS_TOKEN'}
)

stats = response.json()
```

```bash cURL theme={null}
curl -X GET https://acme-corp.nudj.cx/api/v2/analytics/community/stats/overview \
  -H "x-api-token: YOUR_ANALYTICS_TOKEN"
```

## Common Use Cases

> **Building Executive Dashboards**
>
> Combine community overview, user metrics, and rewards analytics to create comprehensive executive dashboards showing ROI and engagement trends.

> **User Segmentation Analysis**
>
> Use user analytics endpoints to segment users by activity level, achievement progress, and reward redemption patterns for targeted campaigns.

> **Challenge Optimization**
>
> Analyze challenge funnel metrics to identify drop-off points and optimize difficulty curves for better completion rates.

> **Reward Inventory Management**
>
> Track reward redemption velocity and forecast inventory needs using rewards analytics endpoints.

> **Engagement Reporting**
>
> Generate automated weekly/monthly reports showing user activity, content creation, and community growth metrics.

## Response Format

All Analytics API responses follow a consistent structure:

```json theme={null}
{
  "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

> [!WARNING]
>
> 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

> [!NOTE]
>
> Access to user data through the Analytics API is justified under legitimate business interests for platform administration and service delivery.

#### Legal Basis for PII Processing

* **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**

* 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

**Data Handling**

* Never log or cache PII in client applications
* Use secure storage for any local data processing
* Implement data masking in non-production environments
* Regularly review and purge unnecessary data
* Encrypt any exports or reports containing PII

**Compliance Monitoring**

* Regular access reviews (quarterly)
* Monitor unusual data access patterns
* Document legitimate business purposes
* Maintain data processing records
* Conduct privacy impact assessments

## 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](https://docs.nudj.cx/api-reference/analytics/get-users-overview.md)**
>
> Explore all available endpoints

> **[Support](https://support.nudj.cx)**
>
> Contact our support team


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.