AWS Mobile Blog

Introducing Amazon Cognito Events: Sync Triggers

by Rachit Dhall | on | | Comments

In 2014 we launched Amazon Cognito, a service that makes it easy to save user data, such as app preferences or game state, in the AWS Cloud without writing any backend code or managing any infrastructure. User data is available while the device is offline and is synchronized across a user’s devices so that their app experience is consistent regardless of the device they use.

Today we are launching Amazon Cognito Events, which will allow you to run an AWS Lambda function in response to important events in Amazon Cognito. The first event that we’re launching is the Sync Trigger event, which runs each time a dataset is synchronized. By using this feature you can evaluate and manipulate data before it is stored in the cloud and synchronized back to the user’s devices.

You can use this feature in a number of different use cases, such as:

  1. Data Validation and Manipulation: Developers can add, modify, or ignore data in real time before it is synchronized back to the cloud and other devices.
  2. Awards & Promotions: Developers can now issue rewards based on a player’s score in real time. Apps may issue a "badge" when the user has a high level of engagement with the app or uses advanced features without the need of app resubmission.
  3. Prevent cheating: Verify the data before it makes into the cloud to check for any malicious or abnormal activity.

Writing Lambda Functions for Sync Triggers

Sync triggers follow the Service Provider Interface programming paradigm. Amazon Cognito will provide input in the following JSON format to your Lambda function.

{
  "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 Lambda function to be in the same format as the input.  A complete example is provided below.

Some key points to keep in mind writing Lambda functions for the Sync Trigger event:

  1. Amazon Cognito will provide all the records present in the dataset as input to the Lambda function.
  2. Records updated by the app user will have the ‘op’ field set as “replace” and the records deleted will have ‘op’ field as “remove”.
  3. You can modify any record, even if it was not updated by the app user.
  4. All the fields except the datasetRecords are read only and should not be changed. Changing these fields will result in a failure to update the records.
  5. To modify the value of a record, simply update the value and set the ‘op’ to “replace”.
  6. To remove a record, either set the ‘op’ to remove or set the value to null.
  7. To add a record, simply add a new record to the datasetRecords array.
  8. Any omitted record in the response will be ignored for the update.

Sample Lambda Function

Here is a sample Lambda function showing 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);
};

Configuring Amazon Cognito Events

Once you create a Lambda function using the AWS Lambda console, you can associate it with an identity pool from the Edit identity pool screen on the Amazon Cognito console. In the Cognito Events section, select the Lambda function to be invoked for the Sync Trigger event from the dropdown.

We have also updated our AWS Mobile SDKs for Android and iOS to use Amazon Cognito events. You can use our Android or iOS sample apps to test this feature.

Conclusion

Amazon Cognito Events gives you complete control over the data saved by app users in the cloud. We’d love to hear how you plan to use this feature in your applications, so please feel free to leave a comment and share your plans.

If you encounter any issues or have further comments or questions, please visit our forums and we’ll be happy to assist you.