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

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

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-gtm` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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(options: { containerId: string; timeout?: number; }) => Promise<void>

push(options: { event: string; parameters?: Record<string, any>; }) => Promise<void>

setUserProperty(options: { key: string; value: string | number | boolean; }) => Promise<void>

getValue(options: { key: string; }) => Promise<{ value: any; }>

reset() => Promise<void>

getPluginVersion() => Promise<{ version: string; }>

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