Registry / aws / amplify-category-analytics

amplify-category-analytics

library4.4.2jsnpmunverified

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.

aws

npm install amplify-category-analytics

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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.

Debug

Known issues

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

affects: >=13.0.0

breakingThe 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]

affects: >=4.0.0 (for client-side library integration)

gotchaAmazon 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]

affects: >=1.0.0 (all versions relying on Pinpoint)

gotchaIncorrectly 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]

affects: >=1.0.0

gotchaBackend 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]

affects: >=1.0.0

Errors

Common errors & fixes

User is not authorized to perform: mobiletargeting:UpdateEndpoints

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

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)

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

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]

Upgrade

Version history

4.4.2latest on PyPI

Audit

Dependencies

@aws-amplify/clirequiredThis package is a plugin designed to extend the functionality of the Amplify CLI, requiring the CLI to operate.

Agent activity

52 hits · last 30 days

node

ahrefsbot

claudebot

mj12bot