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

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 your container from Google Tag Manager console (GTM-XXXXXX.json)
   • Place the file in android/app/src/main/assets/containers/
   • Create the containers directory if it doesn't exist

API

• initialize(...)
• push(...)
• setUserProperty(...)
• getValue(...)
• reset()
• getPluginVersion()
• Type Aliases

The main interface for the Google Tag Manager plugin.

initialize(...)

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(...)

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(...)

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(...)

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()

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

getPluginVersion()

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

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

// 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

// 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 container file is in the correct location: android/app/src/main/assets/containers/GTM-XXXXXX.json

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