Using Amazon Pinpoint analytics with Amazon Cognito user pools

Amazon Cognito user pools are integrated with Amazon Pinpoint to provide analytics for Amazon Cognito user pools and to enrich the user data for Amazon Pinpoint campaigns. Amazon Pinpoint provides analytics and targeted campaigns to drive user engagement in mobile apps using push notifications. With Amazon Pinpoint analytics support in Amazon Cognito user pools, you can track user pool sign-ups, sign-ins, failed authentications, daily active users (DAUs), and monthly active users (MAUs) in the Amazon Pinpoint console. You can drill into the data for different date ranges or attributes, such as device platform, device locale, and app version.

You can also set up custom attributes for your app. Those can then be used to segment your users on Amazon Pinpoint and send them targeted push notifications. If you choose Share user attribute data with Amazon Pinpoint in the Analytics tab in the Amazon Cognito console, Amazon Pinpoint creates additional endpoints for user email addresses and phone numbers.

When you activate Amazon Pinpoint analytics in your user pool with the Amazon Cognito console, you also create a service-linked role that Amazon Cognito assumes when it makes an API request to Amazon Pinpoint for your user pool. The IAM principal that adds your analytics configuration must have CreateServiceLinkedRole permissions. The service-linked role is AWSServiceRoleForAmazonCognitoIdp. For more information, see Using service-linked roles for Amazon Cognito.

When you apply an AnalyticsConfiguration to your app client in the Amazon Cognito API, you can assign a custom IAM role for Amazon Pinpoint and an external ID to assume the role. The role must trust the cognito-idp service principal, and if the role trust policy requires an external ID, it must match your AnalyticsConfiguration. You must grant the role cognito-idp:Describe* permissions, and the following permissions for your Amazon Pinpoint project.

• mobiletargeting:UpdateEndpoint

• mobiletargeting:PutEvents

Amazon Cognito and Amazon Pinpoint Region availability

The following table shows the AWS Region mappings between Amazon Cognito and Amazon Pinpoint that meet one of the following conditions.

• You can only use an Amazon Pinpoint project in the US East (N. Virginia) (us-east-1) Region.

• You can use an Amazon Pinpoint project in the same Region or in the US East (N. Virginia) (us-east-1) Region

By default, Amazon Cognito can only send analytics to a Amazon Pinpoint project in the same AWS Region. The exceptions to this rule are the Regions in the following table, and Regions where Amazon Pinpoint in unavailable.

Note

Amazon Pinpoint isn't available in Europe (Milan) and Middle East (Bahrain). Amazon Cognito user pools in these Regions don't support analytics.

The table shows the relation between the Region where you built your Amazon Cognito user pool and the corresponding Region in Amazon Pinpoint. You must configure your Amazon Pinpoint project in an available Region to integrate it with Amazon Cognito.

Amazon Cognito user pool Region	Region for Amazon Pinpoint project
ap-northeast-1	us-east-1
ap-northeast-2	us-east-1
ap-south-1	us-east-1, ap-south-1
ap-southeast-1	us-east-1
ap-southeast-2	us-east-1, ap-southeast-2
ca-central-1	us-east-1
eu-central-1	us-east-1, eu-central-1
eu-west-1	us-east-1, eu-west-1
eu-west-2	us-east-1
us-east-1	us-east-1
us-east-2	us-east-1
us-west-2	us-east-1, us-west-2

Region mapping examples

• If you create a user pool in ap-northeast-1, you can create your Amazon Pinpoint project in us-east-1.

• If you create a user pool in ap-south-1, you can create your Amazon Pinpoint project in either us-east-1 or ap-south-1.

Note

For all AWS Regions except those in the preceding table, Amazon Cognito can only use an Amazon Pinpoint project in the same Region as your user pool. If Amazon Pinpoint isn't available in the Region where you built your user pool, and it's not listed in the table, then Amazon Cognito doesn't support Amazon Pinpoint analytics in that Region. For detailed AWS Region information, see Amazon Pinpoint endpoints and quotas.

Specifying Amazon Pinpoint analytics settings (AWS Management Console)

You can configure your Amazon Cognito user pool to send analytics data to Amazon Pinpoint. Amazon Cognito only sends analytics data to Amazon Pinpoint for local users. After you configure your user pool to associate with a Amazon Pinpoint project, you must include AnalyticsMetadata in your API requests. For more information, see Integrating your app with Amazon Pinpoint.

To specify analytics settings

1. Go to the Amazon Cognito console. You might be prompted for your AWS credentials.

2. Select User Pools and choose an existing user pool from the list.

3. Choose the App integration tab.

4. Under App clients and analytics, choose an existing App client name from the list.

5. Under Pinpoint analytics, choose Enable.

6. Choose a Pinpoint Region.

7. Choose an Amazon Pinpoint project or select Create Amazon Pinpoint project.

   Note

   The Amazon Pinpoint project ID is a 32-character string that is unique to your Amazon Pinpoint project. It is listed in the Amazon Pinpoint console.

   You can map multiple Amazon Cognito apps to a single Amazon Pinpoint project. However, each Amazon Cognito app can only be mapped to one Amazon Pinpoint project.

   In Amazon Pinpoint, each project should be a single app. For example, if a game developer has two games, each game should be a separate Amazon Pinpoint project, even if both games use the same Amazon Cognito user pool. For more information on Amazon Pinpoint projects, see Create a project in Amazon Pinpoint.

8. Under User data sharing, choose Share user data with Amazon Pinpoint if you want Amazon Cognito to send email addresses and phone numbers to Amazon Pinpoint and create additional endpoints for users. After your users verify their email address and phone number, Amazon Cognito only shares them with Amazon Pinpoint if they are available to the user account.

   Note

   An endpoint uniquely identifies a user device to which you can send push notifications with Amazon Pinpoint. For more information about endpoints, see Adding endpoints in the Amazon Pinpoint Developer Guide.

9. Choose Save changes.

Specifying Amazon Pinpoint analytics settings (AWS CLI and AWS API)

Use the following commands to specify Amazon Pinpoint analytics settings for your user pool.

To specify the analytics settings for your user pool's existing client app at app creation time

• AWS CLI: aws cognito-idp create-user-pool-client

• AWS API: CreateUserPoolClient

To update the analytics settings for your user pool's existing client app

• AWS CLI: aws cognito-idp update-user-pool-client

• AWS API: UpdateUserPoolClient

Note

Amazon Cognito supports in-Region integrations when you use ApplicationArn

Integrating your app with Amazon Pinpoint

You can publish analytics metadata to Amazon Pinpoint for Amazon Cognito local users in the user pools API.

Local users

Users who signed up for an account or were created in your user pool instead of signing in through a third-party identity provider (IdP).

User pools API

The operations that you can integrate with an AWS SDK, using an app with a custom user interface (UI). You can't pass analytics metadata for federated or local users who sign in through the hosted UI. See the Amazon Cognito API Reference for a list of user pools API operations.

After you configure your user pool to publish to a campaign, Amazon Cognito passes metadata to Amazon Pinpoint for the following API operations.

• AdminInitiateAuth

• AdminRespondToAuthChallenge

• ConfirmForgotPassword

• ConfirmSignUp

• ForgotPassword

• InitiateAuth

• ResendConfirmationCode

• RespondToAuthChallenge

• SignUp

To pass metadata about your user's session to your Amazon Pinpoint campaign, include an AnalyticsEndpointId value in the AnalyticsMetadata parameter of your API request. For a JavaScript example, see Why aren't my Amazon Cognito user pool analytics appearing on my Amazon Pinpoint dashboard? in the AWS Knowledge Center.