## Google Ads Settings

Connect your Google Ads account to Alpha Insights for automatic ad spend tracking, campaign performance insights, and advanced profit value conversion tracking. This integration enables you to send profit data back to Google Ads for better campaign optimization.

### Accessing Google Ads Settings

1. Go to Alpha Insights → Settings
2. Navigate to the Google Ads settings page
3. You'll see the Google Ads API configuration interface

### Integration Status: Beta

The Google Ads integration is currently in beta. It's fully functional and production-ready, with ongoing improvements.

### What This Integration Does

- Automatic ad spend tracking: Daily Google Ads spend imported as expenses
- Campaign performance: Detailed metrics for each campaign
- Profit per campaign: Track which campaigns drive actual profit using UTM tracking
- Conversion value tracking: Send profit values back to Google Ads (unique feature!)
- Add-to-cart tracking: Track add-to-cart events for remarketing
- True ROAS calculations: Profit-based return on ad spend
- Historical data import: Fetch years of past campaign data

## API Connection

Connect Alpha Insights to your Google Ads account using secure OAuth authentication.

### Connect To The Google Ads API

#### Connection Status Display

Shows your current connection status:

- Connected To: Shows masked refresh token with green status (when connected)
- Not Connected: Red status indicator when no connection exists

#### Initial Connection Setup

1. Click Connect to Google Ads button
2. Google sign-in popup opens
3. Log in with Google account that has admin access to your Google Ads account
4. Review permissions requested - Alpha Insights needs access to Google Ads
5. Click "Allow" to grant permissions
6. Select your Google Ads account from the list (do NOT select manager accounts - only client accounts)
7. Click Connect Account button
8. A success screen appears with your connected account name
9. Click Fetch All Data to immediately import your historical ad data
10. Or close the modal to configure settings first, then fetch data later using "Refresh All Campaign Data" button
11. If data fetch is successful, you'll see a completion message
12. If data fetch fails (e.g., large account, timeout), you'll see a helpful message explaining your account IS connected and you can:
    - Try fetching data again later from settings
    - Adjust the "Account Age" setting to fetch a smaller date range
13. Page reloads to show your active connection status

Important requirements:

- Must have Admin or Standard access to Google Ads account
- Google Ads account must be active and not suspended
- If using Manager account, you can access child accounts

### Ad Account Selection

After connecting, select which Google Ads account to track.

#### Selecting An Account

1. After logging in with Google, ad accounts appear in dropdown
2. If dropdown is empty, click Fetch For Available Ad Accounts
3. Alpha Insights queries Google for all accounts you have access to
4. Select the ad account you want to track from dropdown
5. Account shows descriptive name (e.g., "YourStore Ads - 123-456-7890")
6. Click Save Changes
7. Status indicator turns green when account is configured

Manager Accounts: If you use a Google Ads Manager account, you'll see all child accounts you manage in the list

### Reconnecting / Refreshing Token

Google refresh tokens don't expire like Facebook, but you may need to reconnect if:

- You revoked access in Google account settings
- You see "Connection expired" errors
- Syncs stop working

To reconnect:

1. Click Login With Google again
2. Reauthenticate with Google
3. Connection is restored

### Revoking Connection

To remove the Google Ads connection:

1. Click Delete Connection link
2. Confirm deletion
3. Refresh token is removed
4. Scheduled syncs stop
5. Historical data remains (unless you delete it)

Note: If you need to reconnect after revoking, you may first need to remove Alpha Insights from your Google Account Connections

## Alpha Campaign Profit Tracking

Track which Google Ads campaigns drive actual profit.

### How It Works

1. Add tracking parameter to your Google Ads
2. When someone clicks ad, campaign ID is captured
3. When they purchase, order is linked to that campaign
4. Alpha Insights calculates profit for the order
5. View campaign-level profitability in reports

### UTM Tracking Key / Values

The parameter: `google_cid={campaignid}`

What it does:

- `google_cid` = Google Campaign ID
- `{campaignid}` = Google Ads dynamic parameter (auto-fills with campaign ID)

### Setting Up UTM Tracking

#### Method 1: Account-Level Tracking Template (Recommended)

1. Go to Google Ads
2. Click Settings → Account settings
3. Find "Tracking" section
4. Look for "Tracking template" or "Account-level options"
5. In "Tracking template" or "Final URL suffix" field, add: `?google_cid={campaignid}`
6. If your URLs already have parameters, use: `&google_cid={campaignid}`
7. Click Save

This applies to ALL ads in your account automatically!

#### Method 2: Campaign-Level Tracking

1. Go to specific campaign settings
2. Find "Campaign URL options"
3. Add to "Tracking template" or "Final URL suffix"
4. Applies to all ads in that campaign

