Skip to content
Last updated

PERS SDK - v2.3.26 / Exports / AnalyticsManager

Class: AnalyticsManager

Analytics Manager - Clean, high-level interface for analytics operations

Provides comprehensive analytics and business intelligence capabilities for the loyalty ecosystem including transaction analysis, user behavior tracking, campaign performance metrics, and business insights. Enables data-driven decision making with real-time and historical analytics across all system domains.

Example

// Get transaction analytics for the last 30 days
const analytics = await sdk.analytics.getTransactionAnalytics({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  groupBy: 'day',
  metrics: ['volume', 'count', 'averageValue']
});

console.log('Transaction Trends:');
console.log(`Total Volume: $${analytics.totalVolume}`);
console.log(`Total Transactions: ${analytics.totalCount}`);
console.log(`Average Transaction: $${analytics.averageValue}`);

Example

// Analyze performance by business partner
const businessAnalytics = await sdk.analytics.getTransactionAnalytics({
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  groupBy: 'business',
  includeDetails: true
});

console.log('Top Performing Partners:');
businessAnalytics.businessBreakdown?.forEach((business, index) => {
  console.log(`${index + 1}. ${business.name}`);
  console.log(`   Volume: $${business.volume}`);
  console.log(`   Transactions: ${business.count}`);
});

Example

// Get comprehensive analytics dashboard data
const analyticsService = sdk.analytics.getAnalyticsService();

// Get multiple analytics in parallel
const [userMetrics, campaignMetrics, tokenMetrics] = await Promise.all([
  analyticsService.getUserEngagementMetrics(),
  analyticsService.getCampaignPerformance(),
  analyticsService.getTokenDistributionAnalytics()
]);

Table of contents

Constructors

Methods

Constructors

constructor

• new AnalyticsManager(apiClient): AnalyticsManager

Parameters

NameType
apiClientPersApiClient

Returns

AnalyticsManager

Defined in

managers/analytics-manager.ts:75

Methods

getTransactionAnalytics

▸ getTransactionAnalytics(request): Promise<TransactionAnalyticsResponseDTO>

Get transaction analytics

Retrieves comprehensive transaction analytics with flexible filtering, grouping, and metric selection. Provides insights into transaction volumes, trends, business performance, and user behavior patterns across the loyalty ecosystem.

Parameters

NameTypeDescription
requestTransactionAnalyticsRequestDTOAnalytics request parameters including date range, filters, and metrics

Returns

Promise<TransactionAnalyticsResponseDTO>

Promise resolving to transaction analytics data with metrics and breakdowns

Throws

When analytics data is unavailable or parameters are invalid

Example

try {
  const analytics = await sdk.analytics.getTransactionAnalytics({
    startDate: '2024-01-01T00:00:00Z',
    endDate: '2024-01-31T23:59:59Z',
    groupBy: 'day',
    metrics: ['volume', 'count', 'averageValue', 'tokens'],
    includeComparisons: true  // Compare with previous period
  });
  
  console.log('Transaction Analytics Summary:');
  console.log(`Total Volume: $${analytics.totalVolume.toLocaleString()}`);
  console.log(`Total Transactions: ${analytics.totalCount.toLocaleString()}`);
  console.log(`Average Transaction: $${analytics.averageValue.toFixed(2)}`);
  console.log(`Tokens Distributed: ${analytics.totalTokens.toLocaleString()}`);
  
  if (analytics.periodComparison) {
    const volumeChange = analytics.periodComparison.volumeChangePercent;
    const countChange = analytics.periodComparison.countChangePercent;
    
    console.log('\nPeriod-over-Period Changes:');
    console.log(`Volume: ${volumeChange > 0 ? '+' : ''}${volumeChange}%`);
    console.log(`Count: ${countChange > 0 ? '+' : ''}${countChange}%`);
  }
  
  // Display daily trend data
  if (analytics.dailyBreakdown) {
    console.log('\nDaily Trends:');
    analytics.dailyBreakdown.forEach(day => {
      console.log(`${day.date}: $${day.volume} (${day.count} transactions)`);
    });
  }
  
} catch (error) {
  console.log('Analytics retrieval failed:', error.message);
}

Example

