import { BaseSDK } from './sdk'; import { TaskTracker, TaskResponse, type ResponseType } from '@jolibox/types'; export enum JoliboxTaskEvents { LEVEL_FINISHED = 'JOLIBOX_TASK_LEVEL_FINISHED', GAME_PLAY_ENDED = 'JOLIBOX_TASK_GAME_PLAY_ENDED', LEVEL_UPGRADE = 'JOLIBOX_TASK_LEVEL_UPGRADE', LEVEL_START = 'JOLIBOX_LEVEL_START_EVENT', LEVEL_FAILED = 'JOLIBOX_LEVEL_FAIL_EVENT' } /** * @public * Provides functionalities for task tracking within the Jolibox SDK. * Allows tracking of game levels, gameplay sessions, and level upgrades. * @implements {TaskTracker} */ export class TaskTrackerSDK extends BaseSDK implements TaskTracker { /** * Handles completion of a game level by sending analytics data to the backend * * @param params - Object containing level completion details: * @param params.levelId - Unique identifier for the completed level (string or number) * @param params.duration - Optional time spent in the level (milliseconds) * @param params.rating - Optional user rating for the level * @param params.score - Optional final score achieved in the level * @param params.variation - Optional variation * @returns Promise resolving to TaskResponse or error message if validation fails * @throws {Promise} Rejects with error if params is not an object */ async onLevelFinished(params: { levelId: string | number; duration?: number; rating?: number; score?: number; variation?: string; }): Promise { if (typeof params !== 'object') { return Promise.reject({ code: 'FAILURE' as ResponseType, message: 'params must be an object' }); } const { levelId, duration, rating, score, variation } = params; const errMsg = this.canIUseIfThrow('TaskTrackerSDK.onLevelFinished'); if (errMsg) { return Promise.resolve(errMsg); } const event = new CustomEvent(JoliboxTaskEvents.LEVEL_FINISHED, { detail: params }); window.dispatchEvent(event); return await this.commands.executeCommand('TaskTrackerSDK.levelFinished', { levelId, duration, rating, score, variation }); } /** * Records completion of a gameplay session with final metrics * * @param params - Object containing gameplay session details: * @param params.duration - Optional total time spent in gameplay (milliseconds) * @param params.rating - Optional user rating for the gameplay session * @param params.score - Mandatory final score achieved during gameplay * @param params.variation - Optional variation * @returns Promise resolving to TaskResponse or error message if validation fails * @throws {Promise} Rejects with error if params is not an object */ async onGamePlayEnded(params: { duration?: number; rating?: number; score: number; variation?: string; }): Promise { if (typeof params !== 'object') { return Promise.reject({ code: 'FAILURE' as ResponseType, message: 'params must be an object' }); } const { duration, rating, score, variation } = params; const errMsg = this.canIUseIfThrow('TaskTrackerSDK.onGamePlayEnded'); if (errMsg) { return Promise.resolve(errMsg); } const event = new CustomEvent(JoliboxTaskEvents.GAME_PLAY_ENDED, { detail: params }); window.dispatchEvent(event); return await this.commands.executeCommand('TaskTrackerSDK.gamePlayEnded', { duration, rating, score, variation }); } /** * Tracks player progression when they upgrade to a new level * * @param params - Object containing level upgrade details: * @param params.levelId - Unique identifier for the new level (string or number) * @param params.name - Optional display name for the upgraded level * @returns Promise resolving to TaskResponse or error message if validation fails * @throws {Promise} Rejects with error if params is not an object */ async onLevelUpgrade(params: { levelId: string | number; name?: string }): Promise { if (typeof params !== 'object') { return Promise.reject({ code: 'FAILURE' as ResponseType, message: 'params must be an object' }); } const { levelId, name } = params; const errMsg = this.canIUseIfThrow('TaskTrackerSDK.onLevelUpgrade'); if (errMsg) { return errMsg; } const event = new CustomEvent(JoliboxTaskEvents.LEVEL_UPGRADE, { detail: params }); window.dispatchEvent(event); return await this.commands.executeCommand('TaskTrackerSDK.levelUpgrade', { levelId, name }); } /** * Tracks when a game level starts * * @param params - Object containing level start details: * @param params.levelId - Unique identifier for the level being started (string or number) * @returns Promise resolving to TaskResponse or error message if validation fails * @throws {Promise} Rejects with error if params is not an object */ async onLevelStart(params: { levelId: string | number }): Promise { if (typeof params !== 'object') { return Promise.reject({ code: 'FAILURE' as ResponseType, message: 'params must be an object' }); } const { levelId } = params; const errMsg = this.canIUseIfThrow('TaskTrackerSDK.onLevelStart'); if (errMsg) { return Promise.resolve(errMsg); } const event = new CustomEvent(JoliboxTaskEvents.LEVEL_START, { detail: params }); window.dispatchEvent(event); return await this.commands.executeCommand('TaskTrackerSDK.levelStart', { levelId }); } /** * Tracks when a game level fails * * @param params - Object containing level failure details: * @param params.levelId - Unique identifier for the failed level (string or number) * @param params.score - Optional total score achieved in the level * @param params.rating - Optional star rating (how many stars earned) * @param params.duration - Optional time spent in the level (milliseconds) * @returns Promise resolving to TaskResponse or error message if validation fails * @throws {Promise} Rejects with error if params is not an object */ async onLevelFailed(params: { levelId: string | number; score?: number; rating?: number; duration?: number; }): Promise { if (typeof params !== 'object') { return Promise.reject({ code: 'FAILURE' as ResponseType, message: 'params must be an object' }); } const { levelId, score, rating, duration } = params; const errMsg = this.canIUseIfThrow('TaskTrackerSDK.onLevelFailed'); if (errMsg) { return Promise.resolve(errMsg); } const event = new CustomEvent(JoliboxTaskEvents.LEVEL_FAILED, { detail: params }); window.dispatchEvent(event); return await this.commands.executeCommand('TaskTrackerSDK.levelFailed', { levelId, score, rating, duration }); } }