### Testing Your Tracking

1. Click your Google ad (or use Preview & Diagnose in Google Ads)
2. Look at URL in browser address bar
3. Should see: `google_cid=12345678` (with actual campaign ID)
4. This confirms tracking is working

## API Settings

Configure sync schedule and data collection.

### API Call Schedule

What it does: Controls how often Alpha Insights syncs with Google Ads

Options:

- Daily: Checks once per day (sufficient for most)
- Every 12 Hours: Checks twice daily
- Every 6 Hours: Checks four times daily (most current)

What gets synced on schedule:

- Past 30 days of campaign data
- Daily ad spend
- Campaign metrics and performance
- Updates existing records or creates new ones

Important note: Regular syncs check past 30 days. Use "Refresh All Campaign Data" button to sync all-time historical data.

Recommendation: Daily is perfect for most stores

### Ad Spend Expense Category

What it is: Where Google Ads spend is stored in your expense tracking

Configuration:

1. Select existing expense category from dropdown
2. Or click Add New Category
3. Common names: "Google Ads", "Google Advertising", "PPC Advertising"

Why it matters: Allows separate reporting of Google Ads costs vs other expenses

### Ad Account Age (Years)

Default: 10 years

Range: 1-25 years

What it does: When you click "Refresh All Campaign Data", determines how far back to fetch data

How to set: Enter a number larger than your account age (10 is usually safe)

Warning: Very large queries (many years, many campaigns) may timeout. If this happens, reduce the number.

## Conversion Action for Tracking Order Profit Value & Add To Carts

This is the unique powerful feature that sets Alpha Insights apart - sending profit data back to Google Ads.

### Conversion Action for Tracking Order Profit Value

#### What This Feature Does

Creates a conversion action in your Google Ads account that receives the profit value of orders, not revenue.

Why this is revolutionary:

- Google Ads optimizes for revenue by default
- But high revenue doesn't mean high profit
- This feature sends PROFIT to Google for optimization
- Google's algorithms can optimize for actual profitability
- You get better campaign performance based on real business value

#### How It Works

1. Customer clicks your Google Ad (GCLID is captured automatically by Google)
2. Customer makes a purchase on your store
3. Alpha Insights calculates the profit for that order
4. The profit value is sent to Google Ads via Enhanced Conversions API
5. Google receives profit value and can optimize campaigns for profit
6. Your campaigns become more profitable over time

#### Setup Process

1. Ensure Google Ads API is connected (refresh token exists)
2. Ensure ad account is selected
3. Click Create Conversion Action button
4. Alpha Insights automatically creates conversion action in your Google Ads account
5. Conversion action named "Alpha Insights - Order Profit"
6. Status updates to show conversion action ID with green indicator
7. From this point forward, all orders with GCLID send profit value to Google

#### Viewing in Google Ads

1. Log into Google Ads
2. Go to Goals → Summary
3. Click View All Conversions
4. Look for "Alpha Insights - Order Profit"
5. You'll see conversion counts and profit values

#### Current Status Display

When configured:

- Shows: "Current Conversion Action: Alpha Insights - Order Profit (ID: xxxxx)" with green status
- Displays "Delete Conversion Action" button
- Shows message: "Conversion action is configured and currently sending the order profit value to Google Ads"

When not configured:

- Shows: "No conversion action configured" with red status
- Displays "Create Conversion Action" button
- Shows setup instructions

#### Deleting Conversion Action

To remove the profit conversion tracking:

1. Click Delete Conversion Action
2. Confirms deletion
3. Removes conversion action from Google Ads account
4. Stops sending profit values
5. Can be recreated anytime

### Conversion Action for Add To Cart

#### What It Does

Tracks when visitors add products to cart - useful for remarketing and campaign optimization.

#### How It Works

1. Visitor with GCLID (from Google Ad) adds product to cart
2. Alpha Insights captures the add-to-cart event
3. Event is sent to Google Ads
4. Google receives the conversion event
5. You can create remarketing audiences of people who added to cart
6. Google can optimize campaigns for add-to-cart actions

#### Setup Process

1. Ensure Google Ads connection is configured
2. Click Create Add To Cart Conversion Action
3. Alpha Insights creates "Alpha Insights - Add to Cart" conversion action
4. Status updates with green indicator
5. Add-to-cart events start sending to Google

#### Use Cases

- Remarketing: Create audiences of cart abandoners
- Optimization: Optimize campaigns for add-to-cart (earlier in funnel than purchase)
- Analysis: See which campaigns drive cart adds vs purchases

## API Data

View sync status and stored data information.

Daily Expenses Stored: Number of daily ad spend records in database