// Analyze transaction performance by business partner
const businessAnalytics = await sdk.analytics.getTransactionAnalytics({
  startDate: '2024-01-01',
  endDate: '2024-03-31',
  groupBy: 'business',
  metrics: ['volume', 'count', 'averageValue', 'customerCount'],
  includeDetails: true,
  minimumTransactionCount: 10  // Only include businesses with 10+ transactions
});

console.log('Business Partner Performance:');

if (businessAnalytics.businessBreakdown) {
  // Sort by volume descending
  const sortedBusinesses = businessAnalytics.businessBreakdown
    .sort((a, b) => b.volume - a.volume);
  
  console.log('\nTop 10 Partners by Volume:');
  sortedBusinesses.slice(0, 10).forEach((business, index) => {
    console.log(`\n${index + 1}. ${business.name}`);
    console.log(`   Volume: $${business.volume.toLocaleString()}`);
    console.log(`   Transactions: ${business.count}`);
    console.log(`   Avg Transaction: $${business.averageValue.toFixed(2)}`);
    console.log(`   Unique Customers: ${business.customerCount}`);
    console.log(`   Customer LTV: $${(business.volume / business.customerCount).toFixed(2)}`);
  });
  
  // Identify growth opportunities
  const lowVolumeHighFrequency = sortedBusinesses.filter(b => 
    b.count > 50 && b.averageValue < 25
  );
  
  if (lowVolumeHighFrequency.length > 0) {
    console.log('\nGrowth Opportunities (High Frequency, Low Value):');
    lowVolumeHighFrequency.forEach(business => {
      console.log(`${business.name}: ${business.count} transactions, $${business.averageValue} avg`);
    });
  }
}

Example

// Analyze seasonal patterns and trends
const seasonalAnalytics = await sdk.analytics.getTransactionAnalytics({
  startDate: '2023-01-01',
  endDate: '2024-12-31',
  groupBy: 'month',
  metrics: ['volume', 'count'],
  includeSeasonalAnalysis: true,
  includeTrendLine: true
});

console.log('Seasonal Analysis:');

if (seasonalAnalytics.monthlyBreakdown) {
  const monthlyData = seasonalAnalytics.monthlyBreakdown;
  
  // Find peak months
  const peakVolumeMonth = monthlyData.reduce((max, current) => 
    current.volume > max.volume ? current : max
  );
  
  const peakCountMonth = monthlyData.reduce((max, current) => 
    current.count > max.count ? current : max
  );
  
  console.log(`Peak Volume Month: ${peakVolumeMonth.month} ($${peakVolumeMonth.volume})`);
  console.log(`Peak Transaction Month: ${peakCountMonth.month} (${peakCountMonth.count})`);
  
  // Calculate quarterly performance
  const quarters = {
    Q1: monthlyData.slice(0, 3).reduce((sum, m) => sum + m.volume, 0),
    Q2: monthlyData.slice(3, 6).reduce((sum, m) => sum + m.volume, 0),
    Q3: monthlyData.slice(6, 9).reduce((sum, m) => sum + m.volume, 0),
    Q4: monthlyData.slice(9, 12).reduce((sum, m) => sum + m.volume, 0)
  };
  
  console.log('\nQuarterly Performance:');
  Object.entries(quarters).forEach(([quarter, volume]) => {
    console.log(`${quarter}: $${volume.toLocaleString()}`);
  });
}

if (seasonalAnalytics.trendAnalysis) {
  console.log('\nTrend Analysis:');
  console.log(`Growth Rate: ${seasonalAnalytics.trendAnalysis.growthRate}%/month`);
  console.log(`Trend Direction: ${seasonalAnalytics.trendAnalysis.direction}`);
  console.log(`Seasonality Score: ${seasonalAnalytics.trendAnalysis.seasonalityScore}`);
}

Example

// Get real-time metrics for dashboard display
const realTimeMetrics = await sdk.analytics.getTransactionAnalytics({
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(), // Last 24 hours
  endDate: new Date().toISOString(),
  groupBy: 'hour',
  metrics: ['volume', 'count', 'tokens'],
  includeRealTimeMetrics: true
});

console.log('⚡ Real-time Metrics (Last 24 Hours):');
console.log(`Current Volume: $${realTimeMetrics.totalVolume}`);
console.log(`Active Users: ${realTimeMetrics.activeUserCount}`);
console.log(`Transactions/Hour: ${realTimeMetrics.transactionsPerHour}`);

