Sessions API

The Sessions API enables you to track user activity, analyze engagement patterns, and gain insights into how players interact with your games. Monitor session duration, platform distribution, retention rates, and user behavior across your entire app portfolio.

Authentication

All endpoints require authentication using either:

• API Key: Include x-api-key header
• Cognito JWT: Include Authorization: Bearer <token> header
• Developer Auth: Special authentication for developer operations

Base URL

https://sdk.getjar.com/sessions

---

Core Concepts

What is a Session?

A session represents a single usage period of your app by a user. Sessions are used to track:

• User Engagement: How often users play your game
• Platform Distribution: Which platforms are most popular
• Retention Metrics: How many users come back
• Geographic Data: Where your users are located
• Version Adoption: How quickly users update

Session Lifecycle

// 1. User launches app
await createSession({
  appId: "app_123",
  cognitoUserId: "user_123",
  platform: "IOS",
  appVersion: "1.2.3",
  metadata: {
    deviceModel: "iPhone 14 Pro",
    osVersion: "17.0",
    country: "US",
  },
});

// 2. Session is tracked
// GetJar automatically monitors session activity

// 3. Analytics available
// View user stats, app analytics, retention rates

---

Create Session

Initialize a new user session for tracking app usage and analytics.

Endpoint

POST /sessions

Request Body

{
  cognitoUserId: string;            // Required: AWS Cognito user ID
  appId: string;                    // Required: Application ID
  platform: string;                 // Required: IOS, ANDROID, WEB, WINDOWS, MAC, LINUX
  appVersion: string;               // Required: App version (e.g., '1.2.3')
  metadata?: {                      // Optional: Additional tracking data
    deviceModel?: string;           // Device model
    osVersion?: string;             // OS version
    country?: string;               // Country code
    city?: string;                  // City name
    ipAddress?: string;             // IP address
    userAgent?: string;             // User agent string
    [key: string]: any;             // Custom metadata
  };
}

Response

{
  sessionId: string;
  cognitoUserId: string;
  appId: string;
  appName: string;
  platform: string;
  appVersion: string;
  metadata: object;
  createdAt: string;
}

Example

import { SessionsApi } from "@getjar-iap/sdk";

const sessionsApi = new SessionsApi(configuration);

const session = await sessionsApi.createSession({
  body: {
    appId: "app_123",
    cognitoUserId: "us-east-1:12345678-1234-1234-1234-123456789012",
    platform: "IOS",
    appVersion: "1.2.3",
    metadata: {
      deviceModel: "iPhone 14 Pro",
      osVersion: "17.0",
      country: "US",
      city: "New York",
    },
  },
});

console.log("Session ID:", session.data.sessionId);
console.log("Created:", session.data.createdAt);

Platform Values

Platform	Description
IOS	iPhone/iPad
ANDROID	Android devices
WEB	Web browser
WINDOWS	Windows desktop
MAC	macOS desktop
LINUX	Linux desktop

Response Codes

Code	Description
201	Session created successfully
400	Invalid session data
401	Unauthorized

---

Get Session by ID

Retrieve detailed information about a specific session.

Endpoint

GET /sessions/:sessionId

Parameters

Parameter	Type	Required	Description
sessionId	string	Yes	The unique session identifier

Response

{
  sessionId: string;
  cognitoUserId: string;
  appId: string;
  appName: string;
  platform: string;
  appVersion: string;
  metadata: {
    deviceModel: string;
    osVersion: string;
    country: string;
    city: string;
    ipAddress: string;
    userAgent: string;
  }
  createdAt: string;
  updatedAt: string;
}

Example

const session = await sessionsApi.getSessionById({
  sessionId: "sess_123",
});

console.log("User:", session.data.cognitoUserId);
console.log("Platform:", session.data.platform);
console.log("Version:", session.data.appVersion);
console.log("Location:", session.data.metadata?.country);

Response Codes

Code	Description
200	Session retrieved
401	Unauthorized
404	Session does not exist

---

Get User Sessions

Retrieve a paginated list of all sessions for a specific user.

Endpoint

GET /sessions/users/:cognitoUserId

Parameters

Parameter	Type	Required	Description
cognitoUserId	string	Yes	AWS Cognito user identifier
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20)
startDate	string	No	Start date (ISO format)
endDate	string	No	End date (ISO format)

Response

{
  items: Array<{
    sessionId: string;
    cognitoUserId: string;
    appId: string;
    appName: string;
    platform: string;
    appVersion: string;
    metadata: object;
    createdAt: string;
  }>;
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  }
}

Example

// Get all user sessions
const sessions = await sessionsApi.getUserSessions({
  cognitoUserId: "us-east-1:12345678-1234-1234-1234-123456789012",
  page: 1,
  limit: 50,
});

console.log("Total sessions:", sessions.data.pagination.total);
console.log("Recent sessions:", sessions.data.items.slice(0, 5));

// Get sessions for date range
const recentSessions = await sessionsApi.getUserSessions({
  cognitoUserId: "us-east-1:12345678-1234-1234-1234-123456789012",
  startDate: "2025-10-01T00:00:00Z",
  endDate: "2025-10-31T23:59:59Z",
  page: 1,
  limit: 20,
});

console.log("October sessions:", recentSessions.data.items);

Response Codes

Code	Description
200	Sessions retrieved
401	Unauthorized
404	User does not exist

---

Get User Session Statistics

Retrieve comprehensive session analytics for a user including total sessions, unique apps, and platform breakdown.

Endpoint

GET /sessions/users/:cognitoUserId/stats

Parameters

Parameter	Type	Required	Description
cognitoUserId	string	Yes	AWS Cognito user identifier
startDate	string	No	Start date (ISO format)
endDate	string	No	End date (ISO format)

Response

{
  totalSessions: number;
  uniqueApps: number;
  totalPlayTime: number; // Minutes
  averageSessionDuration: number; // Minutes
  mostPlayedGame: {
    appId: string;
    appName: string;
    sessionCount: number;
    percentage: number;
  }
  topPlatform: {
    platform: string;
    sessionCount: number;
    percentage: number;
  }
  sessionsByApp: Array<{
    appId: string;
    appName: string;
    sessionCount: number;
  }>;
  sessionsByPlatform: Array<{
    platform: string;
    sessionCount: number;
  }>;
  recentActivity: Array<{
    sessionId: string;
    appName: string;
    platform: string;
    createdAt: string;
  }>;
}

Example

const stats = await sessionsApi.getUserSessionStats({
  cognitoUserId: "us-east-1:12345678-1234-1234-1234-123456789012",
});

console.log("📊 User Statistics:");
console.log("Total Sessions:", stats.data.totalSessions);
console.log("Total Play Time:", `${stats.data.totalPlayTime} minutes`);
console.log("Average Session:", `${stats.data.averageSessionDuration} minutes`);
console.log("\n🎮 Most Played:");
console.log(
  `${stats.data.mostPlayedGame.appName} (${stats.data.mostPlayedGame.percentage}%)`
);
console.log("\n📱 Top Platform:");
console.log(
  `${stats.data.topPlatform.platform} (${stats.data.topPlatform.percentage}%)`
);

// Get stats for specific time period
const monthStats = await sessionsApi.getUserSessionStats({
  cognitoUserId: "us-east-1:12345678-1234-1234-1234-123456789012",
  startDate: "2025-10-01T00:00:00Z",
  endDate: "2025-10-31T23:59:59Z",
});

console.log("October playtime:", `${monthStats.data.totalPlayTime} minutes`);

Response Codes

Code	Description
200	Statistics retrieved
401	Unauthorized
404	User does not exist

---

Get App Sessions

Retrieve a paginated list of all sessions for a specific app.

Endpoint

GET /sessions/apps/:appId

Parameters

Parameter	Type	Required	Description
appId	string	Yes	The application identifier
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20)
startDate	string	No	Start date (ISO format)
endDate	string	No	End date (ISO format)

Response

{
  items: Array<{
    sessionId: string;
    cognitoUserId: string;
    appId: string;
    appName: string;
    platform: string;
    appVersion: string;
    metadata: object;
    createdAt: string;
  }>;
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  }
}

Example

