> ## Documentation Index
> Fetch the complete documentation index at: https://docs.admanage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AdManage Google Sheets Addon

> Complete campaign management directly from Google Sheets with launch drafts, ad set exports, matching, and data synchronization

The AdManage Google Sheets Addon is a comprehensive campaign management tool that brings the full power of AdManage directly into your Google Sheets environment. Upload launch drafts, export ad sets, match campaigns, and manage your advertising data all without leaving your spreadsheet.

**Need help?** For technical support, email us at [support@admanage.ai](mailto:support@admanage.ai)

## Key Features

The addon provides four core features accessible through an intuitive interface:

* **🚀 Launch Ads** - Upload campaign data to AdManage Launch Drafts
* **📊 Export Data** - Export ad sets and campaign data from AdManage to sheets
* **🎯 Match Ad Sets** - Intelligently match ads to appropriate ad sets based on campaign patterns

### Typical Launching Workflow

1. **Setup**: Use "Load Defaults" to create properly structured sheet
2. **Data Entry**: Fill in columns and rows with your information
3. **Upload**: Send launch batch to AdManage
4. **Launch**: Complete launching in AdManage platform

## Installation

### Install from Google Workspace Marketplace

The AdManage addon is available directly from the Google Workspace Marketplace for easy installation:
[Install AdManage from Google Workspace Marketplace](https://workspace.google.com/u/0/marketplace/app/admanage/550827967992)

1. **Open Google Sheets** - Create a new sheet or open an existing one
2. **Access Extensions** - Go to **Extensions** → **Add-ons** → **Get add-ons**
3. **Search for AdManage** - In the Google Workspace Marketplace, search for "AdManage"
4. **Install the Add-on** - Click on the AdManage addon and select **Install**
5. **Grant Permissions** - Review and accept the required permissions when prompted

### Initial Setup

1. **Refresh your Google Sheet** after installation
2. Go to **Extensions** → **AdManage** → **Launch Sidebar** to open the integration panel
3. The addon will automatically attempt to authenticate with your Google account

## Authentication

### Connect Your AdManage Account

The addon requires authentication with both Google and AdManage:

<AccordionGroup>
  <Accordion icon="google" title="Google Account Authorization">
    1. When you first open the sidebar, you may be prompted to authorize the script
    2. Click **"Review Permissions"** and grant the necessary access
    3. The addon needs permissions to:
       * Read and modify your spreadsheet data
       * Connect to external services (AdManage API)
       * Access your Google account information
  </Accordion>

  <Accordion icon="key" title="AdManage API Authentication">
    The addon uses **automatic authentication** through your Google account. The email address on the google account must be invited to your admanage organization.
  </Accordion>
</AccordionGroup>

## Feature 1: Launch Ads (Upload to AdManage)

Transform your spreadsheet data into AdManage Launch Drafts for campaign creation.

### Required Column Structure

Your Google Sheet must include the **Row Type** column:

* **Row Type** - Specifies the ad format (single, multi, carousel, etc.)

### Supported Columns

The addon supports extensive column mapping for comprehensive ad configuration:

<AccordionGroup>
  <Accordion icon="text" title="Basic Ad Information">
    * **Custom Name** / **Ad Name** - Campaign or ad identifier
    * **Ad Description** / **Description** - Detailed ad description
    * **Headline** / **Ad Title** - Primary headline text
    * **Primary Text** / **Main Text** / **Body Text** - Ad body content
    * **Created At** / **Updated At** - Timestamps
  </Accordion>

  <Accordion icon="link" title="Links and Tracking">
    * **Link** / **Landing Page** / **URL** / **Website** - Destination URL
    * **Display Link** - URL shown in ad
    * **UTM** / **UTM Parameters** - Tracking parameters
    * **CTA** / **Call to Action** / **Button Text** - Call-to-action text
    * **Partnership Code** - Partnership tracking
  </Accordion>

  <Accordion icon="play" title="Media and Targeting">
    * **Video URLs** / **Video Link** / **File Links** - Media content
    * **Ad Set IDs** - Target ad set identifiers
    * **Launch Paused** - Launch in paused state (true/false)
  </Accordion>

  <Accordion icon="pencil" title="Multiple Variations">
    * **Headline Variation (1-5)** - Multiple headline options
    * **Primary Text Variation (1-5)** - Multiple body text options
  </Accordion>

  <Accordion icon="images" title="Carousel Content (Advanced)">
    For carousel ads, the addon supports up to 10 carousel items:

    * **Carousel X Media URL** - Media file for each carousel card
    * **Carousel X Portrait Media URL** - Portrait orientation media
    * **Carousel X Title** - Title for each carousel card
    * **Carousel X Description** - Description for each carousel card
    * **Carousel X Link** - Destination URL for each carousel card
      *Note: Special carousel processing is available for specific customer configurations*
  </Accordion>
</AccordionGroup>

### Column Mapping System

The addon uses a two-tier column mapping system to automatically convert your sheet column names to AdManage format:

1. **Automatic Mappings** - Built-in mappings that work immediately (no configuration needed)
2. **Custom Mappings** - User-defined mappings for specific column names (configured in the sidebar)

#### Automatic Mappings (Always Active)

These mappings are automatically applied to your sheet columns. If your sheet uses any of these column names, they will be automatically converted to the AdManage format shown below:

<AccordionGroup>
  <Accordion icon="text" title="Basic Ad Information Mappings">
    **Ad Name:**

    * `Campaign Name` → `Ad Name`
    * `Custom Name` → `Ad Name`
    * `ad_name` → `Ad Name`

    **Headline:**

    * `Ad Title` → `Headline`
    * `Captions` → `Headline`
    * `headline_1` → `Headline`
    * `Headline Variation 1` → `Headline`
    * `Headline Variation 2` → `Headline Variation 1`
    * `Headline Variation 3` → `Headline Variation 2`
    * `Headline Variation 4` → `Headline Variation 3`
    * `Headline Variation 5` → `Headline Variation 4`

    **Primary Text:**

    * `Main Text` → `Primary Text`
    * `Body Text` → `Primary Text`
    * `primary_text_1` → `Primary Text`
    * `Primary Text Variation 1` → `Primary Text`
    * `Primary Text Variation 2` → `Primary Text Variation 1`
    * `Primary Text Variation 3` → `Primary Text Variation 2`
    * `Primary Text Variation 4` → `Primary Text Variation 3`
    * `Primary Text Variation 5` → `Primary Text Variation 4`

    **Ad Description:**

    * `Description` → `Ad Description`
    * `description` → `Ad Description`
  </Accordion>

  <Accordion icon="link" title="Links and Tracking Mappings">
    **Link:**

    * `Landing Page` → `Link`
    * `Page Link` → `Link`
    * `URL` → `Link`
    * `Website` → `Link`
    * `website_url` → `Link`

    **CTA:**

    * `Call to Action` → `CTA`
    * `Call-to-Action` → `CTA`
    * `Button Text` → `CTA`
    * `call_to_action` → `CTA`

    **UTM Parameters:**

    * `UTM` → `UTM Parameters`
    * `url_parameters` → `UTM Parameters`

    **Partnership Code:**

    * `Booster Code` → `Partnership Code`
    * `Spark Code` → `Partnership Code`
    * `Auth Code` → `Partnership Code`
    * `Tiktok Code` → `Partnership Code`
  </Accordion>

  <Accordion icon="play" title="Media and Format Mappings">
    **Media URLs:**

    * `Video URLs` → `Media URLs`
    * `Video URL` → `Media URLs`
    * `Video Link` → `Media URLs`
    * `File Links` → `Media URLs`
    * `File URLs` → `Media URLs`

    **Row Type:**

    * `Media Type` → `Row Type`
    * `AD Format` → `Row Type`
    * `Format` → `Row Type`
    * `format` → `Row Type`

    **Ad Set IDs:**

    * `adset_name` → `Ad Set IDs`

    **Ad Status:**

    * `ad_status` → `Ad Status`
  </Accordion>

  <Accordion icon="mobile" title="Page ID Mappings">
    **Instagram Page ID:**

    * `Instagram Page Id` → `Instagram Page ID`
    * `Instagram Page` → `Instagram Page ID`
    * `Instagram Profile` → `Instagram Page ID`
    * `IG Page ID` → `Instagram Page ID`

    **Facebook Page ID:**

    * `Facebook Page Id` → `Facebook Page ID`
    * `Facebook Page` → `Facebook Page ID`
    * `Facebook Profile` → `Facebook Page ID`
    * `FB Page ID` → `Facebook Page ID`

    **TikTok Page ID:**

    * `Tiktok Page Id` → `Tiktok Page ID`
    * `Tiktok Page` → `Tiktok Page ID`
    * `Tiktok Profile` → `Tiktok Page ID`

    **Threads Page ID:**

    * `Threads Page Id` → `Threads Page ID`
    * `Threads Page` → `Threads Page ID`
    * `Threads Profile` → `Threads Page ID`
  </Accordion>

  <Accordion icon="app" title="Custom Product Page Mappings">
    **iOS Custom Product Page:**

    * `Custom Product Page Code` → `Custom Product Page`
    * `csl` → `Custom Product Page`
    * `Custom Store Listing` → `Custom Product Page`
    * `CSL` → `Custom Product Page`
    * `iOS Custom Product Page` → `Custom Product Page`
    * `iOS CSL` → `Custom Product Page`
    * `iOS CPP` → `Custom Product Page`
    * And many more iOS variants (see code for complete list)

    **Android Custom Product Page:**

    * `Android Custom Product Page` → `Android Custom Product Page`
    * `Android CSL` → `Android Custom Product Page`
    * `Android CPP` → `Android Custom Product Page`
    * `Google Play Custom Product Page` → `Android Custom Product Page`
    * And many more Android variants (see code for complete list)
  </Accordion>

  <Accordion icon="shield" title="Brand Safety Mappings">
    **IAS Brand Safety URL:**

    * `Brand Safety URL` → `IAS Brand Safety URL`
    * `Brand Safety` → `IAS Brand Safety URL`
    * `IAS URL` → `IAS Brand Safety URL`
    * `IAS Brand Safety` → `IAS Brand Safety URL`
    * `IAS VAST URL` → `IAS Brand Safety URL`
    * `Brand Safety VAST` → `IAS Brand Safety URL`
  </Accordion>

  <Accordion icon="layers" title="Multi-Column Mappings (Automatic)">
    The addon automatically combines multiple columns into single AdManage fields:

    **Media URLs (from multiple asset columns):**

    * `1x1 Asset Link`, `4x5 Asset Link`, `9x16 Asset Link` → `Media URLs`
    * `1x1 Asset`, `4x5 Asset`, `9x16 Asset` → `Media URLs`
    * `1x1 File Link`, `4x5 File Link`, `9x16 File Link` → `Media URLs`
    * `1x1 file`, `4x5 file`, `9x16 file` → `Media URLs`
    * `default_image_url_1`, `default_image_url_2`, `default_image_url_3` → `Media URLs`

    *Note: Values are automatically concatenated with commas when multiple columns are mapped to the same target.*
  </Accordion>
</AccordionGroup>

#### Custom Mappings (User-Configured)

In addition to automatic mappings, you can create custom mappings for column names specific to your workflow. These are managed in the **Column Mappings** section of the sidebar:

1. **View Current Mappings** - The sidebar shows:
   * **Automatic Mappings** - All built-in mappings that are currently active (shown below custom mappings)
   * **Custom Mappings** - Your user-defined mappings (shown at the top)

2. **Add Custom Mapping** - Click **"+ Add Column Mapping"** to map a sheet column to an AdManage field

3. **Edit or Remove** - Custom mappings can be modified or deleted at any time

**Important:** Custom mappings take precedence over automatic mappings. If you create a custom mapping for a column name that also has an automatic mapping, your custom mapping will be used instead.

#### How Mappings Work Together

When you upload data to AdManage:

1. **Automatic mappings are applied first** - All built-in mappings are checked against your sheet columns
2. **Custom mappings are applied next** - Your custom mappings override any automatic mappings for the same column names
3. **Final result** - Your sheet data is transformed to AdManage format using the combined mapping rules

**Example:** If your sheet has a column named `Campaign Name`:

* It will automatically map to `Ad Name` (automatic mapping)
* If you create a custom mapping `Campaign Name` → `Custom Name`, your custom mapping will be used instead
* The final data sent to AdManage will use `Custom Name` as the field name

### Upload Process

<AccordionGroup>
  <Accordion icon="search" title="Smart Row Detection">
    1. The addon automatically detects new rows that haven't been uploaded
    2. It adds an **"ADMANAGE"** column to track upload status
    3. Only processes rows without timestamps in the ADMANAGE column
    4. Shows upload statistics before processing
  </Accordion>

  <Accordion icon="upload" title="Batch Upload (Max 50 rows)">
    1. Click **"Upload to AdManage"** from the Launch Ads card
    2. The addon processes up to 50 rows per batch for optimal performance
    3. If you have more than 50 rows, run multiple uploads
    4. Each successful upload adds timestamps to processed rows
  </Accordion>

  <Accordion icon="gear" title="Upload Configuration">
    * **Business ID**: Optional business/ad account identifier
    * **Status**: Choose "draft" or "active" for launch drafts
    * **Automatic Title Generation**: Uses row count and timestamp
    * **CSV Format**: Data is automatically formatted as CSV for AdManage
  </Accordion>
</AccordionGroup>

## Feature 2: Export Data (Ad Sets from AdManage)

Export ad set data from your AdManage account directly into Google Sheets for analysis and management.

### Export Capabilities

<AccordionGroup>
  <Accordion icon="download" title="Ad Set Export">
    1. Click **"Export from AdManage"** from the Export Data card
    2. Enter your Facebook/Meta Ad Account ID (numeric format)
    3. The addon fetches all ad sets with pagination support
    4. Creates a new sheet named "AdSets\_\[AccountName]"
  </Accordion>

  <Accordion icon="table" title="Exported Data Columns">
    The export includes essential ad set information:

    * **Ad Set ID** - Unique identifier
    * **Name** - Ad set name
    * **Campaign Name** - Parent campaign
    * **Spend** - Total ad spend
    * **Status** - Current ad set status
    * **Ad Count** - Number of ads in set
    * **Platform** - Advertising platform
  </Accordion>

  <Accordion icon="sync" title="Sync Management">
    * **Account Memory**: Your Ad Account ID is saved for future exports
    * **Last Sync Tracking**: Timestamps are recorded for each export
    * **Multiple Accounts**: Support for managing multiple ad accounts
    * **Automatic Formatting**: Headers, frozen rows, and auto-resized columns
  </Accordion>
</AccordionGroup>

### Background Sync & Scheduling

The addon includes advanced sync management:

* **Configured Syncs**: Set up automatic synchronization schedules
* **Batch Processing**: Run multiple account syncs simultaneously
* **Sync Status Tracking**: Monitor sync history and status
* **Error Handling**: Automatic API key refresh and retry logic

## Troubleshooting

<AccordionGroup>
  <Accordion icon="warning" title="Authentication Issues">
    **Problem**: "No AdManage API key found" or connection failures

    **Solution**:

    1. Use the refresh button in the account header
    2. Sign out and sign back into your Google account
    3. Check that your Google account is linked to AdManage
    4. Try opening the addon in an incognito window
    5. Ensure you have AdManage account access
  </Accordion>

  <Accordion icon="warning" title="Authentication Issues: Wrong User showing">
    **Problem**: "Wrong email address showing"
    The wrong email address is showing in the addon.
    This issue occurs when you have multiple google accounts in your chrome browser and the default one is the wrong one.
    We can't fix this issue because it's caused by google incorrectly telling us who is logged in.

    [https://developers.google.com/apps-script/guides/projects#fix\_issues\_with\_multiple\_google\_accounts](https://developers.google.com/apps-script/guides/projects#fix_issues_with_multiple_google_accounts)

    Try one of the following solutions:

    * Log out of all your Google Accounts and only log in to the one that has the add-on or web app you want to access.
    * Open an incognito window in Google Chrome, or an equivalent private browsing window, and log in to the Google Account that has the add-on or web app you want to access.
  </Accordion>

  <Accordion icon="table" title="Sheet Format Issues">
    **Problem**: Column mapping or data format errors

    **Solution**:

    1. Use the "Load Defaults" feature to see proper structure
    2. Ensure "Row Type" column exists and contains valid values
    3. Check for extra spaces in column headers
    4. Verify data is in expected formats (URLs, numbers, text)
    5. Use column mapping preview to verify recognition
  </Accordion>

  <Accordion icon="upload" title="Upload Failures">
    **Problem**: Upload process fails or times out

    **Solution**:

    1. Try uploading smaller batches (under 50 rows)
    2. Check internet connection stability
    3. Verify Ad Account ID format and permissions
    4. Look for error messages in the addon interface
    5. Clear and re-enter problematic data
  </Accordion>

  <Accordion icon="sync" title="Export Issues">
    **Problem**: Ad set export fails or returns no data

    **Solution**:

    1. Verify Ad Account ID is correct and accessible
    2. Check that you have permission to view ad sets
    3. Ensure the account has active ad sets to export
    4. Try a different Ad Account ID format (with/without "act\_")
    5. Check AdManage platform for account status
  </Accordion>

  <Accordion icon="target" title="Matching Problems">
    **Problem**: Ad set matching returns poor results

    **Solution**:

    1. Check that campaign names follow consistent patterns
    2. Verify ad set data has been recently exported
    3. Review column detection for country, language, product fields
    4. Consider setting up custom mapping rules
    5. Ensure ad sets exist for the targeting criteria
  </Accordion>
</AccordionGroup>

## Support

Having issues with the Google Sheets addon? We're here to help:

* 📧 **Email Support**: Contact our support team at [support@admanage.ai](mailto:support@admanage.ai)
* 🔧 **Technical Issues**: Include browser type, error messages, and screenshots
* 📚 **Feature Requests**: Let us know what additional functionality you need
* 🚀 **Integration Help**: Assistance with complex workflow setups

The AdManage Google Sheets addon transforms your spreadsheet into a powerful campaign management hub, providing seamless integration between your data and AdManage's comprehensive advertising platform.