if (realTimeMetrics.hourlyBreakdown) {
  // Show last 6 hours
  const lastSixHours = realTimeMetrics.hourlyBreakdown.slice(-6);
  console.log('\n� Last 6 Hours:');
  lastSixHours.forEach(hour => {
    console.log(`${hour.hour}:00 - $${hour.volume} (${hour.count} txns)`);
  });
}

// Update dashboard in real-time
const updateDashboard = () => {
  document.getElementById('totalVolume').textContent = `$${realTimeMetrics.totalVolume}`;
  document.getElementById('transactionCount').textContent = realTimeMetrics.totalCount;
  document.getElementById('activeUsers').textContent = realTimeMetrics.activeUserCount;
};

updateDashboard();

Defined in

managers/analytics-manager.ts:260


getCampaignClaimAnalytics

▸ getCampaignClaimAnalytics(request): Promise<CampaignClaimAnalyticsResponseDTO>

Get campaign claim analytics with aggregation

Retrieves aggregated analytics for campaign claims with flexible grouping, filtering, and metric selection. Provides insights into campaign performance, claim patterns, and user engagement across the loyalty ecosystem.

Parameters

NameTypeDescription
requestCampaignClaimAnalyticsRequestDTOAnalytics request with filters, groupBy, and metrics

Returns

Promise<CampaignClaimAnalyticsResponseDTO>

Promise resolving to campaign claim analytics data

Example

const analytics = await sdk.analytics.getCampaignClaimAnalytics({
  filters: { status: 'COMPLETED' },
  groupBy: ['campaignId'],
  metrics: ['count'],
  sortBy: 'count',
  sortOrder: 'DESC',
  limit: 10
});

console.log('Top campaigns:', analytics.results);

Defined in

managers/analytics-manager.ts:288


getRedemptionRedeemAnalytics

▸ getRedemptionRedeemAnalytics(request): Promise<RedemptionRedeemAnalyticsResponseDTO>

Get redemption redeem analytics with aggregation

Retrieves aggregated redemption redeem data with flexible grouping and metrics. Perfect for charts, dashboards, and redeem pattern analysis across redemptions, businesses, and time periods.

Parameters

NameTypeDescription
requestRedemptionRedeemAnalyticsRequestDTOAnalytics request with filters, groupBy, and metrics

Returns

Promise<RedemptionRedeemAnalyticsResponseDTO>

Promise resolving to redemption redeem analytics data

Example

const analytics = await sdk.analytics.getRedemptionRedeemAnalytics({
  groupBy: ['redemptionId'],
  metrics: ['count'],
  sortBy: 'count',
  sortOrder: 'DESC',
  limit: 10
});

console.log('Top redemptions by redeems:', analytics.results);

Example

const analytics = await sdk.analytics.getRedemptionRedeemAnalytics({
  groupBy: ['month', 'status'],
  metrics: ['count'],
  sortBy: 'month',
  sortOrder: 'DESC',
  startDate: new Date('2026-01-01'),
  endDate: new Date('2026-12-31')
});

Example

const analytics = await sdk.analytics.getRedemptionRedeemAnalytics({
  filters: { status: 'COMPLETED' },
  groupBy: ['businessId'],
  metrics: ['count'],
  sortBy: 'count',
  sortOrder: 'DESC'
});

Defined in

managers/analytics-manager.ts:338


getUserAnalytics

▸ getUserAnalytics(request?): Promise<UserAnalyticsResponseDTO>

Get user analytics with engagement metrics

Retrieves aggregated user statistics including engagement rate, active users, transaction metrics, and per-active-user averages. Provides comprehensive insights into user behavior, engagement patterns, and platform adoption metrics.

NEW: Added per-active-user metrics (averageTransactionsPerActiveUser, etc.) which show concentrated engagement among active users - more useful than diluted all-user averages.

Request structure matches TransactionAnalytics and CampaignClaimAnalytics:

  • Use filters object for business-specific scoping
  • startDate/endDate at root level for date range filtering

Parameters

NameTypeDescription
requestUserAnalyticsRequestDTOAnalytics request with optional filters and date range

Returns

