https://github.com/th3n00bc0d3r/ngx-amplitude
`ngx-amplitude` is an Angular library that provides an easy-to-use interface for integrating [Amplitude](https://amplitude.com) analytics into your Angular 18+ standalone applications. It includes a global initialization module and a service for logging events.
https://github.com/th3n00bc0d3r/ngx-amplitude
Last synced: 5 days ago
JSON representation
`ngx-amplitude` is an Angular library that provides an easy-to-use interface for integrating [Amplitude](https://amplitude.com) analytics into your Angular 18+ standalone applications. It includes a global initialization module and a service for logging events.
- Host: GitHub
- URL: https://github.com/th3n00bc0d3r/ngx-amplitude
- Owner: th3n00bc0d3r
- Created: 2024-11-13T11:19:54.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-13T11:20:56.000Z (over 1 year ago)
- Last Synced: 2026-02-24T00:46:09.751Z (4 months ago)
- Language: HTML
- Size: 135 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- fucking-awesome-angular - ngx-amplitude - An Angular 18+ library for easy integration of 🌎 [Amplitude](amplitude.com/) analytics, with global init and event logging service. (Development Utilities / Analytics)
- awesome-angular - ngx-amplitude - An Angular 18+ library for easy integration of [Amplitude](https://amplitude.com/) analytics, with global init and event logging service. (Development Utilities / Analytics)
README
# ngx-amplitude
`ngx-amplitude` is an Angular library that provides an easy-to-use interface for integrating [Amplitude](https://amplitude.com) analytics into your Angular 18+ standalone applications. It includes a global initialization module and a service for logging events.
## Features
- **Easy Setup**: Initialize Amplitude with a single line of configuration.
- **Environment Check**: Automatically initializes Amplitude only in production environments.
- **Event Logging**: Use the `AmplitudeService` to log events with custom properties.
- **Standalone Configuration**: Supports Angular's standalone setup with a dedicated `provideAmplitude()` function.
---
## Installation
To install `ngx-amplitude` in your Angular project, run:
```bash
npm install ngx-amplitude @amplitude/analytics-browser
```
---
## Usage
### 1a. Import `AmplitudeModule` and Initialize Amplitude for Standalone
For Angular standalone applications, use the `provideAmplitude()` function to initialize Amplitude globally:
#### In `app.config.ts` or `maint.ts`:
```typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter } from '@angular/router';
import { AppComponent } from './app/app.component';
import { provideAmplitude } from 'ngx-amplitude';
bootstrapApplication(AppComponent, {
providers: [
provideRouter([]),
provideAmplitude('YOUR_API_KEY') // Replace 'YOUR_API_KEY' with your Amplitude API key
]
}).catch(err => console.error(err));
```
- **Note**: Replace `'YOUR_API_KEY'` with your actual Amplitude API key.
- **Environment Check**: The `provideAmplitude()` function ensures that Amplitude is only initialized in production mode, based on the `environment.production` setting.
---
### 1b. Import `AmplitudeModule` and Initialize Amplitude for non-standalone
Import `AmplitudeModule` in your `main.ts` file and provide your Amplitude API key:
```typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter } from '@angular/router';
import { AppComponent } from './app/app.component';
import { AmplitudeModule } from 'ngx-amplitude';
bootstrapApplication(AppComponent, {
providers: [
provideRouter([]),
AmplitudeModule.forRoot('YOUR_API_KEY') // Replace 'YOUR_API_KEY' with your Amplitude API key
]
}).catch(err => console.error(err));
```
### 2. Use `AmplitudeService` to Log Events
Inject `AmplitudeService` into your components or services and use it to log events:
```typescript
import { Component } from '@angular/core';
import { AmplitudeService } from 'ngx-amplitude';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.css'],
standalone: true,
})
export class AppComponent {
constructor(private amplitudeService: AmplitudeService) {}
trackButtonClick(): void {
this.amplitudeService.logEvent('Button Clicked', { buttonName: 'Submit' });
}
}
```
### Logging Events
- **logEvent(eventName: string, eventProperties?: Record)**:
- `eventName`: The name of the event you want to log.
- `eventProperties`: An optional object containing properties to attach to the event.
---
## Development
### Building the Library
To build the library, run:
```bash
ng build ngx-amplitude
```
### Publishing to npm
1. Navigate to the `dist/ngx-amplitude` folder:
```bash
cd dist/ngx-amplitude
```
2. Publish the library:
```bash
npm publish --access public
```
---
## Contributing
Contributions are welcome! If you have suggestions or bug reports, please open an issue or create a pull request.
---
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---
## Acknowledgments
- [Amplitude Analytics](https://amplitude.com) for providing the analytics platform.
- The Angular community for their continued support and contributions.
---
### About `provideAmplitude()`
The `provideAmplitude()` function is a custom provider designed for Angular standalone applications. It initializes Amplitude globally and conditionally, based on the `environment.production` flag.
- **Usage**: Add `provideAmplitude('YOUR_API_KEY')` to your `providers` array in `main.ts`.
- **Environment Check**: Ensures that analytics tracking is only enabled in production, preventing unnecessary data collection during development.
By using `provideAmplitude()`, you can seamlessly integrate Amplitude analytics into your Angular 18+ standalone projects with a clean and efficient setup.
---