The Cordova sync sample app demonstrates best practices when using Akula's synchronization mechanism.

As the Akula sync feature builds on top of the persistent data feature, this app builds on the encryption sample app, which is the recommended entry point for these features.

To use the sync sample app, you must:

1. Deploy one or both of the sample app scopes to your Akula Server.
2. Configure Cordova to use the Akula libraries.
3. Modify the sync sample to point to your Akula server.

This document contains the following sections:

Get the sample

The source code for the Sync app, both client and server, is available in the Verivo_Akula_SDK_v3.0.0.zip file. Ensure that you have already installed Akula. If you have not installed Akula, contact us for more information.

Viewing the client app source code

The source code for the iOS sync client app is located in the cordova-sdk/samples/sync directory in the location where you installed Akula. The steps below include information about editing the source code before you run the sample app.

Viewing the server app source code

There are two server app scopes for the sync sample app:

• Custom Sync – The Uses a custom module to process synchronization requests.
• Route Sync – Uses the built-in Route Sync module to process synchronization requests.

The source code for the Custom Sync app scope is located in the server-sdk/samples/projects/customsync directory in the location where you installed Akula. This directory includes the source code for the Akula app scope and for the custom sync module used by the app scope. While you do not have to modify the server app scope to run the sync sample app, you can use it as a reference for building your own sync module.

The source code for the Route Sync app scope is located in the  server-sdk/samples/projects/routesync  directory in the location where you installed Akula.

Deploy the Akula sync app scopes

Two Akula server app scopes are available to use with the sync client app. You can use one or both of them. For each one you want to use, deploy the corresponding AKZ file to your server. They must be deployed one at a time. The files are:

• customsync.akz (for Custom Sync)
• routesync.akz (for Route Sync)

The customsync.akz file is available in the server-sdk/samples/projects/sync/target directory in the location where you installed Akula. The routesync.akz file must first be built using the source code. 

Deploy the Custom Sync app scope 

To deploy the Akula Custom Sync app scope:

1. Stop the Akula Server.
2. Locate the server-sdk/samples/projects/customsync/target directory in the location where you installed Akula.
3. Copy the customsync.akz file to the AKULA_HOME/deploy directory.
4. Restart the Akula Server.

Build and deploy the Route Sync app scope

Before you can use the Route Sync app scope (routesync.akz), you must download and build it. This process requires that you have Apache Ant installed.

To download, build, and deploy the Route Sync app scope:

1. Stop the Akula Server.
2. Navigate to the server-sdk/samples/projects/routesync directory. This is the directory that has the build.xml file.
3. Execute the following command:
   
   ant install
   
   The included Ant script packages the app scope as an AKZ file and deploys the routesync.akz file to the AKULA_HOME/deploy directory.
4. Restart your Akula Server.

For more information about the route sync project, see the README.txt file in the download.

Set up the sync sample project

This section describes how to set up the sync sample projects for the Android Cordova and iOS Cordova platforms.

Note Before you can set up the sync sample project, you must set up your client environment to use Cordova, and install the Akula core and Akula SQLCipher. For more information, see Configuring a Cordova Development Environment.

Installing required plugins for Akula (iOS and Android only)

For Akula core:

$cordova plugin add /{userpath}/cordova-sdk/lib/plugins/core

For Akula SQLCipher:

$cordova plugin add /{userpath}/cordova-sdk/lib/plugins/core

Before setting up the sample project, locate the cordova-sdk/samples/sync directory in the location where you installed Akula. This is the root directory of the sync sample app's Cordova project.

Tips If you have an existing Cordova sample on your device, be sure to delete it before deploying a new sample because the samples have the same name and they will cause conflicts. These directions were verified with Cordova version 4.2.0 Make sure your project only has either SQLite or SQLCipher - you can't have both in the project The JQuery reference must be to the correct version of JQuery AKConstant.js must have the correct IP address of your Akula server with your Sync app scope

Tips If you have an existing Cordova sample on your device, be sure to delete it before deploying a new sample because the samples have the same name and they will cause conflicts. These directions were verified with Cordova version 4.2.0 Make sure your project only has either SQLite or SQLCipher - you can't have both in the project The JQuery reference must be to the correct version of JQuery AKConstant.js must have the correct IP address of your Akula server with your Sync app scope

Android Cordova

Follow these steps to set up the sync sample app for the Cordova Android platform:

1. Import the cordova-sdk/samples/sync/platforms/android project into your IDE. For example, in Eclipse, select File > Import and ensure that you select Android > Existing Android Code Into Workspace in the Import dialog box.

2. Enter following commands on your command line to add Android libraries:
   cordova plugin add /cordova-sdk/lib/plugins/core
   cordova plugin add /cordova-sdk/lib/plugins/sqlcipher
   cordova plugin add https://github.com/VitaliiBlagodir/cordova-plugin-datepicker

3. Copy the cordova-sdk/lib/plugins/akula-cordova.js file, and the cordova-sdk/lib/dependencies directory, to the Cordova project's sync/www/js/lib directory. Replace existing files if necessary.

4. Add the Android Calendar control to the project

5. Run the Cordova prepare command from the project's directory. This command copies the contents of the app's sync /www directory to the platform-specific app in your /platforms directory. 

6. Run the app.

7. Import the cordova-sdk/samples/sync/platforms/android project into your IDE. For example, in Eclipse, select File > Import and ensure that you select Android > Existing Android Code Into Workspace in the Import dialog box.

