A Capacitor plugin for integrating Google Tag Manager into your mobile applications.
npm install capacitor-gtm
npx cap sync-
Add your GTM container file
- Download your container from Google Tag Manager console
- Add the downloaded
GTM-XXXXXX.jsonfile to your iOS project - In Xcode, drag the file into your project
- Make sure "Copy items if needed" is selected
- Ensure the file is added to your app target
-
No additional configuration needed
- The plugin uses Google Tag Manager SDK v7.4.6 which supports iOS 12+
- The plugin is compatible with iOS 14.0+
- Add your GTM container file
- Download your container from Google Tag Manager console
- Place the
GTM-XXXXXX.jsonfile in your Android project'sassets/containers/folder - Create the
containersfolder if it doesn't exist:android/app/src/main/assets/containers/
No additional setup is required for web. The plugin will automatically load the Google Tag Manager script.
import { GoogleTagManager } from 'capacitor-gtm';
// Initialize Google Tag Manager
await GoogleTagManager.initialize({
containerId: 'GTM-XXXXXX',
timeout: 2000 // optional, defaults to 2000ms
});
// Push an event to the dataLayer
await GoogleTagManager.push({
event: 'purchase',
parameters: {
value: 29.99,
currency: 'USD',
transaction_id: '12345'
}
});
// Set a user property
await GoogleTagManager.setUserProperty({
key: 'user_type',
value: 'premium'
});
// Get a value from the container
const result = await GoogleTagManager.getValue({ key: 'api_key' });
console.log('API Key:', result.value);
// Reset all data
await GoogleTagManager.reset();await GoogleTagManager.push({
event: 'screen_view',
parameters: {
screen_name: 'Home',
screen_class: 'HomeViewController'
}
});await GoogleTagManager.push({
event: 'button_click',
parameters: {
button_name: 'subscribe',
button_location: 'header'
}
});// Track a purchase
await GoogleTagManager.push({
event: 'purchase',
parameters: {
transaction_id: '12345',
value: 59.99,
currency: 'USD',
items: [{
item_id: 'SKU123',
item_name: 'Product Name',
price: 59.99,
quantity: 1
}]
}
});
// Track add to cart
await GoogleTagManager.push({
event: 'add_to_cart',
parameters: {
currency: 'USD',
value: 29.99,
items: [{
item_id: 'SKU456',
item_name: 'Another Product',
price: 29.99,
quantity: 1
}]
}
});// Set multiple user properties
await GoogleTagManager.setUserProperty({
key: 'user_id',
value: 'USER123'
});
await GoogleTagManager.setUserProperty({
key: 'subscription_status',
value: 'active'
});await GoogleTagManager.push({
event: 'custom_event',
parameters: {
custom_parameter_1: 'value1',
custom_parameter_2: 123,
custom_parameter_3: true
}
});The main interface for the Google Tag Manager plugin.
initialize(options: { containerId: string; timeout?: number; }) => Promise<void>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(options: { event: string; parameters?: Record<string, any>; }) => Promise<void>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(options: { key: string; value: string | number | boolean; }) => Promise<void>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(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() => Promise<void>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
Construct a type with a set of properties K of type T
{
[P in K]: T;
}
To test your container configuration before publishing:
- In Google Tag Manager, click "Preview" in your workspace
- For mobile apps, you'll need to use the Google Tag Manager app for testing
- Follow the preview instructions in the GTM interface
Enable verbose logging by setting the log level in your app:
// This should be done before initializing GTM
if (__DEV__) {
// Platform-specific debug enabling
}- iOS: Requires iOS 14.0 or later
- Android: Requires Android 5.0 (API level 21) or later
- Web: Works in all modern browsers
MIT