Skip to main content

Google Slides Integration Explained

Table of Contents​

  1. Feature Overview
  2. Design Philosophy and Technology Selection
  3. Technical Implementation Solution 1: Template Replacement Mode
  4. Technical Implementation Solution 2: Image Insertion Mode
  5. Backend and Apps Script Collaborative Working Principle

Feature Overview​

One of InsightHub's core values is quickly transforming analysis results into deliverable professional slides. The project deeply integrates with Google Slides, allowing users to export analysis results as Google Slides presentations with one click, saving them to their own Google Drive.

Depending on different features' business scenarios and result page complexity, the project cleverly adopts two different technical solutions to implement export functionality:

  1. Template Replacement Mode: Applicable to Market Opportunity Analysis and Audience Signal Analysis. These two features have relatively fixed result page structures, suitable for using preset templates for content filling.
  2. Image Insertion Mode: Applicable to Persona Slide. This feature's results contain multiple structurally complex two-page slides. By directly "screenshotting" frontend-rendered results as images and inserting them into new slides, it can restore visual effects with the highest fidelity.

Design Philosophy and Technology Selection​

In the early stages of the project, we faced a key technology selection: should we directly control every text box, shape, and image position in Google Slides through API, or adopt a more flexible and efficient approach?

Challenges of Direct API Control:

  • High Complexity: Building a beautifully styled slide from scratch through Google Slides API requires writing a large amount of tedious code to precisely calculate and set each element's position, size, font, color, etc., with extremely high development and debugging costs.
  • Poor Flexibility: Once template styles need fine-tuning (e.g., moving a Logo, changing a title's font size), it requires modifying a large amount of backend or frontend code, making maintenance very difficult.
  • No Preview: Users cannot intuitively see the final generated slide effect before clicking export.

Our Chosen Solution: Frontend Rendering + Backend Assistance

Considering the above challenges, we decided to adopt a more modern and intelligent "separation of concerns" solution:

  1. Frontend Responsible for "Appearance": Leverage React components and CSS's powerful capabilities to directly render result data in the browser into an HTML page with 100% consistent visual effects with the final slides. This makes style adjustments very simple (just modify CSS), and users can see what you see is what you get.
  2. Backend Responsible for "Connection": Backend provides a lightweight API service, serving as a "secure bridge" between frontend and Google Apps Script. All sensitive operations, such as calling Apps Script that requires authorization, are completed through the backend, ensuring the entire process's security and stability.
  3. Apps Script Responsible for "Execution": Google Apps Script serves as the final executor for interacting with Google Workspace (Drive, Slides). It is designed to perform some standardized, atomic operations (e.g., "insert an image into a specified slide"), making the logic very clear.

This architectural design fully leverages each technology's advantages, not only perfectly implementing functionality but also greatly reducing development and maintenance complexity, making it a major design highlight of this project.

Technical Implementation Solution 1: Template Replacement Mode​

This solution is applied to Market Opportunity Analysis and Audience Signal Analysis features. Its core idea is "fill in the blanks."

Business Workflow​

  1. User clicks the "Export to Google Slides" button on the results page.
  2. System creates a new folder named after the analysis task in the user's Google Drive.
  3. System copies a pre-designed Google Slides template file to this new folder.
  4. System "screenshots" the chart (e.g., bubble chart) on the results page into an image and uploads it to this folder.
  5. System uses API to replace text placeholders in the template (e.g., {{标题}}) with text from analysis results (such as titles, strategic recommendations, etc.).
  6. System calls Apps Script to replace the image placeholder in the template (e.g., {{图片}}) with the uploaded chart image.
  7. After completion, system displays a success prompt and provides a direct link to jump to the newly generated file.

Technical Implementation Details​

sequenceDiagram
    participant U as User
    participant FE as Frontend (React Hook)
    participant BE as Backend (Node.js)
    participant GDrive as Google Drive API
    participant GSlides as Google Slides API
    participant GScript as Google Apps Script

    U->>FE: 1. Click "Export to Google Slides"
    FE->>GDrive: 2. Create Drive folder
    GDrive-->>FE: Return folder ID
    FE->>GDrive: 3. Copy template file to new folder
    GDrive-->>FE: Return new slide ID
    
    FE->>FE: 4. Render HTML chart as image (Blob)
    
    FE->>BE: 5. Call backend endpoint `/api/slides/insert-image` <br> (pass slide ID, image data, placeholder `{{图片}}`)
    BE->>GScript: 6. Call Apps Script Execution API <br> (execute `insertImageByShapeText` function)
    GScript->>GSlides: 7. Find placeholder shape and replace with image
    GScript-->>BE: Return execution result
    BE-->>FE: Return success/failure
    
    FE->>GSlides: 8. Initiate `batchUpdate` request <br> (replace all text placeholders, e.g., `{{标题}}`)
    GSlides-->>FE: Return success/failure
    
    FE->>U: 9. Display success message and file link
  • Frontend-Driven: The entire workflow is uniformly orchestrated by the frontend's custom Hook useGoogleSlidesExport.ts.
  • Template ID Configuration: Template file ID is configured in environment variable VITE_GOOGLE_SLIDES_TEMPLATE_ID, making it convenient to change templates without modifying code.
  • Image Insertion Ingenuity: Directly inserting images through Google Slides API and precisely controlling their size and position is very cumbersome. We creatively use Apps Script to implement this step: pre-place a shape with special text (e.g., {{图片}}) in the template. The Apps Script function insertImageByShapeText finds this shape and proportionally replaces it with the uploaded image. This makes image position and size control extremely simple—just drag that placeholder shape in the template.
  • Backend Role: Backend plays the role of a "secure proxy" here. Frontend sends image data and instructions to the backend, which then securely calls Apps Script on behalf of the user, avoiding complex browser cross-origin (CORS) issues and permission handling.

Technical Implementation Solution 2: Image Insertion Mode​

This solution is specifically designed for the Persona Slide feature. Its core idea is "print as image, then paste it on."

Business Workflow​

  1. User clicks the "Export to Google Slides" button on the results page.
  2. System creates a new folder in the user's Google Drive.
  3. System creates a brand new, blank Google Slides presentation in this folder.
  4. System deletes the default first blank page in this new presentation.
  5. System begins iterating through each persona (Persona) result on the frontend page: a. "Screenshot" the first page slide content of this persona into a high-resolution image. b. Call Apps Script to create a new page at the end of the presentation and insert this image as the entire content of that page. c. Also "screenshot" the second page slide content of this persona into a high-resolution image. d. Call Apps Script again to create another page at the end and insert the second image.
  6. After iterating through all personas, system displays a success prompt and provides a file link.

Technical Implementation Details​

sequenceDiagram
    participant U as User
    participant FE as Frontend (React Hook)
    participant BE as Backend (Node.js)
    participant GDrive as Google Drive API
    participant GSlides as Google Slides API
    participant GScript as Google Apps Script

    U->>FE: 1. Click "Export to Google Slides"
    FE->>GDrive: 2. Create Drive folder
    GDrive-->>FE: Return folder ID
    FE->>GDrive: 3. Create blank presentation
    GDrive-->>FE: Return new slide ID
    FE->>GSlides: 4. Delete default first blank page
    
    loop Iterate through each persona's each page
        FE->>FE: 5. Render HTML slide as image (Blob)
        FE->>BE: 6. Call backend endpoint `/api/slides/insert-image-to-blank-slide` <br> (pass slide ID, image data)
        BE->>GScript: 7. Call Apps Script Execution API <br> (execute `insertImageToBlankSlide` function)
        GScript->>GSlides: 8. Create new blank page and insert image
        GScript-->>BE: Return execution result
        BE-->>FE: Return success/failure
    end
    
    FE->>U: 9. Display success message and file link
  • Dedicated Hook: This workflow is driven by usePersonaSlideGoogleSlidesExport.ts, with completely different logic from the general Hook.
  • High-Fidelity Restoration: This solution's core advantage lies in fidelity. Since Persona Slide layouts and content are very complex, creating them element by element through API is almost impossible. Converting the carefully rendered, WYSIWYG HTML page directly into an image can 100% restore all visual details, including fonts, colors, layouts, and AI-generated images.
  • Dedicated Apps Script Function: We wrote a dedicated Apps Script function insertImageToBlankSlide for this solution. After receiving image data, it automatically creates a new blank slide at the end (or specified position) of the presentation, then inserts the image and sets it to fill the entire page, with efficient and precise operations.

Backend and Apps Script Collaborative Working Principle​

Regardless of which solution, the collaboration between backend (server/index.ts) and Apps Script (SlidePictureCode.gs) is crucial.

  1. Unified API Entry: Frontend does not directly communicate with Google or Apps Script but uniformly calls backend-provided /api/slides/* interfaces.
  2. Secure Identity Authentication: When frontend calls backend interfaces, it attaches the Google OAuth Access Token obtained during login in the request header.
  3. Backend Execution Call: After backend receives the request, it uses this Token as credentials to call Google Apps Script Execution API. This means Apps Script executes on behalf of the user, so it can only access files and folders the user has permission to access, ensuring data security.
  4. Atomic Script Functions: Functions in Apps Script are designed to be very "atomic," meaning each function only does one specific thing (e.g., "replace image based on text" or "insert image at the end"). This makes the scripts themselves very simple, stable, and easy to maintain.

Through this carefully designed collaborative mechanism, we successfully encapsulate complex Google Workspace operations into simple, secure, and efficient API calls, providing an excellent development experience for the frontend.

Related Documentation: