Skip to main content

App Streak SDK

The App Streak SDK provides methods to manage user engagement streaks for your applications on the GetJar platform. Streaks track consecutive days of user activity and can include freeze functionality to preserve streaks during user absences.

Initialization​

import { Configuration, AppStreak } from '@eightpointio/getjar-iap-sdk';

const config = new Configuration({
  basePath: 'url',
  headers: { 'x-api-key': 'key' }
});

const streakClient = new AppStreak(config);

Methods​

getStreak​

Retrieves the current streak data for a specific user in an application.

Parameters:

  • userId (string): User ID
  • appId (string): Application ID

Returns: Promise<IAppStreak>

const streak = await streakClient.getStreak('user-123', 'app-456');

console.log(streak.currentStreak);
console.log(streak.longestStreak);
console.log(streak.lastActivityDate);

updateStreak​

Updates or increments a user's streak based on their activity.

Parameters:

  • userId (string): User ID
  • appId (string): Application ID
  • payload (IStreakUpdateRequest): Update data
    • activityDate (string, optional): Date of activity (defaults to current date)
    • metadata (Record<string, any>, optional): Additional data

Returns: Promise<IStreakUpdateResponse>

const result = await streakClient.updateStreak('user-123', 'app-456', {
  activityDate: '2025-01-19'
});

console.log(result.streak);
console.log(result.streakIncremented);
console.log(result.message);

applyStreakFreeze​

Applies a freeze to a user's streak, allowing them to maintain their streak during a period of inactivity.

Parameters:

  • userId (string): User ID
  • appId (string): Application ID
  • payload (IStreakFreezeRequest): Freeze configuration
    • freezeDays (number): Number of days to freeze the streak
    • reason (string, optional): Reason for the freeze

Returns: Promise<IStreakFreezeResponse>

const result = await streakClient.applyStreakFreeze('user-123', 'app-456', {
  freezeDays: 3,
  reason: 'Weekend pass'
});

console.log(result.success);
console.log(result.freezeAppliedUntil);
console.log(result.remainingFreezes);

resetStreak​

Resets a user's streak back to zero.

Parameters:

  • userId (string): User ID
  • appId (string): Application ID

Returns: Promise<IStreakResetResponse>

const result = await streakClient.resetStreak('user-123', 'app-456');

console.log(result.success);
console.log(result.previousStreak);

Types​

IAppStreak​

interface IAppStreak {
  streakId: string;
  userId: string;
  appId: string;
  currentStreak: number;
  longestStreak: number;
  lastActivityDate: string;
  streakStartDate: string;
  totalActiveDays: number;
  freezesRemaining?: number;
  freezeActiveUntil?: string;
  metadata?: Record<string, any>;
  createdAt: Date;
  updatedAt: Date;
}

IStreakUpdateRequest​

interface IStreakUpdateRequest {
  activityDate?: string;
  metadata?: Record<string, any>;
}

IStreakUpdateResponse​

interface IStreakUpdateResponse {
  success: boolean;
  streak: IAppStreak;
  streakIncremented: boolean;
  message: string;
}

IStreakFreezeRequest​

interface IStreakFreezeRequest {
  freezeDays: number;
  reason?: string;
}

IStreakFreezeResponse​

interface IStreakFreezeResponse {
  success: boolean;
  message: string;
  freezeAppliedUntil: string;
  remainingFreezes?: number;
}

IStreakResetResponse​

interface IStreakResetResponse {
  success: boolean;
  previousStreak: number;
  message: string;
}

Complete Example​

import { Configuration, AppStreak } from '@eightpointio/getjar-iap-sdk';

const config = new Configuration({
  basePath: 'https://sdk-new.getjar.com',
  headers: { 'x-api-key': 'your-api-key' }
});

const streakClient = new AppStreak(config);

async function manageUserStreak(userId: string, appId: string) {
  const streak = await streakClient.getStreak(userId, appId);
  console.log(`Current streak: ${streak.currentStreak} days`);
  console.log(`Longest streak: ${streak.longestStreak} days`);

  const updateResult = await streakClient.updateStreak(userId, appId, {});

  if (updateResult.streakIncremented) {
    console.log('Streak incremented!');
    console.log(`New streak: ${updateResult.streak.currentStreak}`);
  } else {
    console.log('Streak already updated today');
  }

  if (streak.freezesRemaining && streak.freezesRemaining > 0) {
    const freezeResult = await streakClient.applyStreakFreeze(userId, appId, {
      freezeDays: 1,
      reason: 'Daily freeze power-up'
    });
    console.log(`Freeze applied until: ${freezeResult.freezeAppliedUntil}`);
  }
}

manageUserStreak('user-123', 'app-456');

Best Practices​

  1. Daily updates: Call updateStreak() once per day when the user completes their daily activity
  2. Check existing streak: Use getStreak() before updating to show current progress to users
  3. Freeze management: Track available freezes and allow users to apply them strategically
  4. Reset with caution: Only reset streaks when explicitly requested by users or required by game logic
  5. Metadata usage: Store additional context (e.g., activity type, rewards earned) in the metadata field