Getting Started

Installation

npm

npm install @capgo/capacitor-gtm
npx cap sync

yarn

yarn add @capgo/capacitor-gtm
npx cap sync

pnpm

pnpm add @capgo/capacitor-gtm
npx cap sync

bun

bun add @capgo/capacitor-gtm
npx cap sync

Platform Configuration

iOS

1. Download your GTM container configuration file from Google Tag Manager console
2. Add the container JSON file to your iOS project in Xcode
3. The file should be named something like GTM-XXXXXX.json

Android

1. Download your GTM container configuration file from Google Tag Manager console
2. Add the container JSON file to android/app/src/main/assets/
3. The file should be named something like GTM-XXXXXX.json

Usage Example

import { CapacitorGTM } from '@capgo/capacitor-gtm';

// Initialize GTM with your container ID
await CapacitorGTM.init({
  containerId: 'GTM-XXXXXX'
});

// Push events to dataLayer
await CapacitorGTM.pushEvent({
  event: 'screen_view',
  parameters: {
    screen_name: 'Home',
    screen_class: 'HomeScreen'
  }
});

// Push custom events with parameters
await CapacitorGTM.pushEvent({
  event: 'purchase',
  parameters: {
    transaction_id: 'T12345',
    value: 25.00,
    currency: 'USD',
    items: [
      {
        item_id: 'SKU_12345',
        item_name: 'Product Name',
        quantity: 1,
        price: 25.00
      }
    ]
  }
});

// Set user properties
await CapacitorGTM.setUserProperty({
  key: 'user_type',
  value: 'premium'
});

// Get values from dataLayer
const result = await CapacitorGTM.getVariable({
  key: 'config_value'
});
console.log('Config value:', result.value);

API Reference

init(options)

init(options: { containerId: string }) => Promise<void>

Initialize Google Tag Manager with your container ID.

Param	Type
options	{ containerId: string }

pushEvent(options)

pushEvent(options: GTMEvent) => Promise<void>

Push an event to the dataLayer with optional parameters.

Param	Type
options	GTMEvent

setUserProperty(options)

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

Set a user property for segmentation and targeting.

Param	Type
options	{ key: string; value: string }

getVariable(options)

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

Get a value from the GTM container configuration.

Param	Type
options	{ key: string }

Returns: Promise<{ value: any }>

Interfaces

GTMEvent

Prop	Type	Description
event	string	The event name
parameters	Record<string, any>	Optional event parameters (optional)

Common Event Examples

Screen Views

await CapacitorGTM.pushEvent({
  event: 'screen_view',
  parameters: {
    screen_name: 'Product Details',
    screen_class: 'ProductScreen'
  }
});

User Actions

await CapacitorGTM.pushEvent({
  event: 'button_click',
  parameters: {
    button_name: 'add_to_cart',
    product_id: 'SKU_12345'
  }
});

E-commerce Events

await CapacitorGTM.pushEvent({
  event: 'begin_checkout',
  parameters: {
    currency: 'USD',
    value: 75.00,
    items: [
      {
        item_id: 'SKU_12345',
        item_name: 'Product 1',
        quantity: 2,
        price: 25.00
      },
      {
        item_id: 'SKU_67890',
        item_name: 'Product 2',
        quantity: 1,
        price: 25.00
      }
    ]
  }
});

Best Practices

• Initialize GTM early in your app lifecycle
• Use consistent event naming conventions
• Include relevant parameters with each event
• Test your GTM configuration in preview mode
• Monitor data in Google Tag Manager console
• Use user properties for meaningful segmentation

Debugging

Enable debug mode in Google Tag Manager console to test your implementation:

1. Open GTM console
2. Go to Preview mode
3. Connect to your app using the container ID
4. Verify events are being tracked correctly

Use Cases

• Track user interactions and behavior
• Monitor app performance metrics
• Collect e-commerce data
• Manage third-party tags without code changes
• Implement A/B testing and personalization
• Integrate with Google Analytics and other services