Gemini × Google Workspace Add-ons Development Guide — From Building Custom AI Side Panels to Marketplace Launch

// gemini.gs — Gemini API utilities
const GEMINI_API_KEY = PropertiesService.getScriptProperties()
  .getProperty('GEMINI_API_KEY');
const GEMINI_ENDPOINT =
  'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent';
 
/**
 * Send a prompt to Gemini API and return the text response
 * @param {string} prompt - Input prompt
 * @param {Object} options - Configuration options
 * @returns {string} Gemini's text response
 */
function callGemini(prompt, options = {}) {
  const payload = {
    contents: [{
      parts: [{ text: prompt }]
    }],
    generationConfig: {
      temperature: options.temperature || 0.7,
      maxOutputTokens: options.maxTokens || 2048,
      topP: options.topP || 0.95
    }
  };
 
  // System Instruction (optional)
  if (options.systemInstruction) {
    payload.systemInstruction = {
      parts: [{ text: options.systemInstruction }]
    };
  }
 
  const response = UrlFetchApp.fetch(
    `${GEMINI_ENDPOINT}?key=${GEMINI_API_KEY}`,
    {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify(payload),
      muteHttpExceptions: true
    }
  );
 
  const json = JSON.parse(response.getContentText());
 
  if (json.error) {
    throw new Error(`Gemini API Error: ${json.error.message}`);
  }
 
  return json.candidates[0].content.parts[0].text;
}
 
/**
 * Call Gemini with structured output (JSON mode)
 * @param {string} prompt - Input prompt
 * @param {Object} schema - JSON Schema definition
 * @returns {Object} Parsed JSON object
 */
function callGeminiStructured(prompt, schema) {
  const payload = {
    contents: [{
      parts: [{ text: prompt }]
    }],
    generationConfig: {
      responseMimeType: 'application/json',
      responseSchema: schema,
      temperature: 0.3
    }
  };
 
  const response = UrlFetchApp.fetch(
    `${GEMINI_ENDPOINT}?key=${GEMINI_API_KEY}`,
    {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify(payload),
      muteHttpExceptions: true
    }
  );
 
  const json = JSON.parse(response.getContentText());
  return JSON.parse(json.candidates[0].content.parts[0].text);
}

// gmail-addon.gs — Gmail side panel
function onGmailMessage(e) {
  const messageId = e.gmail.messageId;
  const message = GmailApp.getMessageById(messageId);
  const subject = message.getSubject();
  const body = message.getPlainBody().substring(0, 3000); // Save tokens
  const from = message.getFrom();
 
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle('Gemini AI Assistant')
        .setSubtitle(subject)
        .setImageUrl('https://example.com/gemini-icon.png')
        .setImageStyle(CardService.ImageStyle.CIRCLE)
    );
 
  // Summary section
  const summarySection = CardService.newCardSection()
    .setHeader('📋 Email Summary')
    .addWidget(
      CardService.newTextParagraph()
        .setText('Run AI analysis directly from the side panel')
    )
    .addWidget(
      CardService.newButtonSet()
        .addButton(
          CardService.newTextButton()
            .setText('Generate Summary')
            .setOnClickAction(
              CardService.newAction()
                .setFunctionName('summarizeEmail')
                .setParameters({
                  messageId: messageId,
                  subject: subject,
                  body: body.substring(0, 1500)
                })
            )
        )
        .addButton(
          CardService.newTextButton()
            .setText('Draft Reply')
            .setOnClickAction(
              CardService.newAction()
                .setFunctionName('draftReply')
                .setParameters({
                  messageId: messageId,
                  subject: subject,
                  body: body.substring(0, 1500),
                  from: from
                })
            )
        )
    );
 
  // Custom prompt section
  const customSection = CardService.newCardSection()
    .setHeader('💬 Custom Question')
    .addWidget(
      CardService.newTextInput()
        .setFieldName('customPrompt')
        .setTitle('Ask about this email')
        .setHint('e.g., List the action items in this email')
    )
    .addWidget(
      CardService.newTextButton()
        .setText('Ask AI')
        .setOnClickAction(
          CardService.newAction()
            .setFunctionName('askAboutEmail')
            .setParameters({
              body: body.substring(0, 1500)
            })
        )
    );
 
  card.addSection(summarySection);
  card.addSection(customSection);
 
  return card.build();
}
 
