PERS SDK - v2.3.26 / Exports / 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()
]);- getTransactionAnalytics
- getCampaignClaimAnalytics
- getRedemptionRedeemAnalytics
- getUserAnalytics
- getUserRanking
- getBusinessRanking
- getRetentionAnalytics
- getTagAnalytics
- getAnalyticsService
• new AnalyticsManager(apiClient): AnalyticsManager
| Name | Type |
|---|---|
apiClient | PersApiClient |
managers/analytics-manager.ts:75
▸ 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.
| Name | Type | Description |
|---|---|---|
request | TransactionAnalyticsRequestDTO | Analytics request parameters including date range, filters, and metrics |
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();managers/analytics-manager.ts:260
▸ 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.
| Name | Type | Description |
|---|---|---|
request | CampaignClaimAnalyticsRequestDTO | Analytics request with filters, groupBy, and metrics |
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);managers/analytics-manager.ts:288
▸ 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.
| Name | Type | Description |
|---|---|---|
request | RedemptionRedeemAnalyticsRequestDTO | Analytics request with filters, groupBy, and metrics |
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'
});managers/analytics-manager.ts:338
▸ 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
| Name | Type | Description |
|---|---|---|
request | UserAnalyticsRequestDTO | Analytics request with optional filters and date range |
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)}`);managers/analytics-manager.ts:411
▸ 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
| Name | Type | Description |
|---|---|---|
request | UserRankingAnalyticsRequestDTO | Ranking request with filters, sorting, and limit |
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`);
});managers/analytics-manager.ts:464
▸ getBusinessRanking(request?): Promise<BusinessRankingAnalyticsResponseDTO>
Get business transaction ranking with enriched business data
Returns ranked list of businesses with full business details and transaction metrics.
| Name | Type | Description |
|---|---|---|
request | BusinessRankingAnalyticsRequestDTO | Ranking request with filters, sorting, and limit |
Promise<BusinessRankingAnalyticsResponseDTO>
Promise resolving to ranked business list
managers/analytics-manager.ts:476
▸ getRetentionAnalytics(request?): Promise<RetentionAnalyticsResponseDTO>
Get monthly user retention analytics
Returns monthly retention data with user metrics and retention rates.
| Name | Type | Description |
|---|---|---|
request | RetentionAnalyticsRequestDTO | Retention request with monthsBack and filters |
Promise<RetentionAnalyticsResponseDTO>
Promise resolving to monthly retention data
managers/analytics-manager.ts:488
▸ 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
| Name | Type | Description |
|---|---|---|
request | TagAnalyticsRequestDTO | Optional filters for entity types |
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]
});managers/analytics-manager.ts:519
▸ 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.
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');