1,007
edits
Labs/Test Pilot/ExperimentAPI: Difference between revisions
→handlers
| Line 263: | Line 263: | ||
'''handlers''' must define the following functions, named exactly as they appear here. Each function is called by the extension when the appropriate event occurs. Exactly what your handlers do in response to these events is up to you. | '''handlers''' must define the following functions, named exactly as they appear here. Each function is called by the extension when the appropriate event occurs. Exactly what your handlers do in response to these events is up to you. | ||
* onNewWindow(window) | * onNewWindow(window): Called when a new window is opened, with a reference to the window object. | ||
* onWindowClosed(window) | * onWindowClosed(window): Called when a window is closed, with a reference to the window object. | ||
* onAppStartup() | * onAppStartup(): Called when Firefox starts up. | ||
* onAppShutdown() | * onAppShutdown(): Called when Firefox shuts down. | ||
* onExperimentStartup(store) | * onExperimentStartup(store): Called when your experiment is starting up, with a reference to the data store object. | ||
* onExperimentShutdown() | * onExperimentShutdown(): Called when your experiment is to be shut down. | ||
* doExperimentCleanup() | * doExperimentCleanup(): Called when your experiment is completed or canceled by the user and will not be run anymore. | ||
* onEnterPrivateBrowsing() | * onEnterPrivateBrowsing(): Called when the user enters Private Browsing Mode. | ||
* onExitPrivateBrowsing() | * onExitPrivateBrowsing(): Called when the user exits Private Browsing Mode. | ||
To respect the user's privacy, your handlers should not record any data while the user is in Private Browsing Mode. | |||
"Experiment Startup" is called when your experiment has just started running for the first time. It's also called when the user starts up Firefox again after exiting, in which case your study will need to resume running. In the latter case, your onExperimentStartup() method will be called immediately followed by the onAppStartup() method. | |||
Most experiments will do the majority of their work (registering listeners on various UI elements) in the onExperimentStartup() method or the onNewWindow() method, depending on whether the observation is global or per-window. | |||
In your onExperimentStartup() method, you should save a reference to the data store object since you will need to use its storeEvent() method to store data. | |||
The file '''study_base_classes.js''' defines a class called GenericGlobalObserver that defines appropriate responses to each of these events. It also defines a GenericWindowObserver helper class for installing per-window observers, which is a very common use case. I strongly recommend extending GenericGlobalObserver, overriding methods you want to customize, and then setting '''exports.handlers''' to a new instance of your subclass. This is explained in more detail in the [[/Labs/Test_Pilot/Experiment_Tutorial Experiment Tutorial]]. | The file '''study_base_classes.js''' defines a class called GenericGlobalObserver that defines appropriate responses to each of these events. It also defines a GenericWindowObserver helper class for installing per-window observers, which is a very common use case. I strongly recommend extending GenericGlobalObserver, overriding methods you want to customize, and then setting '''exports.handlers''' to a new instance of your subclass. This is explained in more detail in the [[/Labs/Test_Pilot/Experiment_Tutorial Experiment Tutorial]]. | ||