# Amazon Cognito Sync
****
If you're new to Amazon Cognito Sync, use [AWS AppSync](https://aws.amazon.com/appsync/). Like Amazon Cognito Sync, AWS AppSync is a service for synchronizing application data across devices.
It enables user data like app preferences or game state to be synchronized. It also extends these capabilities by allowing multiple users to synchronize and collaborate in real time on shared data.
Amazon Cognito Sync is an AWS service and client library that makes it possible to sync application-related user data across devices. Amazon Cognito Sync can synchronize user profile data across mobile devices and the web without using your own backend. The client libraries cache data locally so that your app can read and write data regardless of device connectivity status. When the device is online, you can synchronize data. If you set up push sync, you can notify other devices immediately that an update is available.
For information about Amazon Cognito Identity region availability, see [AWS Service Region Availability](http://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/).
To learn more about Amazon Cognito Sync, see the following topics.
**Topics**
+ [Getting started with Amazon Cognito Sync](getting-started-with-cognito-sync.md)
+ [Synchronizing data across clients](synchronizing-data.md)
+ [Handling event callbacks](handling-callbacks.md)
+ [Implementing push synchronization](push-sync.md)
+ [Implementing Amazon Cognito Sync streams](cognito-streams.md)
+ [Customizing workflows with Amazon Cognito Events](cognito-events.md)
# Getting started with Amazon Cognito Sync
****
If you're new to Amazon Cognito Sync, use [AWS AppSync](https://aws.amazon.com/appsync/). Like Amazon Cognito Sync, AWS AppSync is a service for synchronizing application data across devices.
It enables user data like app preferences or game state to be synchronized. It also extends these capabilities by allowing multiple users to synchronize and collaborate in real time on shared data.
Amazon Cognito Sync is an AWS service and client library that enable cross-device syncing of application-related user data. You can use it to synchronize user profile data across mobile devices and web applications. The client libraries cache data locally so your app can read and write data regardless of device connectivity status. When the device is online, you can synchronize data, and if you set up push sync, notify other devices immediately that an update is available.
## Set up an identity pool in Amazon Cognito
Amazon Cognito Sync requires an Amazon Cognito identity pool to provide user identities. Before you use Amazon Cognito Sync you must first set up an identity pool. To create an identity pool and install the SDK, see [Getting started with Amazon Cognito identity pools](getting-started-with-identity-pools.md).
## Store and sync data
After you have set up your identity pool and installed the SDK, you can start storing and syncing data between devices. For more information, see [Synchronizing data across clients](synchronizing-data.md).
# Synchronizing data across clients
****
If you're new to Amazon Cognito Sync, use [AWS AppSync](https://aws.amazon.com/appsync/). Like Amazon Cognito Sync, AWS AppSync is a service for synchronizing application data across devices.
It enables user data like app preferences or game state to be synchronized. It also extends these capabilities by allowing multiple users to synchronize and collaborate in real time on shared data.
With Amazon Cognito, you can save user data in datasets that contain key-value pairs. Amazon Cognito associates this data with an identity in your identity pool so that your app can access it across logins and devices. To sync this data between the Amazon Cognito service and an end user’s devices, invoke the synchronize method. Each dataset can have a maximum size of 1 MB. You can associate up to 20 datasets with an identity.
The Amazon Cognito Sync client creates a local cache for the identity data. When your app reads and writes keys, it communicates with this local cache . This communication guarantees that all changes you make on the device are immediately available on the device, even when you are offline. When the synchronize method is called, changes from the service are pulled to the device, and any local changes are pushed to the service. At this point, the changes are available to other devices to synchronize.
## Initializing the Amazon Cognito Sync client
To initialize the Amazon Cognito Sync client, you must first create a credentials provider. The credentials provider acquires temporary AWS credentials to make it possible for your app to access your AWS resources. You also must import the necessary header files. Use the following steps to initialize the Amazon Cognito Sync client.
### Android
1. Create a credentials provider, following the instructions in [Getting credentials](getting-credentials.md).
1. Import the Amazon Cognito package as follows: `import com.amazonaws.mobileconnectors.cognito.*;`
1. Initialize Amazon Cognito Sync. Pass in the Android app context, the identity pool ID, an AWS Region, and an initialized Amazon Cognito credentials provider as follows:
```
CognitoSyncManager client = new CognitoSyncManager(
getApplicationContext(),
Regions.YOUR_REGION,
credentialsProvider);
```
### iOS - Objective-C
1. Create a credentials provider, following the instructions in [Getting credentials](getting-credentials.md).
1. Import `AWSCore` and `Cognito`, and initialize `AWSCognito` as follows:
```
#import
#import
AWSCognito *syncClient = [AWSCognito defaultCognito];
```
1. If you're using CocoaPods, replace `` with `AWSCore.h`. Follow the same syntax for the Amazon Cognito import.
### iOS - Swift
1. Create a credentials provider, following the instructions in [Getting credentials](getting-credentials.md).
1. Import and initialize `AWSCognito` as follows:
```
import AWSCognito
let syncClient = AWSCognito.default()!
```
### JavaScript
1. Download the [Amazon Cognito Sync Manager for JavaScript](https://github.com/aws/amazon-cognito-js).
1. Include the Sync Manager library in your project.
1. Create a credentials provider, following the instructions in [Getting credentials](getting-credentials.md).
1. Initialize the Sync Manager as follows:
```
var syncManager = new AWS.CognitoSyncManager();
```
### Unity
1. Create an instance of `CognitoAWSCredentials`, following the instructions in [Getting credentials](getting-credentials.md).
1. Create an instance of `CognitoSyncManager`. Pass the `CognitoAwsCredentials` object and a `AmazonCognitoSyncConfig`, and include at least the Region set, as follows:
```
AmazonCognitoSyncConfig clientConfig = new AmazonCognitoSyncConfig { RegionEndpoint = REGION };
CognitoSyncManager syncManager = new CognitoSyncManager(credentials, clientConfig);
```
### Xamarin
1. Create an instance of `CognitoAWSCredentials`, following the instructions in [Getting credentials](getting-credentials.md).
1. Create an instance of `CognitoSyncManager`. Pass the `CognitoAwsCredentials` object and a `AmazonCognitoSyncConfig`, and include at least the Region set, as follows:
```
AmazonCognitoSyncConfig clientConfig = new AmazonCognitoSyncConfig { RegionEndpoint = REGION };
CognitoSyncManager syncManager = new CognitoSyncManager(credentials, clientConfig);
```
## Understanding datasets
Amazon Cognito organizes user profile data into datasets. Each dataset can contain up to 1MB of data in the form of key-value pairs. A dataset is the most granular entity that you can synchronize. Read and write operations performed on a dataset only affect the local store until the synchronize method is invoked. Amazon Cognito identifies a dataset by a unique string. You can create a new dataset or open an existing one as follows.
### Android
```
Dataset dataset = client.openOrCreateDataset("datasetname");
```
To delete a dataset, first call the method to remove it from local storage, then call the `synchronize` method to delete the dataset from Amazon Cognito as follows:
```
dataset.delete();
dataset.synchronize(syncCallback);
```
### iOS - Objective-C
```
AWSCognitoDataset *dataset = [syncClient openOrCreateDataset:@"myDataSet"];
```
To delete a dataset, first call the method to remove it from local storage, then call the `synchronize` method to delete the dataset from Amazon Cognito as follows:
```
[dataset clear];
[dataset synchronize];
```
### iOS - Swift
```
let dataset = syncClient.openOrCreateDataset("myDataSet")!
```
To delete a dataset, first call the method to remove it from local storage, then call the `synchronize` method as follows: to delete the dataset from Amazon Cognito:
```
dataset.clear()
dataset.synchronize()
```
### JavaScript
```
syncManager.openOrCreateDataset('myDatasetName', function(err, dataset) {
// ...
});
```
### Unity
```
string myValue = dataset.Get("myKey");
dataset.Put("myKey", "newValue");
```
To delete a key from a dataset, use `Remove` as follows:
```
dataset.Remove("myKey");
```
### Xamarin
```
Dataset dataset = syncManager.OpenOrCreateDataset("myDatasetName");
```
To delete a dataset, first call the method to remove it from local storage, then call the `synchronize` method to delete the dataset from Amazon Cognito as follows:
```
dataset.Delete();
dataset.SynchronizeAsync();
```
## Reading and writing data in datasets
Amazon Cognito datasets function as dictionaries, with values accessible by key. You can read, add, or modify keys and values of a dataset just as if the dataset were a dictionary, as shown in the following examples.
Note that values you write to a dataset only affect the local cached copy of the data until you call the synchronize method.
### Android
```
String value = dataset.get("myKey");
dataset.put("myKey", "my value");
```
### iOS - Objective-C
```
[dataset setString:@"my value" forKey:@"myKey"];
NSString *value = [dataset stringForKey:@"myKey"];
```
### iOS - Swift
```
dataset.setString("my value", forKey:"myKey")
let value = dataset.stringForKey("myKey")
```
### JavaScript
```
dataset.get('myKey', function(err, value) {
console.log('myRecord: ' + value);
});
dataset.put('newKey', 'newValue', function(err, record) {
console.log(record);
});
dataset.remove('oldKey', function(err, record) {
console.log(success);
});
```
### Unity
```
string myValue = dataset.Get("myKey");
dataset.Put("myKey", "newValue");
```
### Xamarin
```
//obtain a value
string myValue = dataset.Get("myKey");
// Create a record in a dataset and synchronize with the server
dataset.OnSyncSuccess += SyncSuccessCallback;
dataset.Put("myKey", "myValue");
dataset.SynchronizeAsync();
void SyncSuccessCallback(object sender, SyncSuccessEventArgs e) {
// Your handler code here
}
```
### Android
To remove keys from a dataset, use the `remove` method as follows:
```
dataset.remove("myKey");
```
### iOS - Objective-C
To delete a key from a dataset, use `removeObjectForKey` as follows:
```
[dataset removeObjectForKey:@"myKey"];
```
### iOS - Swift
To delete a key from a dataset, use `removeObjectForKey` as follows:
```
dataset.removeObjectForKey("myKey")
```
### Unity
To delete a key from a dataset, use `Remove` as follows:
```
dataset.Remove("myKey");
```
### Xamarin
You can use `Remove` to delete a key from a dataset:
```
dataset.Remove("myKey");
```
## Synchronizing local data with the sync store
### Android
The `synchronize` method compares local cached data to the data stored in the Amazon Cognito Sync store. Remote changes are pulled from the Amazon Cognito Sync store; conflict resolution is invoked if any conflicts occur; and updated values on the device are pushed to the service. To synchronize a dataset, call its `synchronize` method:
```
dataset.synchronize(syncCallback);
```
The `synchronize` method receives an implementation of the `SyncCallback` interface, discussed below.
The `synchronizeOnConnectivity()` method attempts to synchronize when connectivity is available. If connectivity is immediately available, `synchronizeOnConnectivity()` behaves like `synchronize()`. Otherwise it monitors for connectivity changes and performs a sync once connectivity is available. If `synchronizeOnConnectivity()`is called multiple times, only the last synchronize request is kept, and only the last callback will fire. If either the dataset or the callback is garbage-collected, this method won't perform a sync, and the callback won't fire.
To learn more about dataset synchronization and the different callbacks, see [Handling event callbacks](handling-callbacks.md).
### iOS - Objective-C
The `synchronize` method compares local cached data to the data stored in the Amazon Cognito Sync store. Remote changes are pulled from the Amazon Cognito Sync store; conflict resolution is invoked if any conflicts occur; and updated values on the device are pushed to the service. To synchronize a dataset, call its `synchronize` method:
The `synchronize` method is asynchronous and returns an `AWSTask` object to handle the response:
```
[[dataset synchronize] continueWithBlock:^id(AWSTask *task) {
if (task.isCancelled) {
// Task cancelled.
} else if (task.error) {
// Error while executing task.
} else {
// Task succeeded. The data was saved in the sync store.
}
return nil;
}];
```
The `synchronizeOnConnectivity` method attempts to synchronize when the device has connectivity. First, `synchronizeOnConnectivity` checks for connectivity and, if the device is online, immediately invokes synchronize and returns the `AWSTask` object associated with the attempt.
If the device is offline, `synchronizeOnConnectivity` 1) schedules a synchronize for the next time the device comes online and 2) returns an `AWSTask` with a nil result. The scheduled synchronize is only valid for the lifecycle of the dataset object. The data will not be synchronized if the app is exited before connectivity is regained. If you want to be notified when events occur during the scheduled synchronize, you must add observers of the notifications found in `AWSCognito`.
To learn more about dataset synchronization and the different callbacks, see [Handling event callbacks](handling-callbacks.md).
### iOS - Swift
The `synchronize` method compares local cached data to the data stored in the Amazon Cognito Sync store. Remote changes are pulled from the Amazon Cognito Sync store; conflict resolution is invoked if any conflicts occur; and updated values on the device are pushed to the service. To synchronize a dataset, call its `synchronize` method:
The `synchronize` method is asynchronous and returns an `AWSTask` object to handle the response:
```
dataset.synchronize().continueWith(block: { (task) -> AnyObject? in
if task.isCancelled {
// Task cancelled.
} else if task.error != nil {
// Error while executing task
} else {
// Task succeeded. The data was saved in the sync store.
}
return task
})
```
The `synchronizeOnConnectivity` method attempts to synchronize when the device has connectivity. First, `synchronizeOnConnectivity` checks for connectivity and, if the device is online, immediately invokes `synchronize` and returns the `AWSTask` object associated with the attempt.
If the device is offline, `synchronizeOnConnectivity` 1) schedules a synchronize for the next time the device comes online and 2) returns an `AWSTask` object with a nil result. The scheduled synchronize is only valid for the lifecycle of the dataset object. The data will not be synchronized if the app is exited before connectivity is regained. If you want to be notified when events occur during the scheduled synchronize, you must add observers of the notifications found in `AWSCognito`.
To learn more about dataset synchronization and the different callbacks, see [Handling event callbacks](handling-callbacks.md).
### JavaScript
The `synchronize` method compares local cached data to the data stored in the Amazon Cognito Sync store. Remote changes are pulled from the Amazon Cognito Sync store; conflict resolution is invoked if any conflicts occur; and updated values on the device are pushed to the service. To synchronize a dataset, call its `synchronize` method:
```
dataset.synchronize();
```
To learn more about dataset synchronization and the different callbacks, see [Handling event callbacks](handling-callbacks.md).
### Unity
The synchronize method compares local cached data to the data stored in the Amazon Cognito Sync store. Remote changes are pulled from the Amazon Cognito Sync store; conflict resolution is invoked if any conflicts occur; and updated values on the device are pushed to the service. To synchronize a dataset, call its `synchronize` method:
```
dataset.Synchronize();
```
Synchronize will run asynchronously and will end up calling one of the several callbacks you can specify in the Dataset.
To learn more about dataset synchronization and the different callbacks, see [Handling event callbacks](handling-callbacks.md).
### Xamarin
The `synchronize` method compares local cached data to the data stored in the Amazon Cognito Sync store. Remote changes are pulled from the Amazon Cognito Sync store; conflict resolution is invoked if any conflicts occur; and updated values on the device are pushed to the service. To synchronize a dataset, call its `synchronize` method:
```
dataset.SynchronizeAsync();
```
To learn more about dataset synchronization and the different callbacks, see [Handling event callbacks](handling-callbacks.md).
# Handling event callbacks
****
If you're new to Amazon Cognito Sync, use [AWS AppSync](https://aws.amazon.com/appsync/). Like Amazon Cognito Sync, AWS AppSync is a service for synchronizing application data across devices.
It enables user data like app preferences or game state to be synchronized. It also extends these capabilities by allowing multiple users to synchronize and collaborate in real time on shared data.
As an Amazon Cognito Sync developer, you can implement various callbacks to handle different synchronization events and scenarios. The `SyncCallback` interface in the Android SDK configures notifications about dataset synchronization, including `onSuccess()` when a dataset is successfully downloaded, `onFailure()` when an exception occurs, and `onConflict()` to resolve conflicts between local and remote data.
In the iOS SDK, you can register for similar notifications like `AWSCognitoDidStartSynchronizeNotification` and set handlers like the `AWSCognitoRecordConflictHandler` for conflict resolution. The JavaScript, Unity, and Xamarin platforms have analogous callback mechanisms. When you implement these callbacks, your application can gracefully handle the various synchronization events and scenarios that can occur when using Amazon Cognito Sync.
## Android
**SyncCallback Interface**
By implementing the `SyncCallback` interface, you can receive notifications on your app about dataset synchronization. Your app can then make active decisions about deleting local data, merging unauthenticated and authenticated profiles, and resolving sync conflicts. You should implement the following methods, which are required by the interface:
+ `onSuccess()`
+ `onFailure()`
+ `onConflict()`
+ `onDatasetDeleted()`
+ `onDatasetsMerged()`
Note that, if you don't want to specify all the callbacks, you can also use the class `DefaultSyncCallback` which provides default, empty implementations for all of them.
**onSuccess**
The `onSuccess()` callback is triggered when a dataset is successfully downloaded from the sync store.
```
@Override
public void onSuccess(Dataset dataset, List newRecords) {
}
```
**onFailure**
onFailure() is called if an exception occurs during synchronization.
```
@Override
public void onFailure(DataStorageException dse) {
}
```
**onConflict**
Conflicts may arise if the same key has been modified on the local store and in the sync store. The `onConflict()` method handles conflict resolution. If you don't implement this method, the Amazon Cognito Sync client defaults to using the most recent change.
```
@Override
public boolean onConflict(Dataset dataset, final List conflicts) {
List resolvedRecords = new ArrayList();
for (SyncConflict conflict : conflicts) {
/* resolved by taking remote records */
resolvedRecords.add(conflict.resolveWithRemoteRecord());
/* alternately take the local records */
// resolvedRecords.add(conflict.resolveWithLocalRecord());
/* or customer logic, say concatenate strings */
// String newValue = conflict.getRemoteRecord().getValue()
// + conflict.getLocalRecord().getValue();
// resolvedRecords.add(conflict.resolveWithValue(newValue);
}
dataset.resolve(resolvedRecords);
// return true so that synchronize() is retried after conflicts are resolved
return true;
}
```
**onDatasetDeleted**
When a dataset is deleted, the Amazon Cognito client uses the `SyncCallback` interface to confirm whether the local cached copy of the dataset should be deleted too. Implement the `onDatasetDeleted()` method to tell the client SDK what to do with the local data.
```
@Override
public boolean onDatasetDeleted(Dataset dataset, String datasetName) {
// return true to delete the local copy of the dataset
return true;
}
```
**onDatasetMerged**
When two previously unconnected identities are linked together, all of their datasets are merged. Applications are notified of the merge through the `onDatasetsMerged()` method:
```
@Override
public boolean onDatasetsMerged(Dataset dataset, List datasetNames) {
// return false to handle Dataset merge outside the synchronization callback
return false;
}
```
## iOS - Objective-C
**Sync Notifications**
The Amazon Cognito client will emit a number of `NSNotification` events during a synchronize call. You can register to monitor these notifications via the standard `NSNotificationCenter`:
```
[NSNotificationCenter defaultCenter]
addObserver:self
selector:@selector(myNotificationHandler:)
name:NOTIFICATION_TYPE
object:nil];
```
Amazon Cognito supports five notification types, listed below.
**AWSCognitoDidStartSynchronizeNotification**
Called when a synchronize operation is starting. The `userInfo` will contain the key dataset which is the name of the dataset being synchronized.
**AWSCognitoDidEndSynchronizeNotification**
Called when a synchronize operation completes (successfully or otherwise). The `userInfo` will contain the key dataset which is the name of the dataset being synchronized.
**AWSCognitoDidFailToSynchronizeNotification**
Called when a synchronize operation fails. The `userInfo` will contain the key dataset which is the name of the dataset being synchronized and the key error which will contain the error that caused the failure.
**AWSCognitoDidChangeRemoteValueNotification**
Called when local changes are successfully pushed to Amazon Cognito. The `userInfo` will contain the key dataset which is the name of the dataset being synchronized and the key keys which will contain an NSArray of record keys that were pushed.
**AWSCognitoDidChangeLocalValueFromRemoteNotification**
Called when a local value changes due to a synchronize operation. The `userInfo` will contain the key dataset which is the name of the dataset being synchronized and the key keys which will contain an NSArray of record keys that changed.
**Conflict Resolution Handler**
During a sync operation, conflicts may arise if the same key has been modified on the local store and in the sync store. If you haven't set a conflict resolution handler, Amazon Cognito defaults to choosing the most recent update.
By implementing and assigning an AWSCognitoRecordConflictHandler you can alter the default conflict resolution. The AWSCognitoConflict input parameter conflict contains an AWSCognitoRecord object for both the local cached data and for the conflicting record in the sync store. Using the AWSCognitoConflict you can resolve the conflict with the local record: [conflict resolveWithLocalRecord], the remote record: [conflict resolveWithRemoteRecord] or a brand new value: [conflict resolveWithValue:value]. Returning nil from this method prevents synchronization from continuing and the conflicts will be presented again the next time the sync process starts.
You can set the conflict resolution handler at the client level:
```
client.conflictHandler = ^AWSCognitoResolvedConflict* (NSString *datasetName, AWSCognitoConflict *conflict) {
// always choose local changes
return [conflict resolveWithLocalRecord];
};
```
Or at the dataset level:
```
dataset.conflictHandler = ^AWSCognitoResolvedConflict* (NSString *datasetName, AWSCognitoConflict *conflict) {
// override and always choose remote changes
return [conflict resolveWithRemoteRecord];
};
```
**Dataset Deleted Handler**
When a dataset is deleted, the Amazon Cognito client uses the `AWSCognitoDatasetDeletedHandler` to confirm whether the local cached copy of the dataset should be deleted too. If no `AWSCognitoDatasetDeletedHandler` is implemented, the local data will be purged automatically. Implement an `AWSCognitoDatasetDeletedHandler` if you wish to keep a copy of the local data before wiping, or to keep the local data.
You can set the dataset deleted handler at the client level:
```
client.datasetDeletedHandler = ^BOOL (NSString *datasetName) {
// make a backup of the data if you choose
...
// delete the local data (default behavior)
return YES;
};
```
Or at the dataset level:
```
dataset.datasetDeletedHandler = ^BOOL (NSString *datasetName) {
// override default and keep the local data
return NO;
};
```
**Dataset Merge Handler**
When two previously unconnected identities are linked together, all of their datasets are merged. Applications are notified of the merge through the `DatasetMergeHandler`. The handler will receive the name of the root dataset as well as an array of dataset names that are marked as merges of the root dataset.
If no `DatasetMergeHandler` is implemented, these datasets will be ignored, but will continue to use up space in the identity's 20 maximum total datasets.
You can set the dataset merge handler at the client level:
```
client.datasetMergedHandler = ^(NSString *datasetName, NSArray *datasets) {
// Blindly delete the datasets
for (NSString *name in datasets) {
AWSCognitoDataset *merged = [[AWSCognito defaultCognito] openOrCreateDataset:name];
[merged clear];
[merged synchronize];
}
};
```
Or at the dataset level:
```
dataset.datasetMergedHandler = ^(NSString *datasetName, NSArray *datasets) {
// Blindly delete the datasets
for (NSString *name in datasets) {
AWSCognitoDataset *merged = [[AWSCognito defaultCognito] openOrCreateDataset:name];
// do something with the data if it differs from existing dataset
...
// now delete it
[merged clear];
[merged synchronize];
}
};
```
## iOS - Swift
**Sync Notifications**
The Amazon Cognito client will emit a number of `NSNotification` events during a synchronize call. You can register to monitor these notifications via the standard `NSNotificationCenter`:
```
NSNotificationCenter.defaultCenter().addObserver(observer: self,
selector: "myNotificationHandler",
name:NOTIFICATION_TYPE,
object:nil)
```
Amazon Cognito supports five notification types, listed below.
**AWSCognitoDidStartSynchronizeNotification**
Called when a synchronize operation is starting. The `userInfo` will contain the key dataset which is the name of the dataset being synchronized.
**AWSCognitoDidEndSynchronizeNotification**
Called when a synchronize operation completes (successfully or otherwise). The `userInfo` will contain the key dataset which is the name of the dataset being synchronized.
**AWSCognitoDidFailToSynchronizeNotification**
Called when a synchronize operation fails. The `userInfo` will contain the key dataset which is the name of the dataset being synchronized and the key error which will contain the error that caused the failure.
**AWSCognitoDidChangeRemoteValueNotification**
Called when local changes are successfully pushed to Amazon Cognito. The `userInfo` will contain the key dataset which is the name of the dataset being synchronized and the key keys which will contain an NSArray of record keys that were pushed.
**AWSCognitoDidChangeLocalValueFromRemoteNotification**
Called when a local value changes due to a synchronize operation. The `userInfo` will contain the key dataset which is the name of the dataset being synchronized and the key keys which will contain an NSArray of record keys that changed.
**Conflict Resolution Handler**
During a sync operation, conflicts may arise if the same key has been modified on the local store and in the sync store. If you haven't set a conflict resolution handler, Amazon Cognito defaults to choosing the most recent update.
By implementing and assigning an `AWSCognitoRecordConflictHandler` you can alter the default conflict resolution. The `AWSCognitoConflict` input parameter conflict contains an `AWSCognitoRecord` object for both the local cached data and for the conflicting record in the sync store. Using the `AWSCognitoConflict` you can resolve the conflict with the local record: [conflict resolveWithLocalRecord], the remote record: [conflict resolveWithRemoteRecord] or a brand new value: [conflict resolveWithValue:value]. Returning nil from this method prevents synchronization from continuing and the conflicts will be presented again the next time the sync process starts.
You can set the conflict resolution handler at the client level:
```
client.conflictHandler = {
(datasetName: String?, conflict: AWSCognitoConflict?) -> AWSCognitoResolvedConflict? in
return conflict.resolveWithLocalRecord()
}
```
Or at the dataset level:
```
dataset.conflictHandler = {
(datasetName: String?, conflict: AWSCognitoConflict?) -> AWSCognitoResolvedConflict? in
return conflict.resolveWithLocalRecord()
}
```
**Dataset Deleted Handler**
When a dataset is deleted, the Amazon Cognito client uses the `AWSCognitoDatasetDeletedHandler` to confirm whether the local cached copy of the dataset should be deleted too. If no `AWSCognitoDatasetDeletedHandler` is implemented, the local data will be purged automatically. Implement an `AWSCognitoDatasetDeletedHandler` if you wish to keep a copy of the local data before wiping, or to keep the local data.
You can set the dataset deleted handler at the client level:
```
client.datasetDeletedHandler = {
(datasetName: String!) -> Bool in
// make a backup of the data if you choose
...
// delete the local data (default behaviour)
return true
}
```
Or at the dataset level:
```
dataset.datasetDeletedHandler = {
(datasetName: String!) -> Bool in
// make a backup of the data if you choose
...
// delete the local data (default behaviour)
return true
}
```
**Dataset merge handler**
When two previously unconnected identities are linked together, all of their datasets are merged. Applications are notified of the merge through the `DatasetMergeHandler`. The handler will receive the name of the root dataset as well as an array of dataset names that are marked as merges of the root dataset.
If no `DatasetMergeHandler` is implemented, these datasets will be ignored, but will continue to use up space in the identity's 20 maximum total datasets.
You can set the dataset merge handler at the client level:
```
client.datasetMergedHandler = {
(datasetName: String!, datasets: [AnyObject]!) -> Void in
for nameObject in datasets {
if let name = nameObject as? String {
let merged = AWSCognito.defaultCognito().openOrCreateDataset(name)
merged.clear()
merged.synchronize()
}
}
}
```
Or at the dataset level:
```
dataset.datasetMergedHandler = {
(datasetName: String!, datasets: [AnyObject]!) -> Void in
for nameObject in datasets {
if let name = nameObject as? String {
let merged = AWSCognito.defaultCognito().openOrCreateDataset(name)
// do something with the data if it differs from existing dataset
...
// now delete it
merged.clear()
merged.synchronize()
}
}
}
```
## JavaScript
**Synchronization callbacks**
When performing a synchronize() on a dataset, you can optionally specify callbacks to handle each of the following states:
```
dataset.synchronize({
onSuccess: function(dataset, newRecords) {
//...
},
onFailure: function(err) {
//...
},
onConflict: function(dataset, conflicts, callback) {
//...
},
onDatasetDeleted: function(dataset, datasetName, callback) {
//...
},
onDatasetMerged: function(dataset, datasetNames, callback) {
//...
}
});
```
**onSuccess()**
The `onSuccess()` callback is triggered when a dataset is successfully updated from the sync store. If you do not define a callback, the synchronization will succeed silently.
```
onSuccess: function(dataset, newRecords) {
console.log('Successfully synchronized ' + newRecords.length + ' new records.');
}
```
**onFailure()**
`onFailure()` is called if an exception occurs during synchronization. If you do not define a callback, the synchronization will fail silently.
```
onFailure: function(err) {
console.log('Synchronization failed.');
console.log(err);
}
```
**onConflict()**
Conflicts may arise if the same key has been modified on the local store and in the sync store. The `onConflict()` method handles conflict resolution. If you don't implement this method, the synchronization will be aborted when there is a conflict.
```
onConflict: function(dataset, conflicts, callback) {
var resolved = [];
for (var i=0; i
After you open or create a dataset, you can set different callbacks to it that will be triggered when you use the Synchronize method. This is the way to register your callbacks to them:
```
dataset.OnSyncSuccess += this.HandleSyncSuccess;
dataset.OnSyncFailure += this.HandleSyncFailure;
dataset.OnSyncConflict = this.HandleSyncConflict;
dataset.OnDatasetMerged = this.HandleDatasetMerged;
dataset.OnDatasetDeleted = this.HandleDatasetDeleted;
```
Note that `SyncSuccess` and `SyncFailure` use \$1= instead of = so you can subscribe more than one callback to them.
**OnSyncSuccess**
The `OnSyncSuccess` callback is triggered when a dataset is successfully updated from the cloud. If you do not define a callback, the synchronization will succeed silently.
```
private void HandleSyncSuccess(object sender, SyncSuccessEvent e)
{
// Continue with your game flow, display the loaded data, etc.
}
```
**OnSyncFailure**
`OnSyncFailure` is called if an exception occurs during synchronization. If you do not define a callback, the synchronization will fail silently.
```
private void HandleSyncFailure(object sender, SyncFailureEvent e)
{
Dataset dataset = sender as Dataset;
if (dataset.Metadata != null) {
Debug.Log("Sync failed for dataset : " + dataset.Metadata.DatasetName);
} else {
Debug.Log("Sync failed");
}
// Handle the error
Debug.LogException(e.Exception);
}
```
**OnSyncConflict**
Conflicts may arise if the same key has been modified on the local store and in the sync store. The `OnSyncConflict` callback handles conflict resolution. If you don't implement this method, the synchronization will be aborted when there is a conflict.
```
private bool HandleSyncConflict(Dataset dataset, List < SyncConflict > conflicts)
{
if (dataset.Metadata != null) {
Debug.LogWarning("Sync conflict " + dataset.Metadata.DatasetName);
} else {
Debug.LogWarning("Sync conflict");
}
List < Amazon.CognitoSync.SyncManager.Record > resolvedRecords = new List < Amazon.CognitoSync.SyncManager.Record > ();
foreach(SyncConflict conflictRecord in conflicts) {
// SyncManager provides the following default conflict resolution methods:
// ResolveWithRemoteRecord - overwrites the local with remote records
// ResolveWithLocalRecord - overwrites the remote with local records
// ResolveWithValue - to implement your own logic
resolvedRecords.Add(conflictRecord.ResolveWithRemoteRecord());
}
// resolves the conflicts in local storage
dataset.Resolve(resolvedRecords);
// on return true the synchronize operation continues where it left,
// returning false cancels the synchronize operation
return true;
}
```
**OnDatasetDeleted**
When a dataset is deleted, the Amazon Cognito client uses the `OnDatasetDeleted` callback to decide whether the local cached copy of the dataset should be deleted too. By default, the dataset will not be deleted.
```
private bool HandleDatasetDeleted(Dataset dataset)
{
Debug.Log(dataset.Metadata.DatasetName + " Dataset has been deleted");
// Do clean up if necessary
// returning true informs the corresponding dataset can be purged in the local storage and return false retains the local dataset
return true;
}
```
**OnDatasetMerged**
When two previously unconnected identities are linked together, all of their datasets are merged. Applications are notified of the merge through the `OnDatasetsMerged` callback.
```
public bool HandleDatasetMerged(Dataset localDataset, List mergedDatasetNames)
{
foreach (string name in mergedDatasetNames)
{
Dataset mergedDataset = syncManager.OpenOrCreateDataset(name);
//Lambda function to delete the dataset after fetching it
EventHandler lambda;
lambda = (object sender, SyncSuccessEvent e) => {
ICollection existingValues = localDataset.GetAll().Values;
ICollection newValues = mergedDataset.GetAll().Values;
//Implement your merge logic here
mergedDataset.Delete(); //Delete the dataset locally
mergedDataset.OnSyncSuccess -= lambda; //We don't want this callback to be fired again
mergedDataset.OnSyncSuccess += (object s2, SyncSuccessEvent e2) => {
localDataset.Synchronize(); //Continue the sync operation that was interrupted by the merge
};
mergedDataset.Synchronize(); //Synchronize it as deleted, failing to do so will leave us in an inconsistent state
};
mergedDataset.OnSyncSuccess += lambda;
mergedDataset.Synchronize(); //Asnchronously fetch the dataset
}
// returning true allows the Synchronize to continue and false stops it
return false;
}
```
## Xamarin
After you open or create a dataset, you can set different callbacks to it that will be triggered when you use the Synchronize method. This is the way to register your callbacks to them:
```
dataset.OnSyncSuccess += this.HandleSyncSuccess;
dataset.OnSyncFailure += this.HandleSyncFailure;
dataset.OnSyncConflict = this.HandleSyncConflict;
dataset.OnDatasetMerged = this.HandleDatasetMerged;
dataset.OnDatasetDeleted = this.HandleDatasetDeleted;
```
Note that `SyncSuccess` and `SyncFailure` use \$1= instead of = so you can subscribe more than one callback to them.
**OnSyncSuccess**
The `OnSyncSuccess` callback is triggered when a dataset is successfully updated from the cloud. If you do not define a callback, the synchronization will succeed silently.
```
private void HandleSyncSuccess(object sender, SyncSuccessEventArgs e)
{
// Continue with your game flow, display the loaded data, etc.
}
```
**OnSyncFailure**
`OnSyncFailure` is called if an exception occurs during synchronization. If you do not define a callback, the synchronization will fail silently.
```
private void HandleSyncFailure(object sender, SyncFailureEventArgs e)
{
Dataset dataset = sender as Dataset;
if (dataset.Metadata != null) {
Console.WriteLine("Sync failed for dataset : " + dataset.Metadata.DatasetName);
} else {
Console.WriteLine("Sync failed");
}
}
```
**OnSyncConflict**
Conflicts may arise if the same key has been modified on the local store and in the sync store. The `OnSyncConflict` callback handles conflict resolution. If you don't implement this method, the synchronization will be aborted when there is a conflict.
```
private bool HandleSyncConflict(Dataset dataset, List < SyncConflict > conflicts)
{
if (dataset.Metadata != null) {
Console.WriteLine("Sync conflict " + dataset.Metadata.DatasetName);
} else {
Console.WriteLine("Sync conflict");
}
List < Amazon.CognitoSync.SyncManager.Record > resolvedRecords = new List < Amazon.CognitoSync.SyncManager.Record > ();
foreach(SyncConflict conflictRecord in conflicts) {
// SyncManager provides the following default conflict resolution methods:
// ResolveWithRemoteRecord - overwrites the local with remote records
// ResolveWithLocalRecord - overwrites the remote with local records
// ResolveWithValue - to implement your own logic
resolvedRecords.Add(conflictRecord.ResolveWithRemoteRecord());
}
// resolves the conflicts in local storage
dataset.Resolve(resolvedRecords);
// on return true the synchronize operation continues where it left,
// returning false cancels the synchronize operation
return true;
}
```
**OnDatasetDeleted**
When a dataset is deleted, the Amazon Cognito client uses the `OnDatasetDeleted` callback to decide whether the local cached copy of the dataset should be deleted too. By default, the dataset will not be deleted.
```
private bool HandleDatasetDeleted(Dataset dataset)
{
Console.WriteLine(dataset.Metadata.DatasetName + " Dataset has been deleted");
// Do clean up if necessary
// returning true informs the corresponding dataset can be purged in the local storage and return false retains the local dataset
return true;
}
```
**OnDatasetMerged**
When two previously unconnected identities are linked together, all of their datasets are merged. Applications are notified of the merge through the `OnDatasetsMerged` callback.
```
public bool HandleDatasetMerged(Dataset localDataset, List mergedDatasetNames)
{
foreach (string name in mergedDatasetNames)
{
Dataset mergedDataset = syncManager.OpenOrCreateDataset(name);
//Implement your merge logic here
mergedDataset.OnSyncSuccess += lambda;
mergedDataset.SynchronizeAsync(); //Asnchronously fetch the dataset
}
// returning true allows the Synchronize to continue and false stops it
return false;
}
```
# Implementing push synchronization
****
If you're new to Amazon Cognito Sync, use [AWS AppSync](https://aws.amazon.com/appsync/). Like Amazon Cognito Sync, AWS AppSync is a service for synchronizing application data across devices.
It enables user data like app preferences or game state to be synchronized. It also extends these capabilities by allowing multiple users to synchronize and collaborate in real time on shared data.
Amazon Cognito automatically tracks the association between identity and devices. Using the push synchronization, or push sync, feature, you can ensure that every instance of a given identity is notified when identity data changes. Push sync ensures that, whenever the sync store data changes for a particular identity, all devices associated with that identity receive a silent push notification informing them of the change.
**Note**
Push sync is not supported for JavaScript, Unity, or Xamarin.
Before you can use push sync, you must first set up your account for push sync and enable push sync in the Amazon Cognito console.
## Create an Amazon Simple Notification Service (Amazon SNS) app
Create and configure an Amazon SNS app for your supported platforms, as described in the [SNS Developer Guide](https://docs.aws.amazon.com/sns/latest/dg/SNSMobilePush.html).
## Enable push sync in the Amazon Cognito console
You can enable push sync via the Amazon Cognito console. From the [console home page](https://console.aws.amazon.com/cognito/home):
1. Click the name of the identity pool for which you want to enable push sync. The **Dashboard** page for your identity pool appears.
1. In the top-right corner of the **Dashboard** page, click **Manage Identity Pools**. The **Federated Identities** page appears.
1. Scroll down and click **Push synchronization** to expand it.
1. In the **Service role** dropdown menu, select the IAM role that grants Cognito permission to send an SNS notification. Click **Create role** to create or modify the roles associated with your identity pool in the [AWS IAM Console](https://console.aws.amazon.com/iam/home).
1. Select a platform application, and then click **Save Changes**.
1. Grant SNS Access to Your Application
In the AWS Identity and Access Management console, configure your IAM roles to have full Amazon SNS access, or create a new role that has full Amazon SNS access. The following example role trust policy grants Amazon Cognito Sync a limited ability to assume an IAM role. Amazon Cognito Sync can only assume the role when it does so on behalf of both the identity pool in the `aws:SourceArn` condition and the account in the `aws:SourceAccount` condition.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cognito-sync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "123456789012"
},
"ArnLike": {
"AWS:SourceArn": "arn:aws:cognito-identity:us-east-1:123456789012:identitypool/us-east-1:177a950c-2c08-43f0-9983-28727EXAMPLE"
}
}
}
]
}
```
------
To learn more about IAM roles, see [Roles (Delegation and Federation)](https://docs.aws.amazon.com/IAM/latest/UserGuide/WorkingWithRoles.html).
## Use push sync in your app: Android
Your application will need to import the Google Play services. You can download the latest version of the Google Play SDK via the [Android SDK manager](http://developer.android.com/tools/help/sdk-manager.html). Follow the Android documentation on [Android Implementation](https://developers.google.com/instance-id/guides/android-implementation) to register your app and receive a registration ID from GCM. Once you have the registration ID, you need to register the device with Amazon Cognito, as shown in the snippet below:
```
String registrationId = "MY_GCM_REGISTRATION_ID";
try {
client.registerDevice("GCM", registrationId);
} catch (RegistrationFailedException rfe) {
Log.e(TAG, "Failed to register device for silent sync", rfe);
} catch (AmazonClientException ace) {
Log.e(TAG, "An unknown error caused registration for silent sync to fail", ace);
}
```
You can now subscribe a device to receive updates from a particular dataset:
```
Dataset trackedDataset = client.openOrCreateDataset("myDataset");
if (client.isDeviceRegistered()) {
try {
trackedDataset.subscribe();
} catch (SubscribeFailedException sfe) {
Log.e(TAG, "Failed to subscribe to datasets", sfe);
} catch (AmazonClientException ace) {
Log.e(TAG, "An unknown error caused the subscription to fail", ace);
}
}
```
To stop receiving push notifications from a dataset, simply call the unsubscribe method. To subscribe to all datasets (or a specific subset) in the `CognitoSyncManager` object, use `subscribeAll()`:
```
if (client.isDeviceRegistered()) {
try {
client.subscribeAll();
} catch (SubscribeFailedException sfe) {
Log.e(TAG, "Failed to subscribe to datasets", sfe);
} catch (AmazonClientException ace) {
Log.e(TAG, "An unknown error caused the subscription to fail", ace);
}
}
```
In your implementation of the [Android BroadcastReceiver](http://developer.android.com/reference/android/content/BroadcastReceiver.html) object, you can check the latest version of the modified dataset and decide if your app needs to synchronize again:
```
@Override
public void onReceive(Context context, Intent intent) {
PushSyncUpdate update = client.getPushSyncUpdate(intent);
// The update has the source (cognito-sync here), identityId of the
// user, identityPoolId in question, the non-local sync count of the
// data set and the name of the dataset. All are accessible through
// relevant getters.
String source = update.getSource();
String identityPoolId = update.getIdentityPoolId();
String identityId = update.getIdentityId();
String datasetName = update.getDatasetName;
long syncCount = update.getSyncCount;
Dataset dataset = client.openOrCreateDataset(datasetName);
// need to access last sync count. If sync count is less or equal to
// last sync count of the dataset, no sync is required.
long lastSyncCount = dataset.getLastSyncCount();
if (lastSyncCount < syncCount) {
dataset.synchronize(new SyncCallback() {
// ...
});
}
}
```
The following keys are available in the push notification payload:
+ `source`: cognito-sync. This can serve as a differentiating factor between notifications.
+ `identityPoolId`: The identity pool ID. This can be used for validation or additional information, though it's not integral from the receiver's point of view.
+ `identityId`: The identity ID within the pool.
+ `datasetName`: The name of the dataset that was updated. This is available for the sake of the openOrCreateDataset call.
+ `syncCount`: The sync count for the remote dataset. You can use this as a way to make sure that the local dataset is out of date, and that the incoming synchronization is new.
## Use push sync in your app: iOS - Objective-C
To obtain a device token for your app, follow the Apple documentation on Registering for Remote Notifications. Once you've received the device token as an NSData object from APNs, you'll need to register the device with Amazon Cognito using the `registerDevice:` method of the sync client, as shown below:
```
AWSCognito *syncClient = [AWSCognito defaultCognito];
[[syncClient registerDevice: devToken] continueWithBlock:^id(AWSTask *task) {
if(task.error){
NSLog(@"Unable to registerDevice: %@", task.error);
} else {
NSLog(@"Successfully registered device with id: %@", task.result);
}
return nil;
}
];
```
In debug mode, your device will register with the APNs sandbox; in release mode, it will register with APNs. To receive updates from a particular dataset, use the `subscribe` method:
```
[[[syncClient openOrCreateDataset:@"MyDataset"] subscribe] continueWithBlock:^id(AWSTask *task) {
if(task.error){
NSLog(@"Unable to subscribe to dataset: %@", task.error);
} else {
NSLog(@"Successfully subscribed to dataset: %@", task.result);
}
return nil;
}
];
```
To stop receiving push notifications from a dataset, simply call the `unsubscribe` method:
```
[[[syncClient openOrCreateDataset:@”MyDataset”] unsubscribe] continueWithBlock:^id(AWSTask *task) {
if(task.error){
NSLog(@"Unable to unsubscribe from dataset: %@", task.error);
} else {
NSLog(@"Successfully unsubscribed from dataset: %@", task.result);
}
return nil;
}
];
```
To subscribe to all datasets in the `AWSCognito` object, call `subscribeAll`:
```
[[syncClient subscribeAll] continueWithBlock:^id(AWSTask *task) {
if(task.error){
NSLog(@"Unable to subscribe to all datasets: %@", task.error);
} else {
NSLog(@"Successfully subscribed to all datasets: %@", task.result);
}
return nil;
}
];
```
Before calling `subscribeAll`, be sure to synchronize at least once on each dataset, so that the datasets exist on the server.
To react to push notifications, you need to implement the `didReceiveRemoteNotification` method in your app delegate:
```
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
{
[[NSNotificationCenter defaultCenter] postNotificationName:@"CognitoPushNotification" object:userInfo];
}
```
If you post a notification using notification handler, you can then respond to the notification elsewhere in the application where you have a handle to your dataset. If you subscribe to the notification like this ...
```
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(didReceivePushSync:)
name: :@"CognitoPushNotification" object:nil];
```
...you can act on the notification like this:
```
- (void)didReceivePushSync:(NSNotification*)notification
{
NSDictionary * data = [(NSDictionary *)[notification object] objectForKey:@"data"];
NSString * identityId = [data objectForKey:@"identityId"];
NSString * datasetName = [data objectForKey:@"datasetName"];
if([self.dataset.name isEqualToString:datasetName] && [self.identityId isEqualToString:identityId]){
[[self.dataset synchronize] continueWithBlock:^id(AWSTask *task) {
if(!task.error){
NSLog(@"Successfully synced dataset");
}
return nil;
}];
}
}
```
The following keys are available in the push notification payload:
+ `source`: cognito-sync. This can serve as a differentiating factor between notifications.
+ `identityPoolId`: The identity pool ID. This can be used for validation or additional information, though it's not integral from the receiver's point of view.
+ `identityId`: The identity ID within the pool.
+ `datasetName`: The name of the dataset that was updated. This is available for the sake of the `openOrCreateDataset` call.
+ `syncCount`: The sync count for the remote dataset. You can use this as a way to make sure that the local dataset is out of date, and that the incoming synchronization is new.
## Use push sync in your app: iOS - Swift
To obtain a device token for your app, follow the Apple documentation on Registering for Remote Notifications. Once you've received the device token as an NSData object from APNs, you'll need to register the device with Amazon Cognito using the registerDevice: method of the sync client, as shown below:
```
let syncClient = AWSCognito.default()
syncClient.registerDevice(devToken).continueWith(block: { (task: AWSTask!) -> AnyObject! in
if (task.error != nil) {
print("Unable to register device: " + task.error.localizedDescription)
} else {
print("Successfully registered device with id: \(task.result)")
}
return task
})
```
In debug mode, your device will register with the APNs sandbox; in release mode, it will register with APNs. To receive updates from a particular dataset, use the `subscribe` method:
```
syncClient.openOrCreateDataset("MyDataset").subscribe().continueWith(block: { (task: AWSTask!) -> AnyObject! in
if (task.error != nil) {
print("Unable to subscribe to dataset: " + task.error.localizedDescription)
} else {
print("Successfully subscribed to dataset: \(task.result)")
}
return task
})
```
To stop receiving push notifications from a dataset, call the `unsubscribe` method:
```
syncClient.openOrCreateDataset("MyDataset").unsubscribe().continueWith(block: { (task: AWSTask!) -> AnyObject! in
if (task.error != nil) {
print("Unable to unsubscribe to dataset: " + task.error.localizedDescription)
} else {
print("Successfully unsubscribed to dataset: \(task.result)")
}
return task
})
```
To subscribe to all datasets in the `AWSCognito` object, call `subscribeAll`:
```
syncClient.openOrCreateDataset("MyDataset").subscribeAll().continueWith(block: { (task: AWSTask!) -> AnyObject! in
if (task.error != nil) {
print("Unable to subscribe to all datasets: " + task.error.localizedDescription)
} else {
print("Successfully subscribed to all datasets: \(task.result)")
}
return task
})
```
Before calling `subscribeAll`, be sure to synchronize at least once on each dataset, so that the datasets exist on the server.
To react to push notifications, you need to implement the `didReceiveRemoteNotification` method in your app delegate:
```
func application(application: UIApplication, didReceiveRemoteNotification userInfo: [NSObject : AnyObject],
fetchCompletionHandler completionHandler: (UIBackgroundFetchResult) -> Void) {
NSNotificationCenter.defaultCenter().postNotificationName("CognitoPushNotification", object: userInfo)
})
```
If you post a notification using notification handler, you can then respond to the notification elsewhere in the application where you have a handle to your dataset. If you subscribe to the notification like this ...
```
NSNotificationCenter.defaultCenter().addObserver(observer:self,
selector:"didReceivePushSync:",
name:"CognitoPushNotification",
object:nil)
```
...you can act on the notification like this:
```
func didReceivePushSync(notification: NSNotification) {
if let data = (notification.object as! [String: AnyObject])["data"] as? [String: AnyObject] {
let identityId = data["identityId"] as! String
let datasetName = data["datasetName"] as! String
if self.dataset.name == datasetName && self.identityId == identityId {
dataset.synchronize().continueWithBlock {(task) -> AnyObject! in
if task.error == nil {
print("Successfully synced dataset")
}
return nil
}
}
}
}
```
The following keys are available in the push notification payload:
+ `source`: cognito-sync. This can serve as a differentiating factor between notifications.
+ `identityPoolId`: The identity pool ID. This can be used for validation or additional information, though it's not integral from the receiver's point of view.
+ `identityId`: The identity ID within the pool.
+ `datasetName`: The name of the dataset that was updated. This is available for the sake of the `openOrCreateDataset` call.
+ `syncCount`: The sync count for the remote dataset. You can use this as a way to make sure that the local dataset is out of date, and that the incoming synchronization is new.
# Implementing Amazon Cognito Sync streams
****
If you're new to Amazon Cognito Sync, use [AWS AppSync](https://aws.amazon.com/appsync/). Like Amazon Cognito Sync, AWS AppSync is a service for synchronizing application data across devices.
It enables user data like app preferences or game state to be synchronized. It also extends these capabilities by allowing multiple users to synchronize and collaborate in real time on shared data.
Amazon Cognito Streams gives developers control and insight into their data stored in Amazon Cognito. Developers can now configure a Kinesis stream to receive events as data is updated and synchronized. Amazon Cognito can push each dataset change to a Kinesis stream you own in real time.
Using Amazon Cognito Streams, you can move all of your Sync data to Kinesis, which can then be streamed to a data warehouse tool such as Amazon Redshift for further analysis. To learn more about Kinesis, see [Getting Started Using Amazon Kinesis](https://docs.aws.amazon.com/kinesis/latest/dev/getting-started.html).
**Configuring streams**
You can set up Amazon Cognito Streams in the Amazon Cognito console. To enable Amazon Cognito Streams in the Amazon Cognito console, you need to select the Kinesis stream to publish to and an IAM role that grants Amazon Cognito permission to put events in the selected stream.
From the [console home page](https://console.aws.amazon.com/cognito/home):
1. Click the name of the identity pool for which you want to set up Amazon Cognito Streams. The **Dashboard** page for your identity pool appears.
1. In the top-right corner of the **Dashboard** page, click **Manage Identity Pools**. The Manage Federated Identities page appears.
1. Scroll down and click **Cognito Streams** to expand it.
1. In the **Stream name** dropdown menu, select the name of an existing Kinesis stream. Alternatively, click **Create stream** to create one, entering a stream name and the number of shards. To learn about shards and for help on estimating the number of shards needed for your stream, see the [Kinesis Developer Guide](https://docs.aws.amazon.com/kinesis/latest/dev/amazon-kinesis-streams.html).
1. In the **Publish role** dropdown menu, select the IAM role that grants Amazon Cognito permission to publish your stream. Click **Create role** to create or modify the roles associated with your identity pool in the [AWS IAM Console](https://console.aws.amazon.com/iam/home).
1. In the **Stream status** dropdown menu, select **Enabled** to enable the stream updates. Click **Save Changes**.
After you've successfully configured Amazon Cognito streams, all subsequent updates to datasets in this identity pool will be sent to the stream.
**Stream contents**
Each record sent to the stream represents a single synchronization. Here is an example of a record sent to the stream:
```
{
"identityPoolId": "Pool Id",
"identityId": "Identity Id",
"dataSetName": "Dataset Name",
"operation": "(replace|remove)",
"kinesisSyncRecords": [
{
"key": "Key",
"value": "Value",
"syncCount": 1,
"lastModifiedDate": 1424801824343,
"deviceLastModifiedDate": 1424801824343,
"op": "(replace|remove)"
},
...
],
"lastModifiedDate": 1424801824343,
"kinesisSyncRecordsURL": "S3Url",
"payloadType": "(S3Url|Inline)",
"syncCount": 1
}
```
For updates that are larger than the Kinesis maximum payload size of 1 MB, Amazon Cognito incudes a presigned Amazon S3 URL that contains the full contents of the update.
After you have configured Amazon Cognito streams, if you delete the Kinesis stream or change the role trust permission so that Amazon Cognito Sync can no longer assume the role, you turn off the Amazon Cognito streams. You must either recreate the Kinesis stream or fix the role, and then you must turn on the stream again.
**Bulk publishing**
Once you have configured Amazon Cognito streams, you will be able to execute a bulk publish operation for the existing data in your identity pool. After you initiate a bulk publish operation, either via the console or directly via the API, Amazon Cognito will start publishing this data to the same stream that is receiving your updates.
Amazon Cognito does not guarantee uniqueness of data sent to the stream when using the bulk publish operation. You may receive the same update both as an update as well as part of a bulk publish. Keep this in mind when processing the records from your stream.
To bulk publish all of your streams, follow steps 1-6 under Configuring Streams and then click Start bulk publish. You are limited to one ongoing bulk publish operation at any given time and to one successful bulk publish request every 24 hours.
# Customizing workflows with Amazon Cognito Events
****
If you're new to Amazon Cognito Sync, use [AWS AppSync](https://aws.amazon.com/appsync/). Like Amazon Cognito Sync, AWS AppSync is a service for synchronizing application data across devices.
It enables user data like app preferences or game state to be synchronized. It also extends these capabilities by allowing multiple users to synchronize and collaborate in real time on shared data.
Amazon Cognito Events allows you to execute an AWS Lambda function in response to important events in Amazon Cognito. Amazon Cognito raises the Sync Trigger event when a dataset is synchronized. You can use the Sync Trigger event to take an action when a user updates data. The function can evaluate and optionally manipulate the data before it is stored in the cloud and synchronized to the user's other devices. This is useful to validate data coming from the device before it is synchronized to the user's other devices, or to update other values in the dataset based on incoming data such as issuing an award when a player reaches a new level.
The steps below will guide you through setting up a Lambda function that executes each time a Amazon Cognito Dataset is synchronized.
**Note**
When using Amazon Cognito events, you can only use the credentials obtained from Amazon Cognito Identity. If you have an associated Lambda function, but you call `UpdateRecords` with AWS account credentials (developer credentials), your Lambda function will not be invoked.
**Creating a function in AWS Lambda**
To integrate Lambda with Amazon Cognito, you first need to create a function in Lambda. To do so:
**Selecting the Lambda Function in Amazon Cognito**
1. Open the Lambda console.
1. Click Create a Lambda function.
1. On the Select blueprint screen, search for and select "cognito-sync-trigger."
1. On the Configure event sources screen, leave the Event source type set to "Cognito Sync Trigger" and select your identity pool. Click Next.
**Note**
When configuring a Amazon Cognito Sync trigger outside of the console, you must add Lambda resource-based permissions to allow Amazon Cognito to invoke the function. You can add this permission from the Lambda console (see [Using resource-based policies for AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)) or by using the Lambda [AddPermission](https://docs.aws.amazon.com/lambda/latest/dg/API_AddPermission.html) operation.
**Example Lambda Resource-Based Policy**
The following AWS Lambda resource-based policy grants Amazon Cognito a limited ability to invoke a Lambda function. Amazon Cognito can only invoke the function on behalf of the identity pool in the `aws:SourceArn` condition and the account in the `aws:SourceAccount` condition.
****
```
{
"Version":"2012-10-17",
"Id": "default",
"Statement": [
{
"Sid": "lambda-allow-cognito-my-function",
"Effect": "Allow",
"Principal": {
"Service": "cognito-sync.amazonaws.com"
},
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:us-east-1:111122223333:function:MyFunction",
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "111122223333"
},
"ArnLike": {
"AWS:SourceArn": "arn:aws:cognito-identity:us-east-1:111122223333:identitypool/us-east-1:abcdefg-1234-5678-910a-0e8443553f95"
}
}
}
]
}
```
1. On the Configure function screen, enter a name and description for your function. Leave Runtime set to "Node.js." Leave the code unchanged for our example. The default example makes no changes to the data being synced. It only logs the fact that the Amazon Cognito Sync Trigger event occurred. Leave Handler name set to "index.handler." For Role, select an IAM role that grants your code permission to access AWS Lambda. To modify roles, see the IAM console. Leave Advanced settings unchanged. Click Next.
1. On the Review screen, review the details and click Create function. The next page displays your new Lambda function.
Now that you have an appropriate function written in Lambda, you need to choose that function as the handler for the Amazon Cognito Sync Trigger event. The steps below walk you through this process.
From the console home page:
1. Click the name of the identity pool for which you want to set up Amazon Cognito Events. The Dashboard page for your identity pool appears.
1. In the top-right corner of the Dashboard page, click Manage Federated Identities. The Manage Federated Identities page appears.
1. Scroll down and click Cognito Events to expand it.
1. In the Sync Trigger dropdown menu, select the Lambda function that you want to trigger when a Sync event occurs.
1. Click Save Changes.
Now, your Lambda function will be executed each time a dataset is synchronized. The next section explains how you can read and modify the data in your function as it is being synchronized.
**Writing a Lambda function for sync triggers**
Sync triggers follow the programming pattern that service provider interfaces use. Amazon Cognito provides input to your Lambda function in the following JSON format.
```
{
"version": 2,
"eventType": "SyncTrigger",
"region": "us-east-1",
"identityPoolId": "identityPoolId",
"identityId": "identityId",
"datasetName": "datasetName",
"datasetRecords": {
"SampleKey1": {
"oldValue": "oldValue1",
"newValue": "newValue1",
"op": "replace"
},
"SampleKey2": {
"oldValue": "oldValue2",
"newValue": "newValue2",
"op": "replace"
},..
}
}
```
Amazon Cognito expects the return value of the function to have the same format as the input.
When you write functions for the Sync Trigger event, observe the following:
+ When Amazon Cognito calls your Lambda function during UpdateRecords, the function must respond within 5 seconds. If it doesn't, the Amazon Cognito Sync service generates a `LambdaSocketTimeoutException` exception. You can't increase this timeout value.
+ If you get a `LambdaThrottledException` exception, try the sync operation again to update the records.
+ Amazon Cognito provides all the records present in the dataset as input to the function.
+ Records that the app user updates have the `op` field set as `replace`. The deleted records have `op` field set as `remove`.
+ You can modify any record, even if the app user doesn't update the record.
+ All the fields except the datasetRecords are read-only. Do not change them. If you change these fields, you can't update the records.
+ To modify the value of a record, update the value and set the `op` to `replace`.
+ To remove a record, either set the `op` to `remove`, or set the value to null.
+ To add a record, add a new record to the datasetRecords array.
+ Amazon Cognito ignores any omitted record in the response when Amazon Cognitoupdates the record.
**Sample Lambda function**
The following sample Lambda function shows how to access, modify and remove the data.
```
console.log('Loading function');
exports.handler = function(event, context) {
console.log(JSON.stringify(event, null, 2));
//Check for the event type
if (event.eventType === 'SyncTrigger') {
//Modify value for a key
if('SampleKey1' in event.datasetRecords){
event.datasetRecords.SampleKey1.newValue = 'ModifyValue1';
event.datasetRecords.SampleKey1.op = 'replace';
}
//Remove a key
if('SampleKey2' in event.datasetRecords){
event.datasetRecords.SampleKey2.op = 'remove';
}
//Add a key
if(!('SampleKey3' in event.datasetRecords)){
event.datasetRecords.SampleKey3={'newValue':'ModifyValue3', 'op' : 'replace'};
}
}
context.done(null, event);
};
```