Applying Sync Rules
The Akula synchronization mechanism lets you synchronize changes to the data on a client device with a back end data source. If the client modifies data, the synchronization mechanism can upload those changes to the back end. In response to the upload, the Akula Server returns to the client any updates to the back end data since the client performed the last synchronization.
For more information on sync, see Synchronizing Client Data with the Akula Server.
In an environment where you have many clients, you might want to restrict when the client can perform a sync. For example, you might prevent sync during times of heavy network usage. Or, because a sync can potentially require a large amount of data to be sent from or to the device, you might restrict sync to only be allowed when the device has a WiFi connection.
Sync rules let you block a client app from performing a sync operation under the following conditions:
- Battery charge level
- Type of network connection
- Time of day
This document describes the sync rules and contains the following sections:
Handling a blocked sync request
When you initiate a sync on Android or iOS, you pass an object to the sync method that defines callback methods to handle sync success and failure. If the sync is blocked by a client rule for any reason, the sync fails and calls the
onFailure() method (Android) or
onFailure: method (iOS) of the callback object. The failure callback method receives the
ErrorCode.SYNC_BLOCKED error code indicating that the error was caused by a blocked sync request.
failure_callback function of the promise object. The failure callback's argument specifies the reason for the failure.
For examples of performing a sync for all Akula clients, including handling sync failures, see Syncing on the Client.
Types of sync rule templates
Akula provides several rule templates that let you specify conditions on a sync rule, including the following:
|Block sync based on the battery level.|
|Block sync if the device is not on a WiFi network.|
|Block sync between a start time and an end time.|
Akula rule templates are available on all supported client SDKs, with the following exceptions:
Notice that each rule template takes a property named
entities, and zero or more additional properties that you use to configure a client rule.
Setting properties of a sync rule
Create a sync rule by setting properties on a sync rule template. The following table lists all of the properties of the sync rules:
A comma-separated list of entities blocked from syncing.
In native client apps, entities are defined by a class that implements the AKModel interface (Android) or AKModel protocol (iOS). Therefore, this value is the name of the model class.
The default value is '*', corresponding to all syncable entities.
The minimum battery charge percentage required for sync, as an integer between 0 and 100. If the battery percentage is below this value, then sync is blocked.
The default value is 10, meaning sync is blocked for a battery charge level less than 10%.
The time to start blocking sync, in the format:
The default value is null; you must set this property.
The comparison for start time is inclusive, meaning a time equal to or later than the start time is blocked.
The time to stop blocking sync, in the format:
The default value is null; you must set this property.
The comparison for end time is inclusive, meaning a time equal to or earlier than the end time is blocked.
Setting the entities property
All sync rule templates take a property named
entities that specifies the entities to block from syncing. The default value of the
entities property is '*', corresponding to all syncable entities.
On native clients, syncable entities are defined by a class that implements the AKModel interface (Android) or AKModel protocol (iOS). To simplify the process of syncing data, Akula provides a simple concrete implementation of AKModel called AKBasicModel, which you can extend, rather than implementing AKModel on your own.
The following Android example defines a syncable class named Customer as a subclass of AKBasicModel :
The following iOS example defines a syncable class named Customer as a subclass of AKBasicModel :
For all of the examples above, specify "Customer" as the value of the
entities property, as shown below in the following Akula Command-line.
For more information on using the Akula Command-line to define client rules, see Client Rules Overview.
Sync rule examples
Create a rule based on the Akula_BlockSyncOnBatteryChange rule template with the following properties to block syncing if the battery is below 50%:
Create a rule based on the Akula_BlockSyncOnCellNetwork rule template with the following properties to block syncing unless the device is connected to a WiFi network:
Create a rule based on the Akula_BlockSyncDuringTimeRange rule template with the following properties to block syncing from 9:00 AM to 5:00 PM, where the time is the local time of the device:
You can create multiple sync rules. For example, create two rules that block sync from 10:00 PM until 2:00 AM and again from 3:00 PM to 5:00 PM, as shown below:
Create multiple sync rules that block sync from 10:00 PM until 2:00 AM and block syncing unless the device is connected to a WiFi network:
Determining sync blocking state
The Akula clients provide APIs that you can use to determine if sync is blocked:
- Android - the
AKPersistenceManager.isSyncBlocked()method returns true if sync is blocked. For example:
- iOS - the
isSyncBlocked:method of the AKPersistenceManager class returns YES if sync is blocked. For example:
AK.PersistenceManager.isSyncBlocked()method returns true if sync is blocked. For example:
Handling sync rule events on the client
All sync rules dispatch an event on the client when the sync becomes blocked or becomes unblocked:
- In an Android client app, define a class that implements the AKSyncBlockedListener interface to handle the event.
- In iOS, add separate handlers for the events named by the AKPersistenceManagerDidBlockSyncNotification and
AKPersistenceManagerDidUnblockSyncNotification constants defined in AKConstants.
These events are dispatched when a client rule causes sync to become blocked or unblocked. They are not dispatched when the client attempts to perform a sync and sync is blocked.
If the sync is blocked by a client rule for any reason, the sync fails and calls the
For more information on handling these events, see Client Rules Overview.
Handling sync rule events in an Android app
To handle a rule event in an Android app, define a class that implements the AKSyncBlockedListener interface, as shown below:
The AKSyncBlockedListener interface defines a single method, named
handle(), that you must implement. This method is called when sync becomes blocked (
true), and when sync becomes unblocked (
Handling sync rule events in an iOS app
In an iOS app, the event handler for a sync blocked and sync unblocked event receives an NSNotification object that contains three fields:
name- The event name.
object- The object associated with the event.
userInfo- An NSDictionary object containing information about the event. For the sync events, the
userInfoobject contains the name of the blocked or unblocked sync entities in the
To handle a rule event on an iOS client, define a handler method for when sync becomes blocked and a separate handler function for when sync becomes unblocked. For example, define the methods as shown below:
In this example, you attach an event handler for the