- Print
Listening for Events
- Print
Known Defect in Firebolt® SDK v1.3.0 & v1.4.0
Events are a common pattern for asynchronous notifications from an SDK.
Firebolt® provides three methods for interacting with Firebolt® events:
listen
once
clear
Listening for Events
In order to listen for an event, you need to know which Firebolt® module it is part of.
For example, the foreground
event is part of the Firebolt® Lifecycle
module.
Once you've identified which module, there are two ways to listen:
listen for every event in the module.
listen for a specific event in the module.
Listening for a specific event
To listen to just the foreground
event, you'd use the listen
method that is part of the Lifecycle
module:
Lifecycle.listen('foreground', () => { })
The first parameter is the name of the event you are listening for. The second parameter is a callback function that the X1 Platform will call to inform you that this event has occurred.
Ideally your callback would be more interesting than the example above. Generally the callback will take the event's payload object, which has important context about each instance of an event, and do something with it.
To make this slightly more interesting:
Lifecycle.listen('foreground', (value) => {
if (value.previous === 'inactive') {
console.log('Our app has transitioned from inactive to foreground!')
}
})
Listening for all events in a Module
To listen to all events in a module, say the Lifecycle
module, you'd use the listen method with only one parameter, the callback:
Lifecycle.listen((event, value) => {
console.log(event) // this will be the string representation of the lifecycle state we just entered
if (value.previous === 'inactive') {
console.log('Our app has transitioned from inactive to foreground!')
}
})
Note that in this case, your callback method must take two parameters: the name of the event being received and the payload value of the event.
Listening for an event just once
Sometimes your App only wants to be notified of the very next instance of an event.
In this case, use the once
method, which as the same signature as listen
:
Lifecycle.once('foreground', (value) => {
if (value.previous === 'inactive') {
console.log('Our app has transitioned from inactive to foreground!')
}
})
Lifecycle.once((event, value) => {
console.log(event) // this will be the string representation of the lifecycle state we just entered
if (value.previous === 'inactive') {
console.log('Our app has transitioned from inactive to foreground!')
}
})
Each of those once
calls results in zero or one calls to your callback, when a matching event occurs. Future events will not be sent to those callbacks.
Clearing listeners
Modules that have the listen
method also have a clear
method. This allows you to clear out all of the listeners for the entire module, or just a single listener.
Clearing a single listener
In order to clear a single listener, your app needs to keep track of the listener ID for the initiating listen
call.
The listen
method returns a Promise that resolves to an integer for this purpose:
// let's log "Hello World!" whenever our app moves into the foreground
const helloListenerId = await Lifecycle.listen('foreground', () => { console.log("Hello World!")})
// but let's stop doing that when our app is unloading
Lifecycle.listen('unloading', () => {
Lifecycle.clear(helloListenerId)
})
Clearing all listeners in a module
In order to clear all of the listeners added a specific module, simply call clear()
with no parameters:
Lifecycle.clear()