The app has a list of "integrations" which serves different purposes, eg. push notifications or calendar. Each method in the respective integrations can be called directly on the integrations using dot annotation.
To retrieve the result of a method call you'll need a JavaScript method named the same as the method name + Result. The method must be placed in a scope which matches the scope of the called method minus Integration.
Let's take an example:
If the following method is called from the website: PushNotificationIntegration.getLastPublishedToken();
the result of the method call will be returned through a call to PushNotification.getLastPublishedTokenResult. So the following must be defined in the website:
var PushNotification = {
getLastPublishedTokenResult(token) {
console.log('Push notification token received by request: ' + token);
}
}
The above method will be specified like this:
getLastPublishedToken(): string
The specification will also indicate the return type of the method even though there in practice won't be returned a values from the method. Instead the return value will be given as a parameter for the corresponding Result method.
Events, called from the app, has no return value as those are calls from the app to the website and the website isn't supposed to return anything back to the app.
Example:
var PushNotification = {
notificationReceivedEvent(arguments) {
console.log('Push notification received: ' + JSON.stringify(arguments));
}
}
There are two scopeless events in the system. Those doesn't belong to an integration but are system events.
appIntegrationsAreReady()
This event is fired when all integrations in the app are loaded correctly and the integrations are ready to be called. The website shouldn't call webAppIsReady() (see below) before this event has been fired.
In normal circumstances it shouldn't be necessary to listen for this event as the app should be loaded and ready a lot faster than the website, which has to be loaded from an external server. But if the call to webAppIsReady() fails it's probably because the app has completed its initialization process yet.
appErrorEvent(error): { message: string: AdditionalDetails: string }
If an error occurs in the app in relation to a call from the website to the app, the exception will be caught and transferred to the website through this event.
Integration name: AppIntegration
This integration is used to handle some basic calls to the app.
webAppIsReady(): void
The website is expected to call this method as soon as it's ready to handle events from the app. When this method has been called the app knows, the website has been initialized and is ready to handle events.
setAppUrl(url: string): bool
Use this method to control which URL the app load when it is initialized. The method returns true when the URL has been changed.
resetAppUrl(): void
Call this method to reset the startup URL of the app. After calling this method the app will load the URL it was "born" with after a restart. Please notice that this URL can be different between the test and production environment.
version(): string
Returns the version number of the app (eg. 1.0.0).
restartApp(): void
Calling this method will reload the startup URL. Use this method if there's not internet and the user want's to try reloading the website again.
appInForegroundEventRecieved()
The event will be called whenever the app enters the foreground on the device and when the app starts og thus also enters the foreground on the device.
Integration name: PushNotificationIntegration
initialize(): bool
This method should be called when the user want's to receive push notifications. When calling this method the result is a bit different on the two platforms. On iOS the user will be asked if it's okay to receive push notifications. On Android nothing happens in the user interface.
The method returns true when the call has been completed.
getLastPublishedToken(): string
This method returns the token which should be used to send push notifications.
tokenReceivedEvent(token: string)
Called with the token used to send push notifications to the current device.
notificationReceivedEvent(notification: any)
Called with the notification that has been received by the mobile. The content of notification is the content that has been sent from the backend. There will also be a special property called appWasLaunchedFromNotification which indicated wether the app entered the foreground because a notification as pressed on the device or wether the app already was in the foreground when the notification was received.
Integration name: CalendarIntegration
When an event is added through the app a key pair will be saved on the device. The key pair contains the EventId and the corresponding SyncId.
This way the app will always be able to find the SyncId for a saved event (unless the app has been deleted from the device).
If the device is running Android 6.0+ (API 23) that it set to "Auto Backup" the data will stay on the phone. Auto Backup can be disabled by following this guide: https://developer.android.com/guide/topics/data/autobackup
isAccessGranted(): bool
Returns a boolean indicating wether there are access to the calendar on the device.
requestAccess(): bool
Asks the user about permission to access the calendar. Returns a boolean indicating wether the call completed successfully or not. So the value returned can't be used to decide if there are access to the calendar. Here a following call to isAccessGranted() is necessary.
listCalendars(): { id: string, name: string }[]
Returns a list of available calendars on the phone. For each calendar an id and a name is returned.
addEvent(calendarId: string, name: string, description: string, syncId: string, startDateTime: Date, endDateTime: Date): {result: bool, syncId: string, error: string}
Adds an event to the calendar with the given calendarId and syncId. Returns an object where the result property indicates success or failure to add the event. syncId matches the given syncId and error will contain an error message if result is false.
deleteEvent(eventId: string): {result: bool, eventId: string, error: string}
Deletes the event with the given eventId. Returns an object containing the same properties as the addEvent method.
listEvents(calendarId: string, from: Date, to: Date): { calendarId: string, eventId: string, title: string, description: string, syncId: string, startDate: Date, endDate: Date }[]
Returns a list of event within the given time span defined in the two parameters from and to from the given calendar.
Integration name: QrScannerIntegration
isCameraAccessGranted(): bool
Returns a boolean indicating where access to the camera has been granted.
requestCameraAccess(): bool
Asks the user about access to the camera on the device. Returns a boolean indicating wether the call completed successfully or not. So the value can't be used to determine if there are access to the camera. Here a following call to IsCameraAccessGranted() is necessary.
startQrCodeScanner()
Opens the camera on the phone og starts scanning after QR codes. When the camera has scanned a QR code the camera will be closed the user will be back on the website.
publishQrResultEvent(message: string)
When a QR code is scanned this event will be raised containing the value from the QR code.
Integration name: NfcIntegration
NFC isn't available on all kinds of devices. Especially the cheap Android phones does't have af NFC reader. So always call isNfcSupported() to make sure the phone has a compatible NFC tag reader.
The app doesn't have access to ask the user for permission to scan NFC tags. Instead a call to isNfcEnabled() is necessary to determine wether the app has permission to read NFC tags.
Reading NFC tags has it limitations. Here are the list of supported NFC tags: NDEF, MIFARE (only Android), ISO/IEC 14443, ISO/IEC 15693, ISO/IEC 7816 (only Android) & FeliCa.
isNfcSupported(): bool
Returns a boolean indicating wether scanning of NFC tags is supported by the device.
isNfcEnabled(): bool
Returns a boolean indicating wether scanning of NFC tags is enabled on the device. If it isn't enabled no API exists to ask the user. The user has to go to the settings on the device and enable the NFC functionality.
initialize(): {result: bool, error: string}
Initializes the NFC service and starts scanning after NFC tags.
Returns an object containing a result set to true if the scanning completed successfully. If it didn't complete successfully result will be set to false and error will contain the corresponding error message.
stopListening(): bool
Stops the NFC scanner. Returns true on success and false if it fails.
NfcTagResultReceivedEvent(message): {result: bool, error: string, nfcTagInfo: string}
When a NFC tag is scanned, this event will be raised. In cases where the NFC tag contains no content or isn't supported result will be falseand error will contain the corresponding error message.
If the NFC tag is read successfully result will be true and nfcTagInfo will contain the content read from the NFC tag.