/**
 * Email summary callback
 */
function summarizeEmail(e) {
  const params = e.commonEventObject.parameters;
 
  const summary = callGemini(
    `Summarize the following email in 3 lines. If there are important action items, list them as bullet points.\n\nSubject: ${params.subject}\n\nBody:\n${params.body}`,
    {
      systemInstruction: 'You are a business email analysis assistant. Summarize concisely and accurately.',
      temperature: 0.3,
      maxTokens: 512
    }
  );
 
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle('Summary')
        .setSubtitle(params.subject)
    )
    .addSection(
      CardService.newCardSection()
        .addWidget(
          CardService.newTextParagraph().setText(summary)
        )
        .addWidget(
          CardService.newButtonSet()
            .addButton(
              CardService.newTextButton()
                .setText('← Back')
                .setOnClickAction(
                  CardService.newAction()
                    .setFunctionName('onGmailMessage')
                )
            )
        )
    );
 
  return CardService.newActionResponseBuilder()
    .setNavigation(
      CardService.newNavigation().pushCard(card.build())
    )
    .build();
}
 
/**
 * Reply draft generation callback
 */
function draftReply(e) {
  const params = e.commonEventObject.parameters;
 
  const replyDraft = callGemini(
    `Write a professional reply to the following email. Be polite, concise, and include specific content.\n\nFrom: ${params.from}\nSubject: ${params.subject}\nBody:\n${params.body}`,
    {
      systemInstruction: 'You are a professional business email writer.',
      temperature: 0.5,
      maxTokens: 1024
    }
  );
 
  // Create draft in Gmail
  const message = GmailApp.getMessageById(params.messageId);
  message.getThread().createDraftReply(replyDraft);
 
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader().setTitle('Draft Created')
    )
    .addSection(
      CardService.newCardSection()
        .addWidget(
          CardService.newTextParagraph()
            .setText('✅ Draft saved to your Drafts folder.\n\n' + replyDraft.substring(0, 500) + '...')
        )
    );
 
  return CardService.newActionResponseBuilder()
    .setNavigation(
      CardService.newNavigation().pushCard(card.build())
    )
    .build();
}

// docs-addon.gs — Google Docs side panel
function onDocsHomepage(e) {
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle('Gemini AI Assistant')
        .setSubtitle('Document Analysis')
    );
 
  const analysisSection = CardService.newCardSection()
    .setHeader('📝 Document Analysis')
    .addWidget(
      CardService.newButtonSet()
        .addButton(
          CardService.newTextButton()
            .setText('Proofread')
            .setOnClickAction(
              CardService.newAction()
                .setFunctionName('proofreadDoc')
            )
        )
        .addButton(
          CardService.newTextButton()
            .setText('Summarize')
            .setOnClickAction(
              CardService.newAction()
                .setFunctionName('summarizeDoc')
            )
        )
    );
 
  const translateSection = CardService.newCardSection()
    .setHeader('🌐 Translation')
    .addWidget(
      CardService.newSelectionInput()
        .setFieldName('targetLang')
        .setTitle('Target Language')
        .setType(CardService.SelectionInputType.DROPDOWN)
        .addItem('Japanese', 'ja', false)
        .addItem('Chinese (Simplified)', 'zh-CN', false)
        .addItem('Korean', 'ko', false)
        .addItem('French', 'fr', false)
        .addItem('Spanish', 'es', false)
    )
    .addWidget(
      CardService.newTextButton()
        .setText('Translate Selection')
        .setOnClickAction(
          CardService.newAction()
            .setFunctionName('translateSelection')
        )
    );
 
  card.addSection(analysisSection);
  card.addSection(translateSection);
 
  return card.build();
}
 
/**
 * Document proofreading
 */
