Synchronization for Mobile apps
This document discusses how to facilitate the synchronization of user data with data present on the Learningpod platform.
To help keep track of the state of user data, we will leverage a transaction sequence ID (txSequenceId). This is a simple numeric long datatype. Every user interaction with a pod, such as starting a pod, ending a pod, answering a question, etc. will increment txSequenceId. A local copy of txSequenceId should be kept on the device to provide a mechanism for quickly and efficiently comparing the state of user data with what is present on the Learningpod platform.
A local copy of txSequenceId should be stored in via the appropriate key/value store on the mobile device.
||Recommended Data Store
The first time a user account is created, or the first time a user authenticates through the app, a call may be made /api/sync (details below) to initialize txSequenceId. If the app has only a set of pre-selected pods available, additional calls to /api/sync/delta/pod should be made as well utilizing a txSequenceId of 0 in case the user has previously interacted with those pods elsewhere..
After the initialization, /api/sync should be polled either at regular intervals, or when certain application events occur. If the value of txSequenceId returned by this service is greater than the value stored locally, this indicates that there has been changes to user data outside the context of this device. The changes may have come from the same app installed on a different device, from a different app, or directly from Learningpod.com.
For most mobile use cases, an event based synchronization will work well. Such events would be an application start, or a change of application state from background to foreground.
Whenever /api/sync is called, the txSequenceId value returned should be held temporarily in memory, a value we will call txSequenceIdTemp. If the value is greater than what is available in the local datastore, a second call to /api/sync/delta/pod (details below) should be made. For a specific set of pods, If there are a large number of pods involved, or the GET request size of the client is exceeded, this can be broken up into multiple, smaller calls of ~20 pods each for faster processing.
If the mobile app is interested in any of the podInstances returned by this service, the state of local data about the pod should be updated to match what is on Learningpod.com. The local podInstance can be immediately updated, and additional calls should be made to retrieve podInteractions associated with each of the questions. The state of the podInstance and all associated interactions should completely replace what is available locally. In certain edge cases if a user has interacted with the same pod on multiple device before any synchronizations occur, this may change a user’s answer to a question, or remove an answer entirely, but this will be very rare.
After local data has been updated, or no podInstances have been returned by /api/sync/delta/pod, the value of txSequenceId in the local datastore may be updated with the value of txSequenceIdTemp.
Additionally, whenever a user interacts with a pod, and that data is sent to the API, the local txSequenceId should updated. This will act to prevent unnecessary synchronization attempts. The ActionResponse object returned when POSTing user pod data to an APIs will contain the newest value of txSequenceId, highlighted below.
Getting the current txSequenceId
- Path /api/sync
- Method GET
- Requires user signature Yes
- Path /api/sync/delta/pod
- Method GET
- Requires user signature Yes
This endpoint will return a list of podInstances that have been altered since the specified txSequenceId.
||A long value. API will return any podInstance that was modified after this ID. This should be the value that is stored on the local device.
||A string (UUID) value. May occur one or more times. The API will return only podInstances associated with the specified pods if appropriate.
||A string (UUID) value. May occur one or more times. The API will return only podInstances associated with pods defined within the specified podCollection if appropriate.
<title>Test Pod One</title>
<description>A Pod for testing</description>
<title>Test Pod Two</title>