//#region ../core/dist/index.d.ts //#endregion //#region build/ActivityEvent.d.ts /** Base interface for all Activity events. */ interface ActivityEvent extends M2Event { target: Activity; } //#endregion //#region build/ActivityKeyValueData.d.ts /** Data from activities are stored as key (string) value pairs. */ interface ActivityKeyValueData { [key: string]: string | number | boolean | object | undefined | null; } //#endregion //#region build/ActivityType.d.ts /** * The type of activity. * * @remarks Currently, m2c2kit has only Game and Survey activities. */ declare enum ActivityType { Game = "Game", Survey = "Survey" } //#endregion //#region build/ActivityMetric.d.ts /** A snapshot of performance at a single point in time. * * @remarks This describes performance of the application internals, not the * participant. Do not store participant data here. Use snake case because * these data will be directly exported to persistence. */ interface ActivityMetric { [key: string]: string | number | boolean | object | undefined | null; activity_type: ActivityType; activity_uuid: string; iso8601_timestamp: string; } //#endregion //#region build/JsonSchema.d.ts interface JsonSchema { /** Data type of the value or array of acceptable data types. */ type?: JsonSchemaDataType | JsonSchemaDataType[]; /** Values the schema can have. */ enum?: unknown[]; /** Annotation to indicate the type of string value, e.g., "date-time" or "email". */ format?: string; /** Intent of the schema. */ title?: string; /** Description of the schema. */ description?: string; /** If the value is an object, the properties in JsonSchema. */ properties?: { [key: string]: JsonSchema; }; /** If the value is an array, the array items in JsonSchema. */ items?: JsonSchema; /** Required properties. */ required?: string[]; /** Reference to object definitions. */ $ref?: string; /** Object definitions. */ $defs?: object; /** Comment string. */ $comment?: string; /** Dialect of JSON Schema. */ $schema?: string; /** Default value. */ default?: any; } type JsonSchemaDataType = "string" | "number" | "integer" | "object" | "array" | "boolean" | "null"; //#endregion //#region build/ActivityResults.d.ts /** * All the data created by an activity. */ interface ActivityResults { /** All the data of the specified data type created thus far by the activity. */ data: ActivityKeyValueData; /** JSON schema describing the structure of the data. */ dataSchema: JsonSchema; /** Type of data. */ dataType: "Trial" | "Scoring" | "Survey"; /** Parameters under which the activity was run. */ activityConfiguration: unknown; /** JSON schema describing the activity parameters. */ activityConfigurationSchema: JsonSchema; /** Metrics describing internal application performance. */ activityMetrics?: Array; } //#endregion //#region build/ActivityLifecycleEvent.d.ts /** * Notifies when an activity starts, ends, cancels, or * creates data. */ interface ActivityLifecycleEvent extends ActivityEvent { results?: ActivityResults; } //#endregion //#region build/ActivityResultsEvent.d.ts /** * Dispatched when new data is created by an activity. * * @remarks Event contains all the data created by an activity, with * separate properties for the newly created data. ActivityResultsEvent * inherits "data" from ActivityResults, which contains the complete data * up to this point (both new and existing data). */ interface ActivityResultsEvent extends ActivityEvent, ActivityResults { /** New data created by the activity, which dispatched this event */ newData: ActivityKeyValueData; /** JSON schema describing the new data */ newDataSchema: JsonSchema; /** ISO 8601 timestamp of the event. Specifically, value of "new Date().toISOString()" executed on the device when the ActivityResultsEvent occurred. */ iso8601Timestamp: string; } //#endregion //#region build/IDataStore.d.ts /** * An interface for persisting data. * * @remarks This interface saves activity results as well as saves and * retrieves arbitrary key-value items that activities can use. * * The underlying persistence provider of the store must * be previously set in the activity's `Session` before use. The * implementation of the store is not provided by the \@m2c2kit/core library. * * @example * ``` * import { LocalDatabase } from "@m2c2kit/db"; * ... * const db: IDataStore = new LocalDatabase(); * session.dataStore = db; * session.initialize(); * ``` */ interface IDataStore { /** Saves activity results in the data store. */ saveActivityResults(ev: ActivityResultsEvent): Promise; /** Sets the value of an item. The key will be saved to the store as provided; * if namespacing or other formatting is desired, it must be done before * calling this method. activityId can be used by the store for indexing. */ setItem(key: string, value: string | number | boolean | object | undefined | null, activityPublishUuid: string): Promise; /** Gets the value of an item by its key. */ getItem(key: string): Promise; /** Deletes an item by its key. */ deleteItem(key: string): Promise; /** Deletes all items. */ clearItemsByActivityPublishUuid(activityPublishUuid: string): Promise; /** Returns keys of all items. */ itemsKeysByActivityPublishUuid(activityPublishUuid: string): Promise; /** Determines if the key exists. */ itemExists(key: string): Promise; } //#endregion //#region build/CallbackOptions.d.ts interface CallbackOptions { /** Should the provided callback replace any existing callbacks of the same event type for this target? Default is false */ replaceExisting?: boolean; /** String identifier used to identify the callback. Only needed if the callback will be removed later */ key?: string; } //#endregion //#region build/Activity.d.ts interface Activity { /** The type of activity: Game or Survey */ type: ActivityType; /** * Initializes the activity. * * @remarks All code to create the activity's appearance and behavior must * be placed in this method. This method is asynchronous, and must be * awaited. When writing a new game by extending the `Game` class, this * method will be overridden, but the base method must still be called with * `await super.initialize()`. */ initialize(): Promise; /** * Initializes the activity. * * @remarks All code to create the activity's appearance and behavior must * be placed in this method. This method is asynchronous, and must be * awaited. When writing a new game by extending the `Game` class, this * method will be overridden, but the base method must still be called with * `await super.init()`. * * @deprecated use Game.initialize() instead. */ init(): Promise; /** Starts the activity */ start(): Promise; /** Stops the activity */ stop(): void; /** * Executes a callback when the activity starts. * * @param callback - function to execute. * @param options - options for the callback. */ onStart(callback: (activityLifecycleEvent: ActivityLifecycleEvent) => void, options?: CallbackOptions): void; /** * Executes a callback when the activity is canceled. * * @param callback - function to execute. * @param options - options for the callback. */ onCancel(callback: (activityLifecycleEvent: ActivityLifecycleEvent) => void, options?: CallbackOptions): void; /** * Executes a callback when the activity ends. * * @param callback - function to execute. * @param options - options for the callback. */ onEnd(callback: (activityLifecycleEvent: ActivityLifecycleEvent) => void, options?: CallbackOptions): void; /** * Executes a callback when the activity generates data. * * @param callback - function to execute. * @param options - options for the callback. */ onData(callback: (activityResultsEvent: ActivityResultsEvent) => void, options?: CallbackOptions): void; /** The activity's parent session unique identifier. This is newly generated each session. */ sessionUuid: string; /** The activity's unique identifier. This is newly generated each session. The UUID for an activity will vary across sessions. */ uuid: string; /** Human-friendly name of this activity */ name: string; /** Short identifier of this activity */ id: string; /** Persistent unique identifier (UUID) of the activity. Required for games. Optional or empty string if a survey. */ publishUuid: string; /** The ID of the study (protocol, experiment, or other aggregate) that contains the repeated administrations of this activity. The ID should be short, url-friendly, human-readable text (no spaces, special characters, or slashes), e.g., `nyc-aging-cohort`. */ studyId?: string; /** Unique identifier (UUID) of the study (protocol, experiment, or other aggregate) that contains the administration of this activity. */ studyUuid?: string; /** The value of performance.now() immediately before the activity begins */ beginTimestamp: number; /** The value of new Date().toISOString() immediately before the activity begins */ beginIso8601Timestamp: string; /** Sets additional activity parameters if defaults are not sufficient. */ setParameters(additionalParameters: unknown): void; /** Additional activity parameters that were set. */ readonly additionalParameters?: unknown; /** Optional stores to use for saving data. The implementation of the store is not provided by the \@m2c2kit/core library. */ dataStores?: IDataStore[]; } //#endregion //#region build/M2NodeEvent.d.ts /** Base interface for all M2Node events. */ //#endregion //#region build/M2Event.d.ts /** * Base interface for all m2c2kit events. * * @remarks I would have named it Event, but that would collide with * the existing DOM Event */ interface M2Event { /** Type of event. */ type: M2EventType | string; /** The object on which the event occurred. If the event has gone through serialization, the string will be the object's UUID (if an `M2Node`) or class name. */ target: T | string; /** Has the event been taken care of by the listener and not be dispatched to other targets? */ handled?: boolean; /** Timestamp of the event, `from performance.now()` */ timestamp: number; /** Timestamp of th event, from `new Date().toISOString()` */ iso8601Timestamp: string; /** Sequence number of event. * @remarks Sequence number is guaranteed to reflect order of events, but * not necessarily contiguous, e.g., could be 1, 2, 5, 10, 11, 24. * */ sequence?: number; } /** * The different events that are dispatched by m2c2kit core. */ declare const M2EventType: { readonly ActivityStart: "ActivityStart"; readonly ActivityEnd: "ActivityEnd"; readonly ActivityCancel: "ActivityCancel"; readonly ActivityData: "ActivityData"; readonly GameWarmupStart: "GameWarmupStart"; readonly GameWarmupEnd: "GameWarmupEnd"; readonly TapDown: "TapDown"; readonly TapUp: "TapUp"; readonly TapUpAny: "TapUpAny"; readonly TapLeave: "TapLeave"; readonly PointerDown: "PointerDown"; readonly PointerUp: "PointerUp"; readonly PointerMove: "PointerMove"; readonly PointerLeave: "PointerLeave"; readonly KeyDown: "KeyDown"; readonly KeyUp: "KeyUp"; readonly Drag: "Drag"; readonly DragStart: "DragStart"; readonly DragEnd: "DragEnd"; readonly Composite: "Composite"; readonly FrameDidSimulatePhysics: "FrameDidSimulatePhysics"; readonly SceneSetup: "SceneSetup"; readonly SceneAppear: "SceneAppear"; readonly ScenePresent: "ScenePresent"; readonly NodeNew: "NodeNew"; readonly NodeAddChild: "NodeAddChild"; readonly NodeRemoveChild: "NodeRemoveChild"; readonly NodePropertyChange: "NodePropertyChange"; readonly DomPointerDown: "DomPointerDown"; readonly BrowserImageDataReady: "BrowserImageDataReady"; readonly I18nDataReadyEvent: "I18nDataReadyEvent"; }; type M2EventType = (typeof M2EventType)[keyof typeof M2EventType]; //#endregion //#region build/M2EventListener.d.ts /** * Base interface for all m2c2kit event listeners. */ //#endregion //#region build/ActivityCallbacks.d.ts interface ActivityCallbacks { /** Callback executed when the activity lifecycle changes, such as when it ends. */ onActivityLifecycle?: (event: ActivityLifecycleEvent) => void; /** Callback executed when an activity creates some data. */ onActivityResults?: (event: ActivityResultsEvent) => void; } //#endregion //#region build/ActivityEventListener.d.ts //#endregion //#region build/SessionEvent.d.ts /** Base interface for all Session events. */ interface SessionEvent extends M2Event { target: Session; } declare const SessionEventType: { readonly SessionInitialize: "SessionInitialize"; readonly SessionStart: "SessionStart"; readonly SessionEnd: "SessionEnd"; readonly SessionData: "SessionData"; }; type SessionEventType = (typeof SessionEventType)[keyof typeof SessionEventType]; //#endregion //#region build/SessionLifecycleEvent.d.ts /** * Notifies when a session starts, ends, or initializes. */ interface SessionLifecycleEvent extends SessionEvent {} //#endregion //#region build/SessionCallbacks.d.ts interface SessionCallbacks { /** Callback executed when the session lifecycle changes, such as when it is initialized. */ onSessionLifecycle?: (event: SessionLifecycleEvent) => void; } //#endregion //#region build/SessionOptions.d.ts interface SessionOptions { /** The activities that compose this session */ activities: Array; /** Callbacks executed when activity events occurs, such as when activity creates data or ends */ activityCallbacks?: ActivityCallbacks; /** Callbacks executed when session events occur */ sessionCallbacks?: SessionCallbacks; /** Use a specified session UUID, rather than create a new one */ sessionUuid?: string; /** URL of session assets folder (which contains wasm binary), if not the default location of "assets" */ assetsUrl?: string; /** Array of one or more optional databases that implement the IDataStore interface for persisting data. For store item operations, the first data store will be used. */ dataStores?: IDataStore[]; /** The ID of the study (protocol, experiment, or other aggregate) that contains the repeated administrations of these sessions. The ID should be short, url-friendly, human-readable text (no spaces, special characters, or slashes), e.g., `nyc-aging-cohort.` */ studyId?: string; /** The unique identifier (UUID) of the study (protocol, experiment, or other aggregate) that contains the administration of this session. */ studyUuid?: string; /** After the session initializes, should the session automatically start? Default is true */ autoStartAfterInit?: boolean; /** When an activity ends or is canceled, should the session automatically go to the next activity? Default is true */ autoGoToNextActivity?: boolean; /** After the last activity ends or is canceled, should the session automatically end? Default is true */ autoEndAfterLastActivity?: boolean; /** The id of the HTML element to use as the root element where m2c2kit activities will be rendered. Default is "m2c2kit". */ rootElementId?: string; /** Optional style sheet (CSS) to apply to the document instead of the default m2c2kit CSS. It is recommended to use the default CSS. */ styleSheet?: string; /** Should the session implement diagnostics that capture error events, show the user an error dialog, and stop the session if an m2c2kit error occurs? Default is false. @remarks URL params will override this setting. */ diagnostics?: boolean; /** NOT IMPLEMENTED YET: Orientation the screen should be locked to for this session. Value will be passed into the ScreenOrientation.lock() Web API. */ orientation?: "natural" | "landscape" | "portrait" | "portrait-primary" | "portrait-secondary" | "landscape-primary" | "landscape-secondary"; } //#endregion //#region build/SessionData.d.ts /** Data from session are stored as key (string) value pairs. */ interface SessionKeyValueData { [key: string]: string | number | boolean | object | undefined | null; } //#endregion //#region build/SessionDataEvent.d.ts /** * Data generated by the session. */ interface SessionDataEvent extends SessionEvent { /** Data generated by the session. */ data: SessionKeyValueData; /** Type of data. */ dataType: "Diagnostics"; } //#endregion //#region build/Session.d.ts declare class Session { options: SessionOptions; currentActivity?: Activity; private _uuid?; dataStores?: IDataStore[]; private eventListeners; private sessionDictionary; private initialized; private diagnosticsReporter?; /** * A Session contains one or more activities. The session manages the start * and stop of activities, and advancement to next activity * * @param options */ constructor(options: SessionOptions); /** * Adds debugging tools to the session. * * @remarks These tools can be activated by appending query parameters to the * URL or by setting game parameters via the `Game.SetParameters()` method * (only eruda and scripts can be set with `Game.SetParameters()`). */ private addDebuggingTools; /** * Starts the diagnostics reporter. */ private startDiagnostics; /** * Executes a callback when the session initializes. * * @param callback - function to execute. * @param options - options for the callback. */ onInitialize(callback: (sessionLifecycleEvent: SessionLifecycleEvent) => void, options?: CallbackOptions): void; /** * Executes a callback when the session starts. * * @param callback - function to execute. * @param options - options for the callback. */ onStart(callback: (sessionLifecycleEvent: SessionLifecycleEvent) => void, options?: CallbackOptions): void; /** * Executes a callback when the session ends. * * @param callback - function to execute. * @param options - options for the callback. */ onEnd(callback: (sessionLifecycleEvent: SessionLifecycleEvent) => void, options?: CallbackOptions): void; /** * Executes a callback when the session generates data. * * @remarks Currently, this is used only for capturing diagnostics data on * exceptions. * * @param callback - function to execute. * @param options - options for the callback. */ onData(callback: (sessionDataEvent: SessionDataEvent) => void, options?: CallbackOptions): void; /** * Executes a callback when any activity in the session generates data. * * @param callback - function to execute. * @param options - options for the callback. */ onActivityData(callback: (activityResultsEvent: ActivityResultsEvent) => void, options?: CallbackOptions): void; private addEventListener; private raiseEventOnListeners; private eventIsSessionDataEventMissingTarget; private sessionActivityStartHandler; private sessionActivityCancelHandler; private sessionActivityEndHandler; private sessionActivityLifecycleHandler; private activityResultsEventHandler; /** * Asynchronously initializes the m2c2kit engine and loads assets * * @deprecated Use Session.initialize() instead. */ init(): Promise; /** * Check if the Activity uses the deprecated init() method. * * @remarks Activity.init() is deprecated and should be replaced with * Activity.initialize(). * * @param activity * @returns true if the activity defines its own init() method, false otherwise. */ private activityUsesDeprecatedInit; /** * Asynchronously initializes the m2c2kit engine and loads assets */ initialize(): Promise; /** * Asynchronously loads fonts and wasm binaries that are common across two * or more game activities and shares them with the games. * * @param activities - array of activities */ private getSharedAssets; private initializeSharedCanvasKit; private fetchSharedFontData; /** * Waits for the session to be initialized. * * @remarks Session.initialize() is asynchronous, and it should be awaited * so that the session is fully initialized before calling Session.start(). * If it is not awaited (or it cannot be awaited because the target * environment does not support top-level await), this function ensures that * the session has been initialized. */ private waitForSessionInitialization; /** * Starts the session and starts the first activity. */ start(): Promise; /** * Declares the session ended and sends callback. */ end(): void; private stop; /** * Frees up resources that were allocated to run the session. * * @remarks This will be done automatically by the m2c2kit library; * the end-user must not call this. */ private dispose; /** * Stops the current activity and goes to the activity with the provided id. * * @param options */ goToActivity(options: GoToActivityOptions): Promise; /** * Stops the current activity and advances to next activity in the session. * If there is no activity after the current activity, throws error. */ goToNextActivity(): Promise; /** * Stops the current activity and advances to next activity in the session. * If there is no activity after the current activity, throws error. * * @deprecated Use goToNextActivity() instead. */ advanceToNextActivity(): Promise; /** * Gets the next activity after the current one, or undefined if * this is the last activity. */ get nextActivity(): Activity | undefined; /** * Saves an item to the session's key-value dictionary. * * @remarks The session dictionary is not persisted. It is available only * during the actively running session. It is useful for storing temporary * data to coordinate between activities. * * @param key - item key * @param value - item value */ dictionarySetItem(key: string, value: SessionDictionaryValues): void; /** * Gets an item value from the session's key-value dictionary. * * @remarks The session dictionary is not persisted. It is available only * during the actively running session. It is useful for storing temporary * data to coordinate between activities. * * @param key - item key * @returns value of the item */ dictionaryGetItem(key: string): T; /** * Deletes an item value from the session's key-value dictionary. * * @remarks The session dictionary is not persisted. It is available only * during the actively running session. It is useful for storing temporary * data to coordinate between activities. * * @param key - item key * @returns true if the item was deleted, false if it did not exist */ dictionaryDeleteItem(key: string): boolean; /** * Determines if a key exists in the activity's key-value dictionary. * * @remarks The session dictionary is not persisted. It is available only * during the actively running session. It is useful for storing temporary * data to coordinate between activities. * * @param key - item key * @returns true if the key exists, false otherwise */ dictionaryItemExists(key: string): boolean; /** * Returns the filename from a url. * * @param url - url to parse * @returns filename */ private getFilenameFromUrl; /** * Returns the duplicated strings in an array. * * @param s - array of strings * @returns array of duplicated strings */ private getDuplicates; get uuid(): string; set uuid(value: string); /** * Sets the value of a variable that will be the same for all diagnostic data. * * @remarks This is useful for custom variables to appear in the diagnostic * data. For example, you might save the subject's participant ID, or some * other identifier that is not typically part of the diagnostic data. In * the example below, if an exception occurs, the `participant_id` variable * will be saved with the value `12345` within the diagnostic data. * * @example * ``` * session.addStaticDiagnosticData("participant_id", "12345"); *``` * @param key - key (variable name) for the static diagnostic data * @param value - value for the data */ addStaticDiagnosticData(key: string, value: string | number | boolean | object | undefined | null): void; } interface GoToActivityOptions { /** ActivityId of the activity to go to. */ id: string; } /** * Types of values that can be stored in the session dictionary. */ type SessionDictionaryValues = string | number | boolean | object | null | undefined; //#endregion //#region build/DomHelper.d.ts declare class DomHelper { /** * Specifies the HTML element in which to render the m2c2kit activities. * * @param rootElement - the element to add the survey div and canvas div to */ static createRoot(rootElement: HTMLElement): void; /** * Adds a style sheet to the head of the document. * * @param css - text of the CSS */ static addStyleSheet(css: string): void; /** * Add elements to hide the canvas and show a spinner. */ static addLoadingElements(): void; /** * Depending on the type of activity, set the visibility of the survey div * and canvas div. * * @param activity - the activity to configure the DOM for */ static configureDomForActivity(activity: Activity): void; /** * Hide the canvas div and survey div. */ static hideM2c2Elements(): void; /** * Shows or hides the canvas overlay. * * @param visible - true if the canvas overlay should be visible */ static setCanvasOverlayVisibility(visible: boolean): void; /** * Shows or hides the busy animation. * * @param visible - true if the busy animation should be visible */ static setBusyAnimationVisibility(visible: boolean): void; /** * Shows or hides the survey div. * * @param visible - true if the survey div should be visible */ private static setSurveyDivVisibility; /** * Shows or hides the canvas div. * * @param visible - true if the canvas div should be visible */ private static setCanvasDivVisibility; } //#endregion export { DomHelper, GoToActivityOptions, Session, SessionDictionaryValues, SessionEvent, SessionEventType, SessionLifecycleEvent, SessionOptions }; //# sourceMappingURL=index.d.ts.map