function proofreadDoc(e) {
  const doc = DocumentApp.getActiveDocument();
  const body = doc.getBody().getText();
 
  if (!body || body.trim().length === 0) {
    return createErrorCard('The document is empty. Please add some text and try again.');
  }
 
  // Limit long documents to first 5000 characters
  const textToAnalyze = body.substring(0, 5000);
 
  const result = callGeminiStructured(
    `Proofread the following text. Identify typos, grammar mistakes, and areas for improvement.\n\n${textToAnalyze}`,
    {
      type: 'object',
      properties: {
        corrections: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              original: { type: 'string', description: 'Original text' },
              corrected: { type: 'string', description: 'Corrected text' },
              reason: { type: 'string', description: 'Reason for correction' }
            },
            required: ['original', 'corrected', 'reason']
          }
        },
        overallScore: { type: 'number', description: 'Writing quality score out of 100' },
        summary: { type: 'string', description: 'Overall assessment comment' }
      },
      required: ['corrections', 'overallScore', 'summary']
    }
  );
 
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle(`Proofreading Result — ${result.overallScore}/100`)
    );
 
  const summarySection = CardService.newCardSection()
    .setHeader('Overall Assessment')
    .addWidget(
      CardService.newTextParagraph().setText(result.summary)
    );
 
  card.addSection(summarySection);
 
  if (result.corrections.length > 0) {
    const correctionsSection = CardService.newCardSection()
      .setHeader(`Suggested Corrections (${result.corrections.length})`);
 
    result.corrections.slice(0, 10).forEach((c, i) => {
      correctionsSection.addWidget(
        CardService.newDecoratedText()
          .setTopLabel(`#${i + 1} — ${c.reason}`)
          .setText(`❌ ${c.original}\n✅ ${c.corrected}`)
          .setWrapText(true)
      );
    });
 
    card.addSection(correctionsSection);
  }
 
  return CardService.newActionResponseBuilder()
    .setNavigation(
      CardService.newNavigation().pushCard(card.build())
    )
    .build();
}

# Install clasp
npm install -g @google/clasp
 
# Log in with your Google account
clasp login
 
# Clone an existing Apps Script project
clasp clone <SCRIPT_ID>
 
# Push local changes
clasp push
 
# Open the Apps Script editor in browser
clasp open

// error-handler.gs — Error handling utilities
function createErrorCard(message) {
  return CardService.newActionResponseBuilder()
    .setNavigation(
      CardService.newNavigation().pushCard(
        CardService.newCardBuilder()
          .setHeader(
            CardService.newCardHeader().setTitle('An error occurred')
          )
          .addSection(
            CardService.newCardSection()
              .addWidget(
                CardService.newTextParagraph()
                  .setText(`⚠️ ${message}`)
              )
              .addWidget(
                CardService.newTextButton()
                  .setText('← Back')
                  .setOnClickAction(
                    CardService.newAction()
                      .setFunctionName('onHomepage')
                  )
              )
          )
          .build()
      )
    )
    .build();
}
 
/**
 * try-catch wrapper
 */
function safeExecute(fn) {
  return function(e) {
    try {
      return fn(e);
    } catch (error) {
      console.error(`Add-on error: ${error.message}`, error.stack);
      return createErrorCard(
        `An error occurred during processing: ${error.message}\n\nPlease wait a moment and try again.`
      );
    }
  };
}

// cache-helper.gs — Cache utilities
function cachedGeminiCall(prompt, options, ttlSeconds) {
  const cache = CacheService.getUserCache();
  const cacheKey = Utilities.computeDigest(
    Utilities.DigestAlgorithm.MD5,
    prompt
  ).map(b => (b < 0 ? b + 256 : b).toString(16).padStart(2, '0')).join('');
 
  const cached = cache.get(cacheKey);
  if (cached) {
    return cached;
  }
 
  const result = callGemini(prompt, options);
  // CacheService limit: 100KB / 6 hours
  cache.put(cacheKey, result, ttlSeconds || 3600);
  return result;
}

// data-sanitizer.gs — Data sanitization
function sanitizeForGemini(text) {
  // Mask email addresses
  let sanitized = text.replace(
    /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
    '[EMAIL_MASKED]'
  );
  // Mask phone numbers (US format)
  sanitized = sanitized.replace(
    /(\+1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}/g,
    '[PHONE_MASKED]'
  );
  // Mask credit card number patterns
  sanitized = sanitized.replace(
    /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,
    '[CARD_MASKED]'
  );
  return sanitized;
}

