Amazon Cognito Events - Amazon Cognito
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon Cognito Events

If you're new to Amazon Cognito Sync, use Amazon AppSync. Like Amazon Cognito Sync, Amazon 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 Amazon 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 Amazon account credentials (developer credentials), your Lambda function will not be invoked.

Creating a function in Amazon 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.

  2. Click Create a Lambda function.

  3. On the Select blueprint screen, search for and select "cognito-sync-trigger."

  4. 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 Amazon Lambda) or by using the Lambda AddPermission operation.

    Example Lambda Resource-Based Policy

    The following Amazon 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": "<your Lambda function ARN>",
            "Condition": {
                "StringEquals": {
                    "AWS:SourceAccount": "<your account number>"
                },
                "ArnLike": {
                    "AWS:SourceArn": "<your identity pool ARN>"
                }
            }
        }
    ]
}

  5. 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 Amazon Lambda. To modify roles, see the IAM console. Leave Advanced settings unchanged. Click Next.

  6. 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.

  2. In the top-right corner of the Dashboard page, click Manage Federated Identities. The Manage Federated Identities page appears.

  3. Scroll down and click Cognito Events to expand it.

  4. In the Sync Trigger dropdown menu, select the Lambda function that you want to trigger when a Sync event occurs.

  5. 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);
};