Google Ads integration

​

What you can sync

• Purchase conversions: Track completed purchases as conversions in Google Ads
• Event conversions: Track custom events (sign-ups, leads, etc.) as conversions
• Conversion values: Send transaction amounts to measure ROAS (Return on Ad Spend)
• Order IDs: Link purchases to specific transactions for better tracking

​

Prerequisites

• A Google Ads account with active campaigns
• Google Ads API access (requires approval from Google)
• A Conversion Action created in Google Ads
• OAuth 2.0 credentials from Google Cloud Console

​

Getting your credentials

​

1. Customer ID

1. Log in to Google Ads
2. Look for the account number at the top of the page (format: 123-456-7890)
3. Remove the dashes when entering in Masivo (e.g., 1234567890)

​

2. Developer Token

1. Go to Tools & Settings → API Center in Google Ads
2. Click Apply for access
3. Fill out the application form
4. Once approved, copy your Developer Token

​

3. OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Ads API
4. Go to APIs & Services → Credentials
5. Click Create Credentials → OAuth client ID
6. Choose Web application as application type
7. Add authorized redirect URIs (e.g., http://localhost:3000/oauth2callback)
8. Save and copy your Client ID and Client Secret

​

4. Refresh Token

1. Use Google’s OAuth 2.0 Playground or implement the OAuth flow
2. Request scopes: https://www.googleapis.com/auth/adwords
3. Complete the authorization flow
4. Exchange the authorization code for tokens
5. Copy the Refresh Token (it won’t expire unless revoked)

​

5. Conversion Action ID

1. Go to Tools & Settings → Conversions in Google Ads
2. Click + New conversion action
3. Choose Import → Other data sources
4. Select Track conversions from clicks
5. Configure your conversion settings:
   • Category: Purchase, Sign-up, Lead, etc.
   • Value: Use different values for each conversion
   • Count: Every conversion (for purchases) or One (for sign-ups)
   • Click-through conversion window: 30-90 days recommended
   • Attribution model: Choose based on your business
6. Save and copy the Conversion Action ID (visible in the conversion details URL or settings)

​

Configuration

1. Go to Settings → Integrations → Google Ads in the Masivo dashboard
2. Enter your credentials:
   • Customer ID: Your 10-digit account number (without dashes)
   • Developer Token: From Google Ads API Center
   • Client ID: From Google Cloud Console
   • Client Secret: From Google Cloud Console
   • Refresh Token: Generated via OAuth flow
   • Conversion Action ID: From your conversion action
3. Enable the features you want to sync:
   • Events: Track custom event conversions
   • Purchases: Track completed purchase conversions
4. Click Save to activate the integration

​

How it works

​

1. Click tracking

• gclid (Google Click ID): Used for web traffic
• gbraid (Google Bounce Rate Analysis ID): Used for iOS 14.5+ traffic
• wbraid (Web to App Bounce Rate Analysis ID): Used for web-to-app conversions

​

2. Capturing click identifiers

// Example: Capture gclid from URL
const urlParams = new URLSearchParams(window.location.search);
const gclid = urlParams.get("gclid");
const gbraid = urlParams.get("gbraid");
const wbraid = urlParams.get("wbraid");

// Store for later use (localStorage, cookie, or session)
if (gclid) localStorage.setItem("gclid", gclid);
if (gbraid) localStorage.setItem("gbraid", gbraid);
if (wbraid) localStorage.setItem("wbraid", wbraid);

​

3. Sending conversions

{
  "type": "PURCHASE",
  "customer_id": "cust_123",
  "gclid": "EAIaIQobChMI0tXXyPaE8wIVjRmtBh3XqAZ7EAAYASAAEgJqxfD_BwE",
  "order": {
    "purchase_id": "ORD-789",
    "value": 159.99,
    "discounted_value": 149.99
  },
  "currency": "USD",
  "issued_at": "2025-10-20T14:30:00Z"
}

​

4. Automatic sync

• Validates the event and configuration
• Transforms the data to Google Ads format
• Sends the conversion to Google Ads API
• Handles errors and retries if needed

​

Data structure

​

Purchase conversion

{
  "type": "PURCHASE",
  "customer_id": "cust_123",
  "brand_id": "0001",
  "gclid": "EAIaIQobChMI0tXXyPaE8wIVjRmtBh3XqAZ7EAAYASAAEgJqxfD_BwE",
  "order": {
    "purchase_id": "ORD-789",
    "value": 159.99,
    "discounted_value": 149.99,
    "payment_method": "CREDIT",
    "products": [
      {
        "sku": "PROD-001",
        "value": 79.99,
        "amount": 2
      }
    ]
  },
  "currency": "USD",
  "fulfilled": true,
  "issued_at": "2025-10-20T14:30:00Z",
  "fulfilled_at": "2025-10-20T14:30:00Z"
}

​

Event conversion

{
  "type": "EVENT",
  "customer_id": "cust_123",
  "brand_id": "0001",
  "gclid": "EAIaIQobChMI0tXXyPaE8wIVjRmtBh3XqAZ7EAAYASAAEgJqxfD_BwE",
  "event_name": "lead_signup",
  "value": 25.0,
  "currency": "USD",
  "issued_at": "2025-10-20T14:30:00Z"
}

​

iOS conversion (using gbraid)

{
  "type": "PURCHASE",
  "customer_id": "cust_123",
  "gbraid": "0AAAAAo4mICNBGfEXAMPLEExampleGbraidString",
  "order": {
    "purchase_id": "ORD-790",
    "value": 99.99
  },
  "currency": "USD",
  "issued_at": "2025-10-20T14:30:00Z"
}

​

Required fields

​

For all conversions

​

For purchases

​

For events

​

Understanding click identifiers

​

GCLID (Google Click ID)

• Format: Long alphanumeric string (e.g., EAIaIQobChMI0tXXyPaE8wIVjRmtBh3XqAZ7EAAYASAAEgJqxfD_BwE)
• Usage: Standard web tracking
• Platform: All web browsers
• Expiration: Valid for 90 days after click
• Priority: Use gclid if available

​

GBRAID (Google Bounce Rate Analysis ID)

• Format: Alphanumeric string starting with specific prefix
• Usage: iOS 14.5+ tracking without cookies
• Platform: Safari on iOS/iPadOS
• Expiration: Valid for click-through conversion window
• Priority: Use when gclid is not available (iOS)

​

WBRAID (Web to App Bounce Rate Analysis ID)

• Format: Alphanumeric string
• Usage: Web-to-app conversion tracking
• Platform: Mobile apps (iOS/Android)
• Expiration: Valid for click-through conversion window
• Priority: Use when tracking web clicks that convert in-app

​

Conversion value logic

​

For PURCHASE events

// Uses order.value or order.discounted_value
conversionValue = order.value || order.discounted_value || 0;

​

For EVENT events

// Uses the event value directly
conversionValue = data.value || 0;

​

Validation

​

Configuration validation

• ✅ Customer ID is exactly 10 digits (without dashes)
• ✅ Developer token is provided
• ✅ OAuth credentials (client_id, client_secret, refresh_token) are complete
• ✅ Conversion Action ID is configured

​

Message validation

• ✅ Event type is enabled (events or purchases)
• ✅ At least one click identifier (gclid, gbraid, or wbraid) is present
• ✅ Customer ID exists
• ✅ Timestamp is in valid ISO 8601 format
• ✅ For purchases: order object with value exists

​

Best practices

​

1. Always capture click identifiers

// Capture and persist on page load
const captureClickId = () => {
  const params = new URLSearchParams(window.location.search);
  const gclid = params.get("gclid");
  const gbraid = params.get("gbraid");
  const wbraid = params.get("wbraid");

  if (gclid) {
    localStorage.setItem("gclid", gclid);
    // Set expiration (90 days)
    localStorage.setItem(
      "gclid_expires",
      Date.now() + 90 * 24 * 60 * 60 * 1000
    );
  }
  if (gbraid) localStorage.setItem("gbraid", gbraid);
  if (wbraid) localStorage.setItem("wbraid", wbraid);
};

captureClickId();

​

2. Check expiration before sending

const getValidGclid = () => {
  const gclid = localStorage.getItem("gclid");
  const expires = localStorage.getItem("gclid_expires");

  if (gclid && expires && Date.now() < parseInt(expires)) {
    return gclid;
  }

  return null;
};

​

3. Send conversions immediately

// After successful purchase
const trackPurchase = async orderData => {
  const gclid = getValidGclid();

  await fetch("/api/events/track", {
    method: "POST",
    body: JSON.stringify({
      type: "PURCHASE",
      customer_id: user.id,
      gclid: gclid, // Include if available
      order: orderData,
      currency: "USD",
      issued_at: new Date().toISOString()
    })
  });
};

​

4. Use accurate conversion values

• For purchases: Use the actual charged amount (after discounts)
• For events: Use realistic value estimates (e.g., average lead value)
• Always include currency code

​

5. Set up conversion tracking early

• Start tracking from day one
• Track multiple conversion types (purchases, sign-ups, leads)
• Be consistent with value attribution

​

6. Monitor conversion import status

1. Go to Tools & Settings → Conversions
2. Select your conversion action
3. Check the Status column for import errors
4. Review conversion counts match your expectations

​

Limitations

• Click identifiers are required: Conversions without gclid/gbraid/wbraid will be skipped
• 90-day attribution window: gclid values expire after 90 days (or your configured window)
• Real identifiers only: Cannot use mock or fabricated click identifiers
• API rate limits: Subject to Google Ads API rate limits (typically not an issue)
• Approval required: Requires approved Google Ads API access

​

Troubleshooting

​

Conversions not showing in Google Ads

// Debug: Log captured values
console.log("gclid:", localStorage.getItem("gclid"));
console.log("gbraid:", localStorage.getItem("gbraid"));

• Settings → Integrations → Google Ads
• Ensure “Purchases” or “Events” toggle is ON

• Must be 10 digits without dashes
• Example: 8623528631 ✅
• Example: 862-352-8631 ❌

​

“Invalid gclid” errors

• Cause: Expired, modified, or fabricated gclid
• Solution: Ensure you’re capturing the gclid directly from the URL without modification
• Note: gclid values are cryptographically signed and validated by Google

​

”Configuration incomplete” errors

✅ Customer ID (10 digits)
✅ Developer Token
✅ Client ID
✅ Client Secret
✅ Refresh Token
✅ Conversion Action ID

​

“Conversion action not found” errors

• Verify the Conversion Action ID is correct
• Ensure the conversion action is active in Google Ads
• Check that it’s configured for “clicks” (not “views”)

​

“Authentication failed” errors

• Refresh token expired: Regenerate your refresh token via OAuth flow
• Invalid credentials: Double-check client_id and client_secret
• API access revoked: Verify your API access status in Google Ads

​

Conversions delayed or not appearing

• Normal delay: Google Ads can take 3-9 hours to process imported conversions
• Check import history: Tools & Settings → Conversions → Import history
• Verify timestamps: Ensure issued_at is accurate and recent

​

Testing your integration

​

1. Create a test conversion action

1. Go to Google Ads → Tools & Settings → Conversions
2. Create a new conversion action with “Test” in the name
3. Use a low value to identify test conversions
4. Use this Conversion Action ID in your test environment

​

2. Generate a real gclid

1. Create a test campaign in Google Ads
2. Click your own ad from a real browser
3. Capture the gclid from the landing page URL
4. Use this gclid in your test conversion (valid for 90 days)

​

3. Use validation mode

// In your codebase (for testing only)
const p = {
  conversions: [conversion],
  partial_failure: true,
  validate_only: true, // Test without recording conversion
  customer_id: cleanCustomerId
};

​

4. Monitor the response

// Success response
{
  "processedCount": 1,
  "errorCount": 0
}

// Error response
{
  "error": "The imported gclid could not be decoded...",
  "details": "conversions[0].gclid"
}

​

Common integration patterns

​

E-commerce checkout

// 1. Capture gclid on landing
useEffect(() => {
  const params = new URLSearchParams(window.location.search);
  const gclid = params.get("gclid");
  if (gclid) sessionStorage.setItem("gclid", gclid);
}, []);

// 2. Send conversion after purchase
const handlePurchaseComplete = async order => {
  const gclid = sessionStorage.getItem("gclid");

  await trackEvent({
    type: "PURCHASE",
    customer_id: user.id,
    gclid: gclid,
    order: {
      purchase_id: order.id,
      value: order.total,
      discounted_value: order.discountedTotal
    },
    currency: "USD",
    issued_at: new Date().toISOString()
  });
};

​

Lead generation

// After form submission
const handleFormSubmit = async formData => {
  const gclid = localStorage.getItem("gclid");

  await trackEvent({
    type: "EVENT",
    customer_id: formData.email,
    gclid: gclid,
    event_name: "lead_form_submission",
    value: 50.0, // Estimated lead value
    currency: "USD",
    issued_at: new Date().toISOString()
  });
};

​

Mobile app (with gbraid)

// React Native or Expo
import { useURL } from "expo-linking";

const captureClickIds = () => {
  const url = useURL();

  if (url) {
    const params = new URL(url).searchParams;
    const gbraid = params.get("gbraid");

    if (gbraid) {
      AsyncStorage.setItem("gbraid", gbraid);
    }
  }
};

​

Next steps

1. Test thoroughly: Verify conversions appear in Google Ads (allow 3-9 hours)
2. Enable automated bidding: Use conversion data for Smart Bidding strategies
3. Set up value-based bidding: Optimize for conversion value, not just count
4. Track multiple actions: Set up different conversion actions for different goals
5. Monitor performance: Check conversion import status regularly