Vive Reports
Technical Details

ViveReports: Track Video Performance

Version: 1.0.0 (Current Version) Tagline: Unlock YouTube Insights, Directly in Google Sheets. Developer: ViveScript Solutions LLC Support: support@vivescriptsolutions.com Homepage: https://www.vivescriptsolutions.com/shop/subscription/vive-reports (opens in a new tab)

Project Overview

ViveReports is a powerful Google Sheets add-on that connects directly to the YouTube API, allowing you to automate your YouTube analytics tracking. With just a few clicks, pull in real-time channel and video performance data—including views, subscribers, watch time, likes, comments, CTR, and more—into your spreadsheet.

Whether you're a creator, marketer, or data analyst, ViveReports saves time and improves decision-making with structured, spreadsheet-friendly metrics. The tool offers flexible plans, including a free version and a 15-day trial of premium features, making it ideal for YouTubers of all sizes.

Primary Goal: To empower YouTube creators with accessible and actionable insights within their familiar spreadsheet environment.

Core Functionality:

  • Fetches data from YouTube Data API v3 and YouTube Analytics API.
  • Processes and populates dedicated sheets within the user's active spreadsheet.
  • Offers manual and automated data refresh options.
  • Features a dynamic dashboard and customizable reporting.
  • Implements plan-based feature access (Free, Trial, Basic, Pro).

Key Data Points:

OAuth Scopes Justifications

Based on your provided code (Code.js, UserPreferences.js, YouTubeService.js, etc.), all the OAuth scopes currently listed in your appsscript.json appear to be necessary and well-justified:

  • https://www.googleapis.com/auth/script.container.ui
    • Justification: Used to create the add-on's custom menu (📺 ViveReports) and display sidebars (AppDashboard, ChannelInfo, SettingsSidebar, HelpSidebar, ReportSetup) and modal dialogs (SubscriptionPlans) within the Google Sheets interface.
    • Necessity: Essential for any add-on that provides a user interface.
  • https://www.googleapis.com/auth/spreadsheets.currentonly
    • Justification: Used for most interactions with the active spreadsheet, such as reading configuration from the "Dashboard" sheet (e.g., date ranges), writing analytics data to channel-specific sheets, and managing the hidden "config" sheet for channel dropdowns.
    • Necessity: Required for the add-on to read from and write data to the spreadsheet it's installed in.
  • https://www.googleapis.com/auth/userinfo.email
    • Justification: Used by Session.getActiveUser().getEmail() to retrieve the user's email address. This is crucial for identifying the user for subscription status checks (UserPreferences.checkAndUpdateSubscriptionStatus), personalizing cache keys (refreshNow), and linking users to Stripe checkout sessions (doGet).
    • Necessity: Essential for user-specific features, especially subscription management.
  • https://www.googleapis.com/auth/script.scriptapp
    • Justification: Used to programmatically create, manage, and delete time-driven triggers (ScriptApp.newTrigger, ScriptApp.getProjectTriggers, ScriptApp.deleteTrigger). This enables automated daily tasks like subscription checks (getUserSubscription), data synchronization (refreshNow), and email reports (sendDailyReportEmail).
    • Necessity: Required for any automation features that run on a schedule.
  • https://www.googleapis.com/auth/script.send_mail
    • Justification: Used by MailApp.sendEmail() in the sendDailyReportEmail function to send automated performance summary emails to the user.
    • Necessity: Required for the automated email reporting feature.
  • https://www.googleapis.com/auth/youtube.readonly
    • Justification: Used by YouTubeService.js to make calls to the YouTube Data API v3 for fetching public and user-authorized channel metadata (subscribers, views, video count, titles, descriptions), video details, and discovering channels associated with the user's account.
    • Necessity: Core to retrieving basic YouTube information.
  • https://www.googleapis.com/auth/yt-analytics.readonly
    • Justification: Used by YouTubeService.js to query the YouTube Analytics API for non-monetary performance metrics (e.g., views, watch time, likes, comments, audience retention, demographics) for authorized channels.
    • Necessity: Essential for providing detailed analytics beyond basic metadata.
  • https://www.googleapis.com/auth/yt-analytics-monetary.readonly
    • Justification: Used by YouTubeService.js to query the YouTube Analytics API specifically for monetary data like estimatedRevenue for authorized and monetized channels.
    • Necessity: Required if the add-on offers revenue tracking features. This is a sensitive scope and will require clear justification to Google.
  • https://www.googleapis.com/auth/script.external_request
    • Justification: Used by UrlFetchApp.fetch() to make HTTP requests to external services. This includes calls to Google APIs (YouTube Data, YouTube Analytics), your backend API at vivescriptsolutions.com for subscription checks and Stripe checkout initiation.
    • Necessity: Fundamental for any integration with external APIs.
  • https://www.googleapis.com/auth/script.locale
    • Justification: Used by Session.getScriptTimeZone() in conjunction with Utilities.formatDate() to ensure dates and times (e.g., "Last Update" timestamps, report dates, PDF filenames) are displayed and logged correctly according to the script's configured timezone.
    • Necessity: Important for correct date/time handling and presentation.

