Amplify CLI Analytics Plugin

4.4.2 · active · verified Wed Apr 22

This package is an internal plugin for the AWS Amplify Command Line Interface (CLI) that enables developers to integrate analytics capabilities into their full-stack applications. It simplifies the provisioning and management of AWS analytics services, primarily Amazon Pinpoint and (for the Amplify JavaScript library) Amazon Kinesis, within an Amplify project. As of `npm@4.4.2`, it operates within the larger `@aws-amplify/cli` ecosystem, which is currently at `v14.3.0`. The Amplify CLI project maintains a frequent release cadence, with various component packages receiving updates multiple times per month. Key differentiators include its deep integration with the Amplify ecosystem, providing a streamlined, guided CLI workflow for adding, updating, and removing analytics backend resources, abstracting away direct AWS SDK calls or complex CloudFormation template management for user engagement and tracking services. It leverages Cognito Identity Pools for user identification, supporting both authenticated and unauthenticated analytics data collection.

Common errors

```
User is not authorized to perform: mobiletargeting:UpdateEndpoints
```
cause The IAM role used by your application (typically an unauthenticated Cognito Identity Pool role) lacks necessary permissions to interact with Amazon Pinpoint endpoints.

fix In the AWS IAM console, locate the role associated with your Cognito Identity Pool's unauthenticated users. Add a policy that grants `mobiletargeting:PutEvents` and `mobiletargeting:UpdateEndpoints` permissions to the Pinpoint resource.
```
Pinpoint project with ID '...' does not exist
```
cause The Pinpoint project referenced in your `amplifyconfiguration.json` or `aws-exports.js` either doesn't exist, was deleted, or the Amplify CLI is configured for the wrong AWS region where the project resides.

fix Verify the Pinpoint project ID and AWS region in your `amplifyconfiguration.json` (or `aws-exports.js`) match an existing Pinpoint project in the correct region in the AWS Pinpoint console. If deleted, you may need to `amplify remove analytics` and `amplify add analytics` again.
```
amplify push failed (analytics category errors in CloudFormation)
```
cause Backend provisioning failed during `amplify push` due to CloudFormation template errors, resource conflicts, or invalid configurations in the local `amplify/backend/analytics` directory.

fix Check the detailed CloudFormation events in the AWS CloudFormation console for the specific Amplify stack (e.g., `amplify-yourappname-dev-xxxxxx-analytics`). The events will provide more specific error messages to diagnose misconfigurations or conflicts. Correct the issues in your local `amplify/backend/analytics` files and try `amplify push` again.
```
Analytics events not showing in Amazon Pinpoint console
```
cause Client-side configuration might be missing or incorrect (e.g., `Amplify.configure` not called), events are not being recorded using the Amplify JavaScript library, or there are network issues preventing event submission.

fix Ensure `Amplify.configure` is called early in your application's lifecycle with the correct configuration object (`amplifyconfiguration.json`). Verify that `record` events are being triggered in your client-side code and check the browser's developer console for any errors or network request failures to Pinpoint endpoints. Confirm the IAM roles have `mobiletargeting:PutEvents` permission. [2, 7]

Warnings

breaking Amplify CLI versions 13.0.0 and above, which include this plugin, mandate Node.js 22 or later. Older Node.js versions (e.g., 18 and below) are no longer supported and will cause build or deployment failures.
Fix: Upgrade your Node.js environment to version 22 or later. Use `nvm install 22 && nvm use 22` or a similar tool to manage Node.js versions.
breaking The AWS Amplify JavaScript Library v6 introduced significant breaking changes to Analytics APIs, including the removal of `startSession`, making `record` synchronous, and determining the provider via import path. While this package handles backend provisioning, developers integrating client-side analytics must update their application code to use the new `aws-amplify/analytics` API patterns.
Fix: Refer to the Amplify JavaScript Library v6 migration guide for Analytics. Update client-side imports and API calls, e.g., use `import { record } from 'aws-amplify/analytics'` and adapt to synchronous `record` calls and the `_session.start` event for session tracking. [25]
gotcha Amazon Pinpoint, a primary analytics provider for Amplify, will end support on October 30, 2026, and ceased accepting new users as of May 20. New Amplify projects should consider using Amazon Kinesis for event collection or explore alternative AWS services for comprehensive messaging/campaign solutions.
Fix: For new projects, evaluate Kinesis for event collection when adding analytics. For existing Pinpoint users, review AWS migration guidance to transition to recommended services before October 2026. [7, 25]
gotcha Incorrectly configured IAM permissions, particularly on the authenticated and unauthenticated roles associated with your Cognito Identity Pool, are a common cause of analytics events failing to be recorded in AWS. The roles must have sufficient permissions for `mobiletargeting` or `kinesis` actions.
Fix: Inspect the IAM policies attached to your Cognito Identity Pool roles (e.g., `Cognito_YourIdentityPoolNameAuth_Role` and `Cognito_YourIdentityPoolNameUnauth_Role`) via the AWS console. Ensure they grant necessary permissions for `mobiletargeting:PutEvents`, `mobiletargeting:UpdateEndpoints`, or `kinesis:PutRecords` if using Kinesis. [2, 21]
gotcha Backend resource 'tangles' can occur where CloudFormation states become out of sync or dependencies cause issues during `amplify push` or `amplify remove`. This is particularly challenging for analytics resources due to their ties to other categories like Auth.
Fix: Before major changes or removals, back up your `amplify/backend` folder. If `amplify push` fails, examine the CloudFormation stack events in the AWS console for detailed error messages. In severe cases, manual cleanup of resources in the AWS console might be necessary, followed by re-adding the analytics category locally. [22]

Install

npm install amplify-category-analytics npm
yarn add amplify-category-analytics yarn
pnpm add amplify-category-analytics pnpm

Quickstart

Demonstrates initializing an Amplify project and adding analytics via the CLI.

nvm install 20 # Ensure Node.js v20+ for Amplify CLI v14+
npm install -g @aws-amplify/cli@latest

amplify configure # Set up your AWS credentials if not already done

mkdir my-amplify-analytics-app
cd my-amplify-analytics-app

amplify init \
  --amplify-config '{"projectName":"myAnalyticsApp","envName":"dev","defaultEditor":"code"}' \
  --frontend 'javascript' \
  --framework 'react' \
  --provider 'awscloudformation'

amplify add analytics
# Follow the CLI prompts:
# ? Select an Analytics provider: Amazon Pinpoint (or Kinesis if preferred)
# ? Provide your pinpoint resource name: myAnalyticsAppPinpoint
# ? Apps need authorization to send analytics events. Do you want to allow guests and unauthenticated users to send analytics events? (we recommend you allow this when getting started): Yes

amplify push
# Confirm the changes: ? Are you sure you want to continue? Yes
# The CLI will provision the backend resources, including Pinpoint/Kinesis and associated IAM roles.

view raw JSON →