https://github.com/cap-go/capacitor-gtm
Capacitor plugin to use google tag manager (GMT) natively
https://github.com/cap-go/capacitor-gtm
capacitor gmt ionic plugin
Last synced: about 2 months ago
JSON representation
Capacitor plugin to use google tag manager (GMT) natively
- Host: GitHub
- URL: https://github.com/cap-go/capacitor-gtm
- Owner: Cap-go
- License: mpl-2.0
- Created: 2025-07-30T04:03:27.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-01-10T18:04:41.000Z (5 months ago)
- Last Synced: 2026-01-11T00:25:24.964Z (5 months ago)
- Topics: capacitor, gmt, ionic, plugin
- Language: Swift
- Homepage: https://capgo.app
- Size: 585 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Capacitor Google Tag Manager Plugin
A Capacitor plugin for integrating Google Tag Manager into your mobile applications.
> **Note**: This plugin uses the official Google Tag Manager SDK directly for both iOS and Android platforms.
## Documentation
The most complete doc is available here: https://capgo.app/docs/plugins/gtm/
## Compatibility
| Plugin version | Capacitor compatibility | Maintained |
| -------------- | ----------------------- | ---------- |
| v8.\*.\* | v8.\*.\* | ✅ |
| v7.\*.\* | v7.\*.\* | On demand |
| v6.\*.\* | v6.\*.\* | ❌ |
| v5.\*.\* | v5.\*.\* | ❌ |
> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
## Installation
```bash
npm install @capgo/capacitor-gtm
npx cap sync
```
## Platform Setup
### iOS Setup
1. **Add GTM container file**
- Download your container from Google Tag Manager console (GTM-XXXXXX.json)
- In Xcode, add the file to your project
- Make sure to add it to your app target
### Android Setup
1. **Add GTM container file**
- Download the Android default container from Google Tag Manager
- Add it as a raw resource in `android/app/src/main/res/raw/`
- Rename the file if needed so it uses only lowercase letters, digits, and underscores
- The plugin resolves the resource name from your container ID, for example `GTM-ABCD12` becomes `res/raw/gtm_abcd12`
- If you use JSON instead of the downloaded binary, it must be a simple default-container JSON. Full GTM export JSON files are not supported by the Android SDK
## API
* [`initialize(...)`](#initialize)
* [`push(...)`](#push)
* [`setUserProperty(...)`](#setuserproperty)
* [`getValue(...)`](#getvalue)
* [`reset()`](#reset)
* [`getPluginVersion()`](#getpluginversion)
* [Type Aliases](#type-aliases)
The main interface for the Google Tag Manager plugin.
### initialize(...)
```typescript
initialize(options: { containerId: string; timeout?: number; }) => Promise
```
Initializes Google Tag Manager with the specified container ID.
| Param | Type | Description |
| ------------- | ------------------------------------------------------- | ----------------------------- |
| **`options`** | { containerId: string; timeout?: number; } | - The initialization options. |
**Since:** 1.0.0
--------------------
### push(...)
```typescript
push(options: { event: string; parameters?: Record; }) => Promise
```
Pushes an event to the Google Tag Manager dataLayer.
| Param | Type | Description |
| ------------- | --------------------------------------------------------------------------------------------- | -------------------- |
| **`options`** | { event: string; parameters?: Record<string, any>; } | - The event options. |
**Since:** 1.0.0
--------------------
### setUserProperty(...)
```typescript
setUserProperty(options: { key: string; value: string | number | boolean; }) => Promise
```
Sets a user property in the Google Tag Manager dataLayer.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------- | ---------------------------- |
| **`options`** | { key: string; value: string \| number \| boolean; } | - The user property options. |
**Since:** 1.0.0
--------------------
### getValue(...)
```typescript
getValue(options: { key: string; }) => Promise<{ value: any; }>
```
Gets a value from the Google Tag Manager dataLayer.
Searches through the dataLayer for the most recent value of the specified key.
| Param | Type | Description |
| ------------- | ----------------------------- | ------------------------------------- |
| **`options`** | { key: string; } | - The options for retrieving a value. |
**Returns:** Promise<{ value: any; }>
**Since:** 1.0.0
--------------------
### reset()
```typescript
reset() => Promise
```
Resets the Google Tag Manager instance and clears all data.
This will remove all data from the dataLayer and require re-initialization.
**Since:** 1.0.0
--------------------
### getPluginVersion()
```typescript
getPluginVersion() => Promise<{ version: string; }>
```
Get the native Capacitor plugin version
**Returns:** Promise<{ version: string; }>
--------------------
### Type Aliases
#### Record
Construct a type with a set of properties K of type T
{
[P in K]: T;
}
## Usage Example
```typescript
import { GoogleTagManager } from '@capgo/capacitor-gtm';
// Initialize GTM
await GoogleTagManager.initialize({
containerId: 'GTM-XXXXXX',
timeout: 2000 // optional, defaults to 2000ms
});
// Track an event
await GoogleTagManager.push({
event: 'purchase',
parameters: {
value: 29.99,
currency: 'USD',
items: ['item1', 'item2']
}
});
// Set user property
await GoogleTagManager.setUserProperty({
key: 'user_type',
value: 'premium'
});
// Get a value from container
const result = await GoogleTagManager.getValue({ key: 'api_key' });
console.log('API Key:', result.value);
// Reset data layer
await GoogleTagManager.reset();
```
## Common Use Cases
### E-commerce Tracking
```typescript
// Track product view
await GoogleTagManager.push({
event: 'view_item',
parameters: {
currency: 'USD',
value: 15.99,
items: [{
item_id: 'SKU123',
item_name: 'Product Name',
price: 15.99,
quantity: 1
}]
}
});
// Track purchase
await GoogleTagManager.push({
event: 'purchase',
parameters: {
transaction_id: '12345',
value: 45.99,
currency: 'USD',
items: [{
item_id: 'SKU123',
item_name: 'Product Name',
price: 15.99,
quantity: 2
}]
}
});
```
### User Engagement
```typescript
// Track screen view
await GoogleTagManager.push({
event: 'screen_view',
parameters: {
screen_name: 'Home',
screen_class: 'HomeViewController'
}
});
// Track custom event
await GoogleTagManager.push({
event: 'level_complete',
parameters: {
level: 5,
score: 1000,
time_spent: 300
}
});
```
## Troubleshooting
### iOS Issues
1. **Container not loading**: Ensure the GTM container JSON file is properly added to your Xcode project and included in the app bundle.
2. **Build errors**: Make sure you've run `npx cap sync` after installation.
### Android Issues
1. **Container not found**: Verify the default container is available under `android/app/src/main/res/raw/` with a filename like `gtm_xxxxxx.json` or `gtm_xxxxxx.bin`. The resource name (filename without the extension) must match your container ID after lowercasing and replacing `-` with `_`.
2. **Initialization failures**: Check that the container ID matches your GTM container exactly.
### General Issues
1. **Events not appearing in GTM**: Remember that GTM has a delay in showing real-time events. Also ensure your GTM container is published.
2. **Values returning null**: Make sure the keys exist in your GTM container configuration.
## License
MIT