// license.gs — License management
const LICENSE_API_URL = 'https://your-backend.com/api/license';
 
/**
 * Check user's license status
 * @returns {Object} License information
 */
function checkLicense() {
  const email = Session.getActiveUser().getEmail();
  const cache = CacheService.getUserCache();
  const cacheKey = `license_${email}`;
 
  // Cache check (5 minutes)
  const cached = cache.get(cacheKey);
  if (cached) {
    return JSON.parse(cached);
  }
 
  try {
    const response = UrlFetchApp.fetch(
      `${LICENSE_API_URL}/check`,
      {
        method: 'post',
        contentType: 'application/json',
        payload: JSON.stringify({ email: email }),
        muteHttpExceptions: true,
        headers: {
          'Authorization': `Bearer ${getServiceToken()}`
        }
      }
    );
 
    const license = JSON.parse(response.getContentText());
    cache.put(cacheKey, JSON.stringify(license), 300);
    return license;
  } catch (error) {
    console.error('License check failed:', error);
    // Fallback: treat as free plan on error
    return { plan: 'free', features: ['basic'] };
  }
}
 
/**
 * Premium feature gating
 */
function requirePremium(e) {
  const license = checkLicense();
 
  if (license.plan === 'free') {
    return CardService.newActionResponseBuilder()
      .setNavigation(
        CardService.newNavigation().pushCard(
          createUpgradeCard(license)
        )
      )
      .build();
  }
 
  return null; // Premium users pass through
}
 
/**
 * Upgrade promotion card
 */
function createUpgradeCard(license) {
  return CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle('Premium Feature')
        .setSubtitle('This feature is available on the Premium plan')
    )
    .addSection(
      CardService.newCardSection()
        .addWidget(
          CardService.newTextParagraph()
            .setText(
              '🔒 This feature requires a Premium plan.\n\n' +
              '**Premium Plan Benefits:**\n' +
              '• Unlimited AI analysis\n' +
              '• Advanced proofreading & translation\n' +
              '• Priority support\n\n' +
              '$9.99/month or $99.99/year'
            )
        )
        .addWidget(
          CardService.newTextButton()
            .setText('View Plans')
            .setOpenLink(
              CardService.newOpenLink()
                .setUrl('https://your-site.com/pricing')
                .setOpenAs(CardService.OpenAs.OVERLAY)
            )
        )
    )
    .build();
}

// performance.gs — Performance optimization
/**
 * Process large text in chunks (pseudo-parallel)
 * (Apps Script doesn't support true parallelism, so we batch for efficiency)
 */
function processLargeDocument(fullText, chunkSize) {
  const chunks = [];
  for (let i = 0; i < fullText.length; i += chunkSize) {
    chunks.push(fullText.substring(i, i + chunkSize));
  }
 
  const results = [];
  const startTime = Date.now();
  const TIME_LIMIT_MS = 300000; // 5 minutes (1-minute buffer)
 
  for (const chunk of chunks) {
    if (Date.now() - startTime > TIME_LIMIT_MS) {
      results.push({
        partial: true,
        message: 'Processing time limit reached. Remaining portions will be analyzed next time.'
      });
      break;
    }
 
    const analysis = callGemini(
      `Analyze the following text:\n${chunk}`,
      { temperature: 0.3, maxTokens: 1024 }
    );
    results.push({ text: analysis });
  }
 
  return results;
}

// monitoring.gs — Usage tracking
function trackUsage(action, metadata) {
  const email = Session.getActiveUser().getEmail();
  const timestamp = new Date().toISOString();
 
  // Output structured log to Cloud Logging
  console.log(JSON.stringify({
    severity: 'INFO',
    action: action,
    user: Utilities.computeDigest(
      Utilities.DigestAlgorithm.SHA_256,
      email
    ).map(b => (b < 0 ? b + 256 : b).toString(16).padStart(2, '0')).join('').substring(0, 16),
    timestamp: timestamp,
    metadata: metadata
  }));
}