HubSpotSetupGuide.md

HubSpot Integration Setup Guide

Why HubSpot?

• Easy Setup: No business verification required like Google Ads
• Free Account: Create a free HubSpot account instantly
• Rich Data: Access contacts, companies, deals, and marketing data
• Simple OAuth: Standard OAuth2 flow with no special approvals

Step 1: Create HubSpot Account (2 minutes)

1. Go to hubspot.com
2. Click "Get HubSpot free"
3. Fill in basic information and create account
4. Complete the quick onboarding (can skip most steps)
5. You now have a free HubSpot account with CRM access!

Step 2: Create HubSpot App (5 minutes)

2.1 Access Developer Account

1. Go to developers.hubspot.com
2. Sign in with your HubSpot account
3. Click "Create App" or "Manage Apps"

2.2 Create New App

1. Click "Create App"
2. Fill in app details:
   • App Name: "Google Sheets Data Connector"
   • Description: "Import HubSpot data into Google Sheets"
3. Click "Create App"

2.3 Configure OAuth

1. Go to the "Auth" tab in your app
2. Set redirect URL:

   https://script.google.com/macros/d/YOUR_SCRIPT_ID/usercallback
   

   (Replace YOUR_SCRIPT_ID with your actual Apps Script ID)
3. Select required scopes:
   • contacts (to read contact data)
   • content (to read general content)
   • crm.objects.companies.read (for company data)
   • crm.objects.deals.read (for deals data)

2.4 Get Credentials

1. Note your Client ID (starts with numbers)
2. Note your Client Secret (long string)
3. Keep these secure - you'll need them for Apps Script

Step 3: Configure Apps Script (2 minutes)

3.1 Set Script Properties

In your Apps Script project:

1. Go to Project Settings > Script Properties
2. Add these properties:

HUBSPOT_CLIENT_ID = your_client_id_from_step_2
HUBSPOT_CLIENT_SECRET = your_client_secret_from_step_2

3.2 Update Script ID

In HubSpot.gs, the redirect URI should automatically use your script ID, but verify:

var redirectUri = 'https://script.google.com/macros/d/' + ScriptApp.getScriptId() + '/usercallback';

Step 4: Test the Integration (1 minute)

4.1 Test Authentication

function testHubSpotSetup() {
  var result = testHubSpotConnection();
  Logger.log(result);
}

4.2 Test Data Access

function testHubSpotData() {
  var config = {
    dimensions: ['firstname', 'lastname', 'email'],
    metrics: ['num_contacted_notes'],
    dateRangeComputed: {
      start: '2024-01-01',
      end: '2024-12-31'
    },
    limit: 10
  };
  
  var result = executeHubSpotReport(config);
  Logger.log(result);
}

Available HubSpot Data

Contact Data

• Dimensions: First Name, Last Name, Email, Phone, Company, Job Title, Create Date, Lifecycle Stage
• Metrics: Contact Notes, Website Visits, Email Opens, Email Clicks

Company Data

• Dimensions: Company Name, Domain, Industry, City, State, Country
• Metrics: Number of Employees, Annual Revenue

Deal Data

• Dimensions: Deal Name, Deal Stage, Pipeline, Close Date
• Metrics: Deal Amount, Conversion Events

Popular Report Templates

1. Contacts Overview

   • First Name, Last Name, Email, Company, Create Date
   • Contact Notes, Website Visits

2. Companies Report

   • Company Name, Domain, Industry, City, State
   • Number of Employees, Annual Revenue

3. Sales Pipeline

   • Deal Name, Deal Stage, Pipeline
   • Deal Amount

Troubleshooting

Issue: "Invalid redirect URI"

Solution: Ensure the redirect URI in HubSpot app exactly matches your Apps Script ID

Issue: "Insufficient scope permissions"

Solution: Add required scopes in your HubSpot app configuration

Issue: "No data returned"

Solution:

• Check if your HubSpot account has contacts/companies/deals
• Verify date ranges are appropriate
• Add sample data to test with

Issue: "Token refresh failed"

Solution: Re-authenticate through the UI - refresh tokens may have expired

Production Checklist

• HubSpot account created
• HubSpot app created with correct redirect URI
• Required OAuth scopes configured
• Client ID and Secret added to Apps Script properties
• Test authentication working
• Test data retrieval working
• Sample reports executing successfully

Sample Data for Testing

If your HubSpot account is empty, add some sample data:

1. Add Sample Contacts:

   • Go to Contacts > Create Contact
   • Add a few test contacts with names, emails, companies

2. Add Sample Companies:

   • Go to Companies > Create Company
   • Add test companies with names, domains, industries

3. Add Sample Deals:

   • Go to Deals > Create Deal
   • Add test deals with names, amounts, stages

Next Steps

Once HubSpot is working:

1. Your users can connect their HubSpot accounts
2. Import contact lists, company data, and sales pipeline reports
3. Schedule regular data refreshes
4. Use the same framework to add more data sources

The HubSpot integration provides valuable CRM data that complements your existing GA4 analytics, giving users a complete view of their marketing and sales funnel.