{"id":16945,"library":"amplify-category-analytics","title":"Amplify CLI Analytics Plugin","description":"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.","status":"active","version":"4.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/aws-amplify/amplify-cli","tags":["javascript","amplify","aws","typescript"],"install":[{"cmd":"npm install amplify-category-analytics","lang":"bash","label":"npm"},{"cmd":"yarn add amplify-category-analytics","lang":"bash","label":"yarn"},{"cmd":"pnpm add amplify-category-analytics","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin designed to extend the functionality of the Amplify CLI, requiring the CLI to operate.","package":"@aws-amplify/cli","optional":false}],"imports":[],"quickstart":{"code":"nvm install 20 # Ensure Node.js v20+ for Amplify CLI v14+\nnpm install -g @aws-amplify/cli@latest\n\namplify configure # Set up your AWS credentials if not already done\n\nmkdir my-amplify-analytics-app\ncd my-amplify-analytics-app\n\namplify init \\\n  --amplify-config '{\"projectName\":\"myAnalyticsApp\",\"envName\":\"dev\",\"defaultEditor\":\"code\"}' \\\n  --frontend 'javascript' \\\n  --framework 'react' \\\n  --provider 'awscloudformation'\n\namplify add analytics\n# Follow the CLI prompts:\n# ? Select an Analytics provider: Amazon Pinpoint (or Kinesis if preferred)\n# ? Provide your pinpoint resource name: myAnalyticsAppPinpoint\n# ? 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\n\namplify push\n# Confirm the changes: ? Are you sure you want to continue? Yes\n# The CLI will provision the backend resources, including Pinpoint/Kinesis and associated IAM roles.","lang":"bash","description":"Demonstrates initializing an Amplify project and adding analytics via the CLI."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=13.0.0"},{"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]","message":"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.","severity":"breaking","affected_versions":">=4.0.0 (for client-side library integration)"},{"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]","message":"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.","severity":"gotcha","affected_versions":">=1.0.0 (all versions relying on Pinpoint)"},{"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]","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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]","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The IAM role used by your application (typically an unauthenticated Cognito Identity Pool role) lacks necessary permissions to interact with Amazon Pinpoint endpoints.","error":"User is not authorized to perform: mobiletargeting:UpdateEndpoints"},{"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.","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.","error":"Pinpoint project with ID '...' does not exist"},{"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.","cause":"Backend provisioning failed during `amplify push` due to CloudFormation template errors, resource conflicts, or invalid configurations in the local `amplify/backend/analytics` directory.","error":"amplify push failed (analytics category errors in CloudFormation)"},{"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]","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.","error":"Analytics events not showing in Amazon Pinpoint console"}],"ecosystem":"npm","meta_description":null}