Campaigns Stored: Number of Google Ads campaigns tracked

Last Successful Data Fetch: Timestamp of last successful sync

Next Scheduled Data Fetch: When next automatic sync will run

## API Tools

Manual sync and data management tools.

### Refresh All Campaign Data

What it does: Fetches all historical campaign data based on "Ad Account Age" setting

When to use:

- After initial connection (to get historical data)
- If data appears missing or incorrect
- After changing API settings
- To backfill years of past campaigns

Process:

1. Click Refresh All Campaign Data
2. Background process starts (can take several minutes)
3. Fetches data for number of years specified in "Ad Account Age" setting
4. Creates new records or updates existing ones
5. Does NOT delete any data

Important: This is a large API request. Use sparingly. Regular syncs are sufficient for ongoing updates.

### Check API Status

What it does: Tests current connection and displays status

When to use:

- Troubleshooting sync issues
- Verifying connection after setup
- Checking for error messages

### Delete All Expense Data

What it does: Removes all Google Ads expense records from database

Important:

- Only deletes data in Alpha Insights
- Does NOT affect Google Ads account
- Cannot be undone
- Does not delete campaign insights (only expense records)

### Delete All Campaign Data

What it does: Removes all Google Ads campaign insights from database

Important:

- Only deletes Alpha Insights data
- Does NOT affect Google Ads
- Cannot be undone
- Does not delete expense records

## Google API Logs

At bottom of settings page, you'll see two log sections.

### Google API Error Log

Shows: Errors and issues encountered during API operations

Use for: Troubleshooting connection problems and sync failures

### Google API Activity Log

Shows: Successful API operations and regular activity

Use for: Verifying syncs are running correctly

## Important Information

### Key Features vs Facebook

- Refresh tokens don't expire: Unlike Facebook (60 days), Google refresh tokens generally don't expire
- No historical data limit: Can fetch many years back (unlike Facebook's 36-month limit)
- Profit value sending: Unique ability to send profit data back to Google
- Add-to-cart tracking: Track early funnel events

### Data Syncing Details

- Scheduled syncs check past 30 days
- "Refresh All" checks back number of years in settings
- No duplication - updates existing or creates new records
- Currency conversion if ad account uses different currency

### Privacy and Security

- Read-only access to campaign data
- Write access only for conversion reporting (profit values, add-to-cart)
- Cannot modify campaigns, budgets, or ads
- No access to customer personal information
- Refresh tokens encrypted in database

## Troubleshooting

### Connection Failed

Solution: Click "Login With Google" again and reauthenticate

### No Ad Accounts Available

Cause: Account doesn't have access to any Google Ads accounts

Solution:

- Verify you have access to Google Ads account
- Try logging in with different Google account
- Check Google Ads account is active and not suspended

### Can't Create Conversion Action

Check:

- Google Ads connection is configured
- Ad account is selected
- Account has permission to create conversion actions
- Check error log for specific error message

### Conversion Values Not Showing in Google Ads

Check:

- Conversion action is created (shows green status)
- Orders have GCLID (customers came from Google Ads)
- Wait 24-48 hours for Google to process conversions
- Check Google Ads conversion tracking tag is working

### Ad Spend Doesn't Match Google Ads

Common reasons:

- Currency difference - check conversion rates
- Time zone mismatch - verify WordPress timezone
- Sync hasn't run - wait for schedule or click "Refresh"
- Different date ranges being compared

## Best Practices

### Initial Setup

- Use business Google account for connection
- Create dedicated expense category for Google Ads
- Set up UTM tracking at account level (applies to all ads)
- Click "Refresh All Campaign Data" after initial connection
- Create profit conversion action immediately
- Create add-to-cart conversion action if using remarketing

### Ongoing Management

- Check API status monthly
- Review error logs if sync issues occur
- Always use UTM tracking on new campaigns
- Monitor conversion action status in Google Ads
- Use daily sync schedule for active campaigns

### Campaign Optimization

- Give Google 1-2 weeks to gather profit conversion data
- Use profit conversion action as primary goal in campaigns
- Set up remarketing lists using add-to-cart conversions
- Monitor profit ROAS vs revenue ROAS in Alpha Insights
- Adjust bids based on campaign profitability

## Summary

The Google Ads integration offers:

- Automatic expense tracking: Daily ad spend imported automatically
- Campaign profitability: See which campaigns drive profit
- Advanced conversion tracking: Send profit values back to Google
- Better optimization: Google optimizes for profit, not just revenue
- Complete insights: All campaign data in one place
- Reliable syncing: Set and forget automated updates

The profit value conversion feature is unique and powerful - it enables Google's algorithms to optimize your campaigns for actual business profitability, not just revenue or conversions!