Game Streak SDK

The Game Streak SDK provides methods to manage user engagement streaks for your games 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, GameStreak } from '@eightpointio/getjar-iap-sdk';

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

const streakClient = new GameStreak(config);

Methods

getStreak

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

Parameters:

• userId (string): User ID
• gameId (string): Game ID

Returns: Promise<IGameStreak>

const streak = await streakClient.getStreak('user-123', 'game-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
• gameId (string): Game 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', 'game-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
• gameId (string): Game 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', 'game-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
• gameId (string): Game ID

Returns: Promise<IStreakResetResponse>

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

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

Types

IGameStreak

interface IGameStreak {
  streakId: string;
  userId: string;
  gameId: 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: IGameStreak;
  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, GameStreak } 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 GameStreak(config);

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

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

  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, gameId, {
      freezeDays: 1,
      reason: 'Daily freeze power-up'
    });
    console.log(`Freeze applied until: ${freezeResult.freezeAppliedUntil}`);
  }
}

manageUserStreak('user-123', 'game-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