Promise<UserAnalyticsResponseDTO>

Promise resolving to user analytics data with per-user and per-active-user metrics

Example

const analytics = await sdk.analytics.getUserAnalytics({});
console.log(`Total users: ${analytics.totalUsers}`);
console.log(`Active users: ${analytics.activeUsers} (${analytics.engagementRate.toFixed(1)}%)`);

// Per-user averages (includes inactive users - lower numbers)
console.log(`\\nPer-User Averages (all users):`);
console.log(`  Transactions: ${analytics.averageTransactionsPerUser.toFixed(2)}`);
console.log(`  Claims: ${analytics.averageClaimsPerUser.toFixed(2)}`);
console.log(`  Redemptions: ${analytics.averageRedemptionsPerUser.toFixed(2)}`);

// Per-active-user averages (only engaged users - higher, more meaningful numbers)
console.log(`\\nPer-Active-User Averages (engaged users only):`);
console.log(`  Transactions: ${analytics.averageTransactionsPerActiveUser.toFixed(2)}`);
console.log(`  Claims: ${analytics.averageClaimsPerActiveUser.toFixed(2)}`);
console.log(`  Redemptions: ${analytics.averageRedemptionsPerActiveUser.toFixed(2)}`);

Example

const analytics = await sdk.analytics.getUserAnalytics({
  startDate: new Date('2026-02-01'),
  endDate: new Date('2026-02-28')
});

console.log('February 2026 User Metrics:');
console.log(`Total users: ${analytics.totalUsers}`);
console.log(`Active users: ${analytics.activeUsers}`);
console.log(`New users: ${analytics.newUsers}`);
console.log(`Engagement rate: ${analytics.engagementRate.toFixed(2)}%`);
console.log(`Total transaction volume: $${analytics.totalTransactionVolume.toLocaleString()}`);
console.log(`Avg transaction amount: $${analytics.averageTransactionAmount.toFixed(2)}`);
console.log(`\\nFilters applied: ${analytics.metadata.dateRange?.startDate} to ${analytics.metadata.dateRange?.endDate}`);

Example

const analytics = await sdk.analytics.getUserAnalytics({
  filters: { businessId: 'business-123' },
  startDate: new Date('2026-01-01'),
  endDate: new Date('2026-12-31')
});

console.log(`Business customer metrics for 2026:`);
console.log(`Active customers: ${analytics.activeUsers} / ${analytics.totalUsers}`);
console.log(`Customer engagement: ${analytics.engagementRate.toFixed(1)}%`);
console.log(`Avg spend per customer: $${analytics.averageTransactionAmount.toFixed(2)}`);
console.log(`Avg spend per active customer: $${(analytics.totalTransactionVolume / analytics.activeUsers).toFixed(2)}`);
console.log(`Avg claims per active customer: ${analytics.averageClaimsPerActiveUser.toFixed(2)}`);

Defined in

managers/analytics-manager.ts:411


getUserRanking

▸ getUserRanking(request?): Promise<UserRankingAnalyticsResponseDTO>

Get user transaction ranking with enriched user data

Retrieves ranked list of users with full user details (email, externalUserId) and transaction metrics. Data enrichment happens via efficient SQL JOINs + UNION (handles legacy transactions). Ideal for leaderboards, engagement analysis, and identifying power users for targeted campaigns.

Use Cases:

  • Admin leaderboards showing top users by activity
  • User engagement analysis with full user context
  • Identifying power users for campaigns
  • Customer segmentation by transaction behavior

Parameters

NameTypeDescription
requestUserRankingAnalyticsRequestDTORanking request with filters, sorting, and limit

Returns

Promise<UserRankingAnalyticsResponseDTO>

Promise resolving to ranked user list with transaction metrics

Example

const ranking = await sdk.analytics.getUserRanking({
  sortBy: 'totalTransactions',
  sortOrder: 'DESC',
  limit: 50
});

console.log(`Top ${ranking.totalUsers} users:`);
ranking.results.forEach((user, index) => {
  console.log(`#${index + 1}: ${user.email || user.externalUserId}`);
  console.log(`  Transactions: ${user.totalTransactions}`);
  console.log(`  Token spent: ${user.tokenSpent}`);
});

Example

