Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

JavaScript APIs for offline-enabled mobile apps

Updated on June 24, 2022

Pega Platform provides a set of JavaScript methods that you can call to deliver a smooth run-time experience for the users of your offline-enabled mobile app.

Consult the following article to learn more about how you can configure data synchronization and data storage in your app. You can then include the methods that you choose in your app by adding the corresponding JavaScript code to your application.

Data storage JavaScript APIs

You can configure how the app stores and manages data in the client store database by calling several JavaScript methods.

For example, you might want to calculate the statistics for all currently stored items or delete a selected item. For a list of available JavaScript methods, see Client Store API for Pega Infinity Mobile Client.

Data synchronization JavaScript APIs

You can configure data synchronization frequency, data synchronization throttling, and the behavior of the synchronization indicator, by calling several JavaScript methods.

Synchronization trigger

You might want to initiate the synchronization, for example, to pass case processing results to the server. The following JavaScript API triggers immediate data synchronization.
window.datasyncStart()
Initiates data synchronization when the user interacts with the control that you configure to invoke the Run script action. When the datasyncStart method is called, the synchronization indicator immediately displays the Syncing/Synced message.
pega.offline.DataSync.start
Initiates data synchronization when called from the custom JavaScript code that defines the logic of your application. When the start method is called, the synchronization indicator does not display the Syncing/Synced message, unless there has been a noticeable delay.

Synchronization frequency

You might want to decrease the default synchronization frequency, for example, to limit battery consumption and network usage. Alternatively, you might want to increase the frequency, for example, to ensure that users always have the most recent data, despite an intermittent network connection. The following JavaScript API delays synchronization for a specified time.
pega.offline.DataSync.setIntervalBetweenSynchronizationsWhenServerAccessible
Sets the interval (in milliseconds) between subsequent synchronization sessions when the server is available. The default value is 300000 ms (5 minutes). The value must be greater than 0.
pega.offline.DataSync.setIntervalBetweenSynchronizationsWhenServerInaccessible
Sets the interval (in milliseconds) between subsequent synchronization sessions when the server is not available. The default value is 60000 ms (1 minute). The value must be greater than 0.

Synchronization throttling

You might want to introduce synchronization throttling, for example, to decrease server load or to limit battery consumption and network usage. The following JavaScript API controls throttling and delays synchronization until a certain number of actions are in the action queue.
pega.offline.DataSync.setQueueMaxSize
Sets the number of actions in the action queue that must be reached before synchronization is triggered. The default value is 1, which means that the app sends actions immediately to the server after they are added to the action queue.
pega.offline.DataSync.setQueueFlushInterval
Sets the amount of time (in milliseconds) that must pass from the moment an action is queued in the client store before synchronization is triggered. The default value is 0, which means synchronization happens immediately.
pega.offline.DataSync.enableFlushOnLastStep
Enables or disables synchronization triggering after the user processes the last step in an assignment. The default value is false.
pega.offline.DataSync.isFlushOnLastStepEnabled
Specifies whether synchronization triggering is enabled after the user processes the last step in an assignment.
When a network connection is not available for a long period of time and a large number of user actions accumulate for synchronization, you might want to decrease server load to ensure that the oldest user actions get synchronized. The following JavaScript API splits a synchronization session into parts.
pega.offline.DataSync.setMaxNumberOfActionsPerRequest
Sets the maximum number of actions that can be sent with a single request. The default value is 60, which means that the app sends up to 60 actions in each synchronization request. When you set the value to -1, you remove the limit, which means that a synchronization request can include an infinite number of actions.

Synchronization indicator appearance

For usability or customization reasons, you might want to modify how the synchronization indicator is displayed. The following JavaScript API controls the appearance of the synchronization status indicator.
Note: Use the following JavaScript API controls for UI-Kit 14 and earlier versions. For UI-Kit 15 and Pega Cosmos design system, modify how you display the synchronization indicator by configuring corresponding dynamic system settings. For more information, see Configuring time-outs for synchronization indicators.
pega.offline.Indicator.setDeferDurationTime
Sets the time (in milliseconds) that must pass from the start of the synchronization session before the Syncing/Synced label appears on the screen. By default, it is set to 4000 ms (4 seconds). The value must be greater than 0.
pega.offline.Indicator.setHideSyncedAfterTime
Sets the time (in milliseconds) that must pass from the end of the synchronization session before the Synced label disappears from the screen. The default value is 5000 ms (5 seconds). The value must be greater than 0.

Synchronization listener

You can add an event listener that the system calls when the app starts synchronizing data or when the synchronization status changes, for example, to calculate how much time has elapsed from the last synchronization.
pega.offline.DataSync.addListener
Returns true after the listener is registered. Returns false when an error occurs and adding the listener fails.

The data synchronization listener has the following callbacks:

onStart(cause)
Required. Called when data synchronization starts.

The callback receives cause as an argument that reflects what triggered the synchronization:

  • pega.offline.DataSync.START_CAUSE_TYPICAL = 0 when a user performs an action that triggers the synchronization, or in case of an automatically recurring synchronization.
  • pega.offline.DataSync.START_CAUSE_MANUAL = 1 when a user manually triggers the synchronization.
  • pega.offline.DataSync.START_CAUSE_NETWORK_BECAME_AVAILABLE = 2 when the app detects network availability and consequently triggers a synchronization.
  • pega.offline.DataSync.START_CAUSE_APPLICATION_BECAME_VISIBLE = 3 when the user brings the app to the foreground or turns on the screen, and consequently triggers a synchronization.
onStatusUpdate(status)
Required. Called when the synchronization status changes.

The callback receives status as a JSON object that reflects the current synchronization status through the following keys and corresponding values:

  • isEvent = true when the app updates the synchronization status, otherwise isEvent = false
  • isBusy = true when synchronization is in progress, otherwise isBusy = false
  • isError = true when an error occurs, otherwise isError = false
    Tip: For more information about the types of errors in offline-enabled mobile apps, see PEGA0066 alert: Mobile App Data-Sync Failure.
  • isNetworkError = true when the error is network-related, otherwise isNetworkError = false
    Note: Network errors are common in real-life scenarios and are fully recoverable after the network is available again.
  • event defines the event that triggered the synchronization status update by taking a corresponding value (STARTED, STOPPED, SUCCEEDED, or FAILED), for example, window.pms.ClientStore.Event.STARTED.
onOnlineDetected
Optional. Called when the app detects the server as accessible.
  • Previous topic Extending mobile apps with JavaScript APIs
  • Next topic Adding JavaScript code to Pega Platform applications

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us