const appSessions = await sessionsApi.getAppSessions({
  appId: "app_123",
  page: 1,
  limit: 100,
});

console.log("Total sessions:", appSessions.data.pagination.total);
console.log(
  "Active users:",
  new Set(appSessions.data.items.map((s) => s.cognitoUserId)).size
);

Response Codes

Code	Description
200	Sessions retrieved
401	Unauthorized
404	App does not exist

---

Get App Session Analytics

Retrieve comprehensive session analytics for an app including user engagement, retention, and platform distribution.

Endpoint

GET /sessions/apps/:appId/analytics

Parameters

Parameter	Type	Required	Description
appId	string	Yes	The application identifier
startDate	string	No	Start date (ISO format)
endDate	string	No	End date (ISO format)

Response

{
  totalSessions: number;
  uniqueUsers: number;
  averageSessionsPerUser: number;
  totalPlayTime: number; // Minutes
  averageSessionDuration: number; // Minutes
  dailyActiveUsers: number; // DAU
  monthlyActiveUsers: number; // MAU
  retentionRate: {
    day1: number; // Percentage
    day7: number; // Percentage
    day30: number; // Percentage
  }
  platformDistribution: Array<{
    platform: string;
    sessionCount: number;
    userCount: number;
    percentage: number;
  }>;
  versionDistribution: Array<{
    version: string;
    sessionCount: number;
    percentage: number;
  }>;
  geographicDistribution: Array<{
    country: string;
    sessionCount: number;
    percentage: number;
  }>;
  peakUsageHours: Array<{
    hour: number; // 0-23 UTC
    sessionCount: number;
  }>;
  sessionsOverTime: Array<{
    date: string; // YYYY-MM-DD
    sessionCount: number;
    uniqueUsers: number;
  }>;
}

Example

const analytics = await sessionsApi.getAppAnalytics({
  appId: "app_123",
});

console.log("📊 App Analytics:");
console.log("Total Sessions:", analytics.data.totalSessions);
console.log("Unique Users:", analytics.data.uniqueUsers);
console.log("DAU:", analytics.data.dailyActiveUsers);
console.log("MAU:", analytics.data.monthlyActiveUsers);
console.log(
  "Avg Sessions/User:",
  analytics.data.averageSessionsPerUser.toFixed(2)
);

console.log("\n📱 Retention Rates:");
console.log("Day 1:", `${analytics.data.retentionRate.day1}%`);
console.log("Day 7:", `${analytics.data.retentionRate.day7}%`);
console.log("Day 30:", `${analytics.data.retentionRate.day30}%`);

console.log("\n🌍 Platform Distribution:");
analytics.data.platformDistribution.forEach((platform) => {
  console.log(
    `${platform.platform}: ${platform.sessionCount} sessions (${platform.percentage}%)`
  );
});

console.log("\n📍 Top Countries:");
analytics.data.geographicDistribution.slice(0, 5).forEach((geo) => {
  console.log(
    `${geo.country}: ${geo.sessionCount} sessions (${geo.percentage}%)`
  );
});

// Get analytics for specific time period
const monthlyAnalytics = await sessionsApi.getAppAnalytics({
  appId: "app_123",
  startDate: "2025-10-01T00:00:00Z",
  endDate: "2025-10-31T23:59:59Z",
});

console.log("\nOctober Analytics:");
console.log("Sessions:", monthlyAnalytics.data.totalSessions);
console.log("Unique Users:", monthlyAnalytics.data.uniqueUsers);

Response Codes

Code	Description
200	Analytics retrieved
401	Unauthorized
404	App does not exist

---

Delete Old Sessions

Soft delete sessions older than the specified number of days. Useful for data cleanup and GDPR compliance.

Endpoint

DELETE /sessions/cleanup/:daysOld

Parameters

Parameter	Type	Required	Description
daysOld	number	Yes	Delete sessions older than this many days

Response

{
  success: boolean;
  deletedCount: number;
  cutoffDate: string;
}

Example

// Delete sessions older than 90 days
const result = await sessionsApi.deleteOldSessions({
  daysOld: 90,
});