8. Enter following commands on your command line to add Android libraries:
   cordova plugin add /cordova-sdk/lib/plugins/core
   cordova plugin add /cordova-sdk/lib/plugins/sqlcipher
   cordova plugin add https://github.com/VitaliiBlagodir/cordova-plugin-datepicker

9. Copy the cordova-sdk/lib/plugins/akula-cordova.js file, and the cordova-sdk/lib/dependencies directory, to the Cordova project's sync/www/js/lib directory. Replace existing files if necessary.

10. Add the Calendar control to the project

11. Run the Cordova prepare command from the project's directory. This command copies the contents of the app's sync /www directory to the platform-specific app in your /platforms directory. 

12. Run the app.

 

Ensure correct Java Build Order

 

 

Correct Java Build Order

 

iOS/Cordova

Follow these steps to set up the sync sample app for the Cordova iOS platform:

1. Open Sync.xcodeproj in Xcode. This Xcode project is located in the sync/platforms/ios directory.
2. Add the following framework files to your Xcode project:
   
   • /plugins/com.verivo.akula.cordova.core/src/ios/AkulaCordovaCorePlugin.framework
   • /plugins/com.verivo.akula.cordova.sqlcipher/src/ios/AkulaCordovaSQLCipherPlugin.framework
3. Copy the cordova-sdk/lib/akula-cordova.js file, and the /dependencies directory, to the new Cordova project sync/www/js/lib directory. Replace existing files if necessary.
4. Open Sync.xcodeproj in Xcode. This Xcode project is located in the sync/platforms/ios directory.
5. Add the following framework files to your Xcode project:
   
   • /plugins/com.verivo.akula.cordova.core/src/ios/AkulaCordovaCorePlugin.framework
   • /plugins/com.verivo.akula.cordova.sqlcipher/src/ios/AkulaCordovaSQLCipherPlugin.framework
6. Copy the cordova-sdk/lib/akula-cordova.js file, and the /dependencies directory, to the new Cordova project sync/www/js/lib directory. Replace existing files if necessary.

Configure the sample app to point to your Akula Server

After installing and configuring your sync sample app, you must modify it to point to the location of your Akula Server.

Note Do not use localhost to reference your Akula Server. Use the IP address or DNS name of your machine.

To point the sample app to your Akula Server:

1. Locate the  sync/www/js/app directory in your Cordova project.
2. Open the ak_constants.js file for editing.
3. Modify the following line to specify the location of the Custom Sync app scope on your Akula Server:
   
      var SERVER_URL = "http://myIPaddress:8080/akula/customsync";

If you are using the Route Sync app scope (routesync.akz), use the following URL:
   
   var SERVER_URL = " http://myIPaddress:8080/akula/routesync ";

Use the sample app

After configuring the sample app, run the Cordova prepare command from the /sync directory. This command processes each of the platforms' files and copies the necessary files from the /sync/www directory to the platform-specific app in your /platforms directory.

Note If you run the sync sample on two different devices or simulators at the same time, make sure that the two devices/simulators are set to the same date, time and time zone.

The purpose of sync is that changes from one mobile device can be synced with other mobile devices that are connected to the same Akula Server. However, it is hard to demonstrate sync if you have only one device or simulator. Therefore, the Custom Sync app scope (customsync.akz) on the Akula Server implements the following features to simulate a realistic environment:

• Tasks due on weekends are rejected by the server module as if your boss rejected them.
• Each time you sync with the server, you receive a new task as if your boss assigned you a new task.

The Route Sync app scope (routesync.akz) does not perform these tasks. To see changes made by another device when using the Route Sync app scope, you must test with two devices or manually change the SQLite database on the server.

To use the sample app:

1. Enter a password to unlock the encrypted persistent data store. Remember this password because you need it every time you unlock the persistent data store.

   Note On some Android devices, the persistent data store unlocks after entering an initial password, but the password dialog does not disappear. If this happens: a. Click the Back button to close the application. b. Reopen the application. c. Enter the same password again. The dialog box should disappear.

2. Click the Menu button and select Local Changes. The Local Changes screen should be empty because you have not added or updated any tasks yet.

3. Select the Menu button while the Local Changes screen is visible, and then select either Incremental Sync or Full Sync to sync with the data on the server.

   Note The first time you sync, the server returns two new tasks in the form: a. Sample Todo #1: Try adding a task to the list. b. Sample Todo #2: Update your new task's due date. On every subsequent sync, the Custom Sync app scope returns another new record in that format. The server also updates one record to be in the "completed" state, and deletes the last record that it marked completed. The Route Sync app scope simply syncs your client data with your server data.

4. Click the "+" icon in the upper-right corner to add a task. The task is saved to the persistent data store.
5. From the main screen, click the Menu button and select Local Changes. You should see your new task under the Adds area of the screen.

6. Select the Menu button while the Local Changes screen is visible, and then select either Incremental Sync or Full Sync.

   Note If the data in your new record is valid, the sync succeeds. The Custom Sync app scope rejects tasks if they are due on a weekend, or if their text is empty. If a task is submitted that violates these constraints, it is rejected, and appears in the Rejected Changes screen. Also, the server rejects a deleted record if it is not in the completed state.

These business rules apply only to the Custom Sync app scope. If you are using the Route Sync app scope, the server does not reject records during a deletion, regardless of their state. Try editing an existing record to set its due date to a weekend to see it being rejected.

To view the rejected records, select Menu > Rejected Changes from the main screen.

For more information

For more information, see:

• Configuring a Cordova Development Environment
• Synchronizing Client Data with the Akula Server
• Using the Built-in Route Sync Module
• Writing a Custom Sync Module