const ranking = await sdk.analytics.getUserRanking({
  filters: { tokenType: 'STAMP' },
  sortBy: 'tokenSpent',
  sortOrder: 'DESC',
  limit: 20
});

console.log('Top 20 STAMP spenders:');
ranking.results.forEach((user, index) => {
  const identifier = user.email || user.externalUserId || user.userId;
  console.log(`${index + 1}. ${identifier} - ${user.tokenSpent} STAMP`);
});

Defined in

managers/analytics-manager.ts:464


getBusinessRanking

▸ getBusinessRanking(request?): Promise<BusinessRankingAnalyticsResponseDTO>

Get business transaction ranking with enriched business data

Returns ranked list of businesses with full business details and transaction metrics.

Parameters

NameTypeDescription
requestBusinessRankingAnalyticsRequestDTORanking request with filters, sorting, and limit

Returns

Promise<BusinessRankingAnalyticsResponseDTO>

Promise resolving to ranked business list

Defined in

managers/analytics-manager.ts:476


getRetentionAnalytics

▸ getRetentionAnalytics(request?): Promise<RetentionAnalyticsResponseDTO>

Get monthly user retention analytics

Returns monthly retention data with user metrics and retention rates.

Parameters

NameTypeDescription
requestRetentionAnalyticsRequestDTORetention request with monthsBack and filters

Returns

Promise<RetentionAnalyticsResponseDTO>

Promise resolving to monthly retention data

Defined in

managers/analytics-manager.ts:488


getTagAnalytics

▸ getTagAnalytics(request?): Promise<TagAnalyticsResponseDTO>

Get tag usage analytics across entities

Aggregates tag usage across all taggable entities (campaigns, redemptions, businesses, token metadata, user status types). Perfect for:

  • Tag autocomplete/suggestions
  • Tag management dashboards
  • Usage analytics

Parameters

NameTypeDescription
requestTagAnalyticsRequestDTOOptional filters for entity types

Returns

Promise<TagAnalyticsResponseDTO>

Promise resolving to aggregated tag usage data

Example

const allTags = await sdk.analytics.getTagAnalytics();
const suggestions = allTags.tags.map(t => t.tag);

Example

import { TaggableEntityType } from '@explorins/pers-sdk';

const campaignTags = await sdk.analytics.getTagAnalytics({
  entityTypes: [TaggableEntityType.CAMPAIGN]
});

Defined in

managers/analytics-manager.ts:519


getAnalyticsService

▸ getAnalyticsService(): AnalyticsService

Get the full analytics service for advanced operations

Provides access to the complete AnalyticsService instance for advanced analytics operations, custom metrics, predictive analytics, cohort analysis, and operations not covered by the high-level manager methods.

Returns

AnalyticsService

AnalyticsService instance with full API access

Example

const analyticsService = sdk.analytics.getAnalyticsService();

// Access user engagement analytics
const engagementMetrics = await analyticsService.getUserEngagementMetrics({
  timeframe: 'last-90-days',
  includeSegmentation: true
});

// Access campaign performance analytics
const campaignMetrics = await analyticsService.getCampaignPerformance({
  campaignIds: ['summer-2024', 'holiday-2024'],
  includeConversionFunnel: true
});

// Access token distribution analytics
const tokenAnalytics = await analyticsService.getTokenDistributionAnalytics({
  tokenTypes: ['CREDIT', 'REWARD'],
  includePredictions: true
});

// Access cohort analysis
const cohorts = await analyticsService.getCohortAnalysis({
    cohortType: 'monthly',
    startDate: '2024-01-01',
    metrics: ['retention', 'revenue', 'activity']
});

// Access predictive analytics
const predictions = await analyticsService.getPredictiveAnalytics({
  model: 'customer-lifetime-value',
  horizon: '12-months'
});

// Access real-time streaming analytics
const realTimeStream = analyticsService.getRealtimeMetrics();
realTimeStream.on('update', (metrics) => {
  console.log('Real-time update:', metrics);
});

// Access custom analytics queries
const customAnalytics = await analyticsService.executeCustomQuery({
  query: 'business-performance-by-region',
  parameters: { region: 'north-america', timeframe: 'Q1-2024' }
});

console.log('Advanced analytics data retrieved');

Defined in

managers/analytics-manager.ts:582