Conclusion on OAuth Scopes: Your current list of OAuth scopes is well-aligned with the functionalities demonstrated in your codebase. No scopes appear to be unnecessary at this stage.

urlFetchWhitelist Justifications

The domains listed in your urlFetchWhitelist are also justified:

  • https://www.googleapis.com/
    • Justification: Base domain for many Google APIs, including parts of the YouTube Data API v3 (e.g., https://www.googleapis.com/youtube/v3/...).
    • Necessity: Required for direct calls to these Google API endpoints.
  • https://youtube.googleapis.com/
    • Justification: While youtubeanalytics.googleapis.com is more specific for the Analytics API, this broader domain might cover other YouTube API subdomains or future needs.
    • Necessity: Covers YouTube API services.
  • https://accounts.google.com/o/oauth2/token
    • Justification: This is the Google OAuth2 token endpoint. The OAuth2 library used by your add-on will make requests to this URL to exchange authorization codes for access tokens and to refresh tokens.
    • Necessity: Essential for the OAuth2 authentication flow.
  • https://youtubeanalytics.googleapis.com/
    • Justification: The specific endpoint for the YouTube Analytics API, called by YouTubeService.getChannelAnalyticsReport().
    • Necessity: Required for fetching detailed analytics data.
  • https://www.vivescriptsolutions.com/
    • Justification: Your backend server domain. Used for API calls related to subscription checking (Config.VIVESCRIPT_API.SUBSCRIPTION_CHECK_URL) and initiating Stripe checkout (Config.VIVESCRIPT_API.STRIPE_CHECKOUT_API_URL) as seen in UserPreferences.js and Code.js (doGet). Also hosts your add-on's logo (logoUrl in addOns.common) and potentially other image assets displayed in your HTML sidebars (e.g., HelpSidebar.html).
    • Necessity: Required for communication with your custom backend services and for the add-on framework and HTML service to load these images.

Conclusion on urlFetchWhitelist: The urlFetchWhitelist is also correctly configured. The domains listed are actively used by your add-on for its core functionality, including authentication, API interactions, and backend communication.

Setup and Installation (For Developers/Testers)

  1. Google Cloud Platform (GCP) Project:
    • Ensure you have a GCP project.
    • Enable the "YouTube Data API v3" and "YouTube Analytics API".
    • Create OAuth 2.0 credentials (Client ID & Client Secret) for a "Web application".
      • Authorized JavaScript origins: https://script.google.com
      • Authorized redirect URIs: https://script.google.com/macros/d/{SCRIPT_ID}/usercallback (replace {SCRIPT_ID} with your Apps Script project's deployment ID).
  2. Apps Script Project:
    • Copy all the .js files and appsscript.json into your Apps Script project.
    • Add the OAuth2 library:
      • Script ID: 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
      • Identifier: OAuth2
    • Script Properties: Go to File > Project properties > Script properties and add:
      • CLIENT_ID: Your Client ID from GCP.
      • CLIENT_SECRET: Your Client Secret from GCP.
      • VIVESCRIPT_BACKEND_API_KEY_FOR_CHECKOUT: Your backend API key for subscription/checkout.
  3. Deployment:
    • Deploy the script as a Web App (Deploy > New deployment):
    • Note the SCRIPT_ID from the web app URL to correctly form your redirect URI in GCP.
  4. Testing:
    • Open a Google Sheet.
    • The "📺 ViveReports" menu should appear (you might need to refresh or authorize the script for the current document first).
    • Use the "Channel Info" sidebar to initiate authorization.

Support and Legal

This README will be updated incrementally as features are developed and refined.

FAQsPrivacy Policy