console.log("Deleted:", result.data.deletedCount, "sessions");
console.log("Cutoff date:", result.data.cutoffDate);

// Delete sessions older than 30 days (monthly cleanup)
await sessionsApi.deleteOldSessions({
  daysOld: 30,
});

Response Codes

Code	Description
200	Sessions deleted successfully
400	Invalid days parameter
401	Unauthorized

---

Complete Example

Here's a complete workflow for implementing session tracking and analytics:

import { Configuration, SessionsApi } from "@getjar-iap/sdk";

const configuration = new Configuration({
  basePath: "https://sdk.getjar.com",
  apiKey: "your-api-key",
});

const sessionsApi = new SessionsApi(configuration);

async function sessionTrackingExample() {
  const appId = "app_123";
  const userId = "us-east-1:12345678-1234-1234-1234-123456789012";

  console.log("🎮 Starting session tracking...\n");

  // 1. Create a new session when user launches app
  const session = await sessionsApi.createSession({
    body: {
      appId,
      cognitoUserId: userId,
      platform: "IOS",
      appVersion: "1.2.3",
      metadata: {
        deviceModel: "iPhone 14 Pro",
        osVersion: "17.0",
        country: "US",
        city: "New York",
      },
    },
  });

  console.log("✓ Session created:", session.data.sessionId);

  // 2. Get user's session history
  const userSessions = await sessionsApi.getUserSessions({
    cognitoUserId: userId,
    page: 1,
    limit: 10,
  });

  console.log("\n📱 Recent Sessions:");
  userSessions.data.items.forEach((session, index) => {
    console.log(`${index + 1}. ${session.appName} on ${session.platform}`);
    console.log(`   ${new Date(session.createdAt).toLocaleString()}`);
  });

  // 3. Get user statistics
  const userStats = await sessionsApi.getUserSessionStats({
    cognitoUserId: userId,
  });

  console.log("\n📊 User Statistics:");
  console.log("Total Sessions:", userStats.data.totalSessions);
  console.log(
    "Total Play Time:",
    `${userStats.data.totalPlayTime} minutes (${(
      userStats.data.totalPlayTime / 60
    ).toFixed(1)} hours)`
  );
  console.log(
    "Average Session:",
    `${userStats.data.averageSessionDuration} minutes`
  );
  console.log("Games Played:", userStats.data.uniqueApps);

  console.log("\n🏆 Most Played Game:");
  console.log(`${userStats.data.mostPlayedGame.appName}`);
  console.log(`${userStats.data.mostPlayedGame.sessionCount} sessions`);
  console.log(`${userStats.data.mostPlayedGame.percentage}% of total`);

  // 4. Get app analytics
  const appAnalytics = await sessionsApi.getAppAnalytics({
    appId,
  });

  console.log("\n📈 App Analytics:");
  console.log("Total Sessions:", appAnalytics.data.totalSessions);
  console.log("Unique Users:", appAnalytics.data.uniqueUsers);
  console.log("DAU:", appAnalytics.data.dailyActiveUsers);
  console.log("MAU:", appAnalytics.data.monthlyActiveUsers);
  console.log(
    "Avg Sessions/User:",
    appAnalytics.data.averageSessionsPerUser.toFixed(2)
  );

  console.log("\n🔄 Retention Rates:");
  console.log("Day 1:", `${appAnalytics.data.retentionRate.day1}%`);
  console.log("Day 7:", `${appAnalytics.data.retentionRate.day7}%`);
  console.log("Day 30:", `${appAnalytics.data.retentionRate.day30}%`);

  console.log("\n📱 Platform Breakdown:");
  appAnalytics.data.platformDistribution.forEach((platform) => {
    console.log(
      `${platform.platform}: ${platform.userCount} users (${platform.percentage}%)`
    );
  });

  // 5. Get monthly analytics
  const monthStart = new Date();
  monthStart.setDate(1);
  monthStart.setHours(0, 0, 0, 0);

  const monthEnd = new Date();

  const monthlyAnalytics = await sessionsApi.getAppAnalytics({
    appId,
    startDate: monthStart.toISOString(),
    endDate: monthEnd.toISOString(),
  });

  console.log("\n📅 This Month:");
  console.log("Sessions:", monthlyAnalytics.data.totalSessions);
  console.log("Unique Users:", monthlyAnalytics.data.uniqueUsers);
  console.log(
    "Total Play Time:",
    `${monthlyAnalytics.data.totalPlayTime} minutes`
  );

  // 6. Clean up old sessions (quarterly)
  const cleanup = await sessionsApi.deleteOldSessions({
    daysOld: 90,
  });

  console.log("\n🧹 Cleanup:");
  console.log("Deleted:", cleanup.data.deletedCount, "old sessions");

  return appAnalytics;
}

// Run the example
sessionTrackingExample()
  .then(() => console.log("\n✅ Session tracking complete!"))
  .catch((error) => console.error("❌ Error:", error));

---

Analytics Dashboard Example

Build a comprehensive analytics dashboard:

async function buildAnalyticsDashboard(appId: string) {
  // Get current month analytics
  const now = new Date();
  const monthStart = new Date(now.getFullYear(), now.getMonth(), 1);
  const monthEnd = new Date(now.getFullYear(), now.getMonth() + 1, 0);

  const analytics = await sessionsApi.getAppAnalytics({
    appId,
    startDate: monthStart.toISOString(),
    endDate: monthEnd.toISOString(),
  });

  // Calculate engagement metrics
  const engagementScore =
    (analytics.data.dailyActiveUsers / analytics.data.monthlyActiveUsers) * 100;

  const dashboard = {
    overview: {
      totalSessions: analytics.data.totalSessions,
      uniqueUsers: analytics.data.uniqueUsers,
      dau: analytics.data.dailyActiveUsers,
      mau: analytics.data.monthlyActiveUsers,
      dauMauRatio: `${engagementScore.toFixed(1)}%`,
      avgSessionDuration: `${analytics.data.averageSessionDuration} min`,
      avgSessionsPerUser: analytics.data.averageSessionsPerUser.toFixed(2),
    },
    retention: {
      day1: `${analytics.data.retentionRate.day1}%`,
      day7: `${analytics.data.retentionRate.day7}%`,
      day30: `${analytics.data.retentionRate.day30}%`,
    },
    platforms: analytics.data.platformDistribution.map((p) => ({
      name: p.platform,
      users: p.userCount,
      sessions: p.sessionCount,
      percentage: `${p.percentage}%`,
    })),
    geography: analytics.data.geographicDistribution.slice(0, 10).map((g) => ({
      country: g.country,
      sessions: g.sessionCount,
      percentage: `${g.percentage}%`,
    })),
    peakHours: analytics.data.peakUsageHours
      .sort((a, b) => b.sessionCount - a.sessionCount)
      .slice(0, 5)
      .map((h) => ({
        hour: `${h.hour}:00 UTC`,
        sessions: h.sessionCount,
      })),
    timeline: analytics.data.sessionsOverTime.map((d) => ({
      date: d.date,
      sessions: d.sessionCount,
      uniqueUsers: d.uniqueUsers,
    })),
  };

  console.log("📊 Analytics Dashboard\n");
  console.log("Overview:");
  console.log(JSON.stringify(dashboard.overview, null, 2));
  console.log("\nRetention:");
  console.log(JSON.stringify(dashboard.retention, null, 2));
  console.log("\nTop Platforms:");
  console.log(JSON.stringify(dashboard.platforms, null, 2));
  console.log("\nTop Countries:");
  console.log(JSON.stringify(dashboard.geography, null, 2));
  console.log("\nPeak Hours:");
  console.log(JSON.stringify(dashboard.peakHours, null, 2));

  return dashboard;
}

---

User Activity Timeline

Track a user's complete activity timeline:

async function getUserActivityTimeline(userId: string) {
  // Get all sessions
  const sessions = await sessionsApi.getUserSessions({
    cognitoUserId: userId,
    page: 1,
    limit: 100,
  });

  // Get statistics
  const stats = await sessionsApi.getUserSessionStats({
    cognitoUserId: userId,
  });

  // Build timeline
  const timeline = {
    user: {
      id: userId,
      totalSessions: stats.data.totalSessions,
      totalPlayTime: `${stats.data.totalPlayTime} minutes`,
      averageSession: `${stats.data.averageSessionDuration} minutes`,
    },
    favoriteGame: stats.data.mostPlayedGame,
    preferredPlatform: stats.data.topPlatform,
    gamesPlayed: stats.data.sessionsByApp,
    recentActivity: sessions.data.items.slice(0, 10).map((session) => ({
      date: new Date(session.createdAt).toLocaleDateString(),
      time: new Date(session.createdAt).toLocaleTimeString(),
      game: session.appName,
      platform: session.platform,
      version: session.appVersion,
    })),
  };

  console.log("👤 User Activity Timeline\n");
  console.log("User Info:", timeline.user);
  console.log("\n🎮 Favorite Game:", timeline.favoriteGame);
  console.log("\n📱 Preferred Platform:", timeline.preferredPlatform);
  console.log("\n📅 Recent Sessions:");
  timeline.recentActivity.forEach((activity, index) => {
    console.log(
      `${index + 1}. ${activity.date} ${activity.time} - ${activity.game} (${
        activity.platform
      })`
    );
  });

  return timeline;
}

---

Best Practices

Session Creation

1. Create on Launch: Initialize session when user starts your app

   // On app launch
   await createSession({
     appId,
     cognitoUserId,
     platform: detectPlatform(),
     appVersion: getAppVersion(),
     metadata: collectMetadata(),
   });

2. Include Metadata: Capture useful context

   metadata: {
     deviceModel: "iPhone 14 Pro",
     osVersion: "17.0",
     country: "US",
     language: "en",
     screenResolution: "2556x1179"
   }

3. Handle Errors Gracefully: Don't block app launch if session creation fails

   try {
     await createSession({
       /* ... */
     });
   } catch (error) {
     console.error("Session creation failed:", error);
     // Continue app launch anyway
   }

Analytics Best Practices

1. Set Date Ranges: Use specific time periods for comparisons

   // This month vs last month
   const thisMonth = await getAppAnalytics({
     appId,
     startDate: thisMonthStart,
     endDate: now,
   });
   
   const lastMonth = await getAppAnalytics({
     appId,
     startDate: lastMonthStart,
     endDate: lastMonthEnd,
   });

2. Monitor Key Metrics:

   • DAU/MAU ratio (> 20% is good for mobile games)
   • Day 1 retention (> 40% is strong)
   • Day 7 retention (> 20% is good)
   • Average session duration (varies by game type)

3. Track Trends: Look at sessionsOverTime for patterns

   const analytics = await getAppAnalytics({ appId });
   
   const trend = analytics.data.sessionsOverTime;
   const lastWeek = trend.slice(-7);
   const avgDaily =
     lastWeek.reduce((sum, day) => sum + day.sessionCount, 0) / 7;
   
   console.log("Average daily sessions:", avgDaily);

Data Management

1. Regular Cleanup: Schedule periodic session cleanup

   // Run monthly
   async function monthlyCleanup() {
     await sessionsApi.deleteOldSessions({
       daysOld: 90, // Keep 3 months
     });
   }

2. GDPR Compliance: Delete user data on request

   async function deleteUserData(userId: string) {
     const sessions = await getUserSessions({
       cognitoUserId: userId,
       limit: 1000,
     });
   
     // Process deletion request
     // Sessions will be soft-deleted
   }

3. Export Analytics: Save regular reports

   async function exportMonthlyReport(appId: string) {
     const analytics = await getAppAnalytics({
       appId,
       startDate: monthStart,
       endDate: monthEnd,
     });
   
     // Save to file or send to analytics platform
     return analytics.data;
   }

Performance Optimization

1. Batch Requests: Minimize API calls

   // Good: Get all data in one analytics call
   const analytics = await getAppAnalytics({ appId });
   
   // Avoid: Multiple separate calls

2. Cache Results: Cache analytics data

   const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
   let analyticsCache = null;
   let cacheTimestamp = 0;
   
   async function getCachedAnalytics(appId: string) {
     if (Date.now() - cacheTimestamp < CACHE_TTL) {
       return analyticsCache;
     }
   
     analyticsCache = await getAppAnalytics({ appId });
     cacheTimestamp = Date.now();
     return analyticsCache;
   }

3. Paginate Large Results: Use appropriate page sizes

   // For display: smaller pages
   const sessions = await getAppSessions({
     appId,
     page: 1,
     limit: 20,
   });
   
   // For export: larger pages
   const allSessions = await getAppSessions({
     appId,
     page: 1,
     limit: 100,
   });

---

Common Patterns

Real-Time Active Users

async function getActiveUsersNow(appId: string) {
  const now = new Date();
  const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000);

  const recentSessions = await sessionsApi.getAppSessions({
    appId,
    startDate: oneHourAgo.toISOString(),
    endDate: now.toISOString(),
    limit: 1000,
  });

  const activeUsers = new Set(
    recentSessions.data.items.map((s) => s.cognitoUserId)
  );

  return {
    activeUsersLastHour: activeUsers.size,
    recentSessions: recentSessions.data.pagination.total,
  };
}

Cohort Analysis

async function analyzeCohort(appId: string, cohortDate: string) {
  // Get users who started on cohortDate
  const cohortStart = new Date(cohortDate);
  const cohortEnd = new Date(cohortStart);
  cohortEnd.setDate(cohortEnd.getDate() + 1);

  const initialSessions = await sessionsApi.getAppSessions({
    appId,
    startDate: cohortStart.toISOString(),
    endDate: cohortEnd.toISOString(),
    limit: 1000,
  });

  const cohortUsers = new Set(
    initialSessions.data.items.map((s) => s.cognitoUserId)
  );

  // Check retention at day 1, 7, 30
  const retentionChecks = [1, 7, 30];
  const retention = {};

  for (const day of retentionChecks) {
    const checkDate = new Date(cohortStart);
    checkDate.setDate(checkDate.getDate() + day);
    const checkEnd = new Date(checkDate);
    checkEnd.setDate(checkEnd.getDate() + 1);

    const returningSessions = await sessionsApi.getAppSessions({
      appId,
      startDate: checkDate.toISOString(),
      endDate: checkEnd.toISOString(),
      limit: 1000,
    });

    const returningUsers = new Set(
      returningSessions.data.items
        .map((s) => s.cognitoUserId)
        .filter((id) => cohortUsers.has(id))
    );

    retention[`day${day}`] = {
      returned: returningUsers.size,
      percentage: ((returningUsers.size / cohortUsers.size) * 100).toFixed(1),
    };
  }

  return {
    cohortDate: cohortDate,
    cohortSize: cohortUsers.size,
    retention,
  };
}

Version Adoption Tracking

async function trackVersionAdoption(appId: string) {
  const analytics = await sessionsApi.getAppAnalytics({ appId });

  const versionStats = analytics.data.versionDistribution.map((v) => ({
    version: v.version,
    sessions: v.sessionCount,
    adoption: `${v.percentage}%`,
    isLatest: v.version === "1.2.3", // Your latest version
  }));

  // Find outdated versions
  const outdated = versionStats.filter((v) => !v.isLatest);

  return {
    currentVersion: "1.2.3",
    latestVersionAdoption: versionStats.find((v) => v.isLatest)?.adoption,
    allVersions: versionStats,
    outdatedVersions: outdated,
  };
}

---

Error Handling

async function safeSessionOperation() {
  try {
    const session = await sessionsApi.createSession({
      body: {
        /* ... */
      },
    });

    return {
      success: true,
      data: session.data,
    };
  } catch (error) {
    if (error.response) {
      switch (error.response.status) {
        case 400:
          console.error("Invalid session data:", error.response.data.message);
          break;
        case 401:
          console.error("Authentication required");
          break;
        case 404:
          console.error("App or user not found");
          break;
        default:
          console.error("Unexpected error:", error.response.status);
      }
    }

    return {
      success: false,
      error: error.message,
    };
  }
}

---

Support

For additional help or questions:

• Documentation: https://docs.getjar.com
• API Reference: https://sdk.getjar.com/api/docs
• Support: support@getjar.com