Architecture Assessment

This document captures the current state of the Adventive Looker Studio connector as of the April 2026 audit: module structure, data flow, API contract, and a complete register of every issue found. Use this as the baseline before applying any changes from §02.

Module inventory

File	Purpose	Lines
appscript.json	Connector manifest, metadata, auth type, OAuth scopes, exception logging, runtime version	35
Code.gs	Main connector logic, config, schema, data fetching, cache coordination, field mapping	393
Auth.gs	Authentication module, getAuthType, setCredentials, isAuthValid, resetAuth, credential validation	94
DataCache.gs	Chunked cache utility, splits responses > 100 KB across multiple CacheService keys	86

Total: 608 lines across 4 files. Lightweight and appropriately scoped for a read-only analytics connector.

Runtime

The connector runs on the Google Apps Script V8 runtime. The manifest explicitly pins "runtimeVersion": "V8". Google retired the legacy Rhino runtime on 2026-01-31; any project without "runtimeVersion": "V8" in its manifest after that date stops executing. See §05, V8 Runtime Migration for the CSV-audit triage procedure and the code-incompatibility review that scores this codebase against the Rhino → V8 delta.

Architecture

┌──────────────────────────────────────────────┐
│         Google Looker Studio (browser)        │
│  User configures connector, builds reports    │
└──────────────────┬───────────────────────────┘
                   │  Calls connector functions
┌──────────────────▼───────────────────────────┐
│         Google Apps Script Runtime            │
│                                              │
│  Auth.gs           Code.gs      DataCache.gs │
│  ─────────         ────────     ─────────── │
│  getAuthType()     getConfig()  DataCache()  │
│  setCredentials()  getSchema()  .get()       │
│  isAuthValid()     getData()    .set()       │
│  resetAuth()       fetchData()               │
│                    fetchDataFromApi()         │
│                    getColumns()              │
│                                              │
│  PropertiesService    CacheService           │
│  (credential store)   (response cache)       │
└──────────────────┬───────────────────────────┘
                   │  HTTPS
┌──────────────────▼───────────────────────────┐
│         Adventive Analytics API v2.0          │
│  https://api.adventive.com/v2.0/              │
│                                              │
│  /credentialscheck.json  (auth validation)   │
│  /dataconnector.json     (metrics data)      │
└──────────────────────────────────────────────┘

Data flow

Authentication setup (one-time per user)

User enters Integration Key + API Key in Looker Studio UI
  → Auth.setCredentials(request)
    → Auth.validateCredentials(username, password)
      → POST https://api.adventive.com/v2.0/credentialscheck.json
        Headers: X-Integration-Key, X-Api-Key
        Response 200 → valid
        Response 401 → invalid → return INVALID_CREDENTIALS error code
    → PropertiesService.getUserProperties().setProperty('dscc.username', ...)
    → PropertiesService.getUserProperties().setProperty('dscc.password', ...)

Report data fetch (every time a chart renders or refreshes)

Looker Studio calls getData(request)
  → Read credentials from PropertiesService
  → Extract dateRange.startDate, dateRange.endDate from request
  → Build DataCache with key: intKey + '_' + startDate + '_' + endDate
  → fetchDataFromCache(cache)
      CacheService.getUserCache().get(chunkKey_0, chunkKey_1, ...)
      Hit  → JSON.parse(cachedString) → content[]
      Miss →
        fetchDataFromApi(intKey, apiKey, startDate, endDate)
          GET https://api.adventive.com/v2.0/dataconnector.json
            ?data_connector=true&removeZeros=false&from=STARTDATE&to=ENDDATE
            Headers: X-Integration-Key, X-Api-Key
          → putDataInCache(content, cache)
              Splits JSON string into 100 KB chunks
              CacheService.put(chunkKey_n, chunk, 1800)
  → getColumns(content, requestedFields)
      Maps each API row to the ordered list of requested field IDs
      Returns [{values: [...]}, ...]
  → Return {schema: [...], rows: [...]} to Looker Studio

API contract

Credential validation endpoint

GET https://api.adventive.com/v2.0/credentialscheck.json
Headers:
  X-Integration-Key: <integration_key>
  X-Api-Key: <api_key>
Response:
  200 OK       → credentials valid
  401 Unauthorized → credentials invalid

Data endpoint

GET https://api.adventive.com/v2.0/dataconnector.json
  ?data_connector=true
  &removeZeros=false
  &from=YYYYMMDD
  &to=YYYYMMDD
Headers:
  X-Integration-Key: <integration_key>
  X-Api-Key: <api_key>
Response: JSON array of row objects, each keyed by field ID

Field schema (28 fields)

ID	Display name	Type	Group	Notes
an	Advertiser	DIMENSION / TEXT	Advertiser
cn	Campaign	DIMENSION / TEXT	Campaign	Default dimension
sn	Site	DIMENSION / TEXT	Campaign
pn	Placement	DIMENSION / TEXT	Campaign
adn	Ad	DIMENSION / TEXT	Campaign
ymd	Date	DIMENSION / YEAR_MONTH_DAY	,
i	Impressions	METRIC / NUMBER	Analytics	Default metric
iu	Unique Impressions	METRIC / NUMBER	Analytics
c	Clicks	METRIC / NUMBER	Analytics
cu	Unique Clicks	METRIC / NUMBER	Analytics
ctr	CTR %	METRIC / PERCENT	Analytics	Formula: SUM($c) / SUM($i), calculated in Looker Studio
e	Engagements	METRIC / NUMBER	Analytics
eu	Unique Engagements	METRIC / NUMBER	Analytics
er	ER %	METRIC / PERCENT	Analytics	Formula: SUM($eu) / SUM($i), calculated in Looker Studio
v0	Video Plays	METRIC / NUMBER	Analytics
v1	Video 25%	METRIC / NUMBER	Analytics
v2	Video 50%	METRIC / NUMBER	Analytics
v3	Video 75%	METRIC / NUMBER	Analytics
v4	Video Complete	METRIC / NUMBER	Analytics
vcr	VCR %	METRIC / PERCENT	Analytics	Formula: SUM($v4) / SUM($v0), calculated in Looker Studio

CTR, ER, and VCR are declared as formula fields in the schema. The API does not return these values, Looker Studio computes them client-side from the raw counts. This is intentional (reduces API response size).

Credential storage

Property key	Value	Scope
dscc.username	Adventive Integration Key	User properties (per-user, isolated)
dscc.password	Adventive API Key	User properties (per-user, isolated)

PropertiesService.getUserProperties() provides per-user isolation, one user’s credentials are never visible to another. There is no encryption layer beyond Apps Script’s built-in access controls.

Issues register

#	Issue	Severity	Location	Category
1	fetchDataFromApi returns the HTTPResponse object; caller passes it directly to JSON.parse(). Every non-cached data fetch crashes with a SyntaxError.	Critical	Code.gs:312	Bug
2	Integration Key (cacheToken) is written to Cloud Logging on every data request.	High	Code.gs:253	Security
3	UrlFetchApp.fetch() in validateCredentials has no muteHttpExceptions. A 401 from the API throws an uncaught exception instead of returning false.	High	Auth.gs:50	Standard compliance
4	UrlFetchApp.fetch() in fetchDataFromApi has no muteHttpExceptions. Any non-2xx response surfaces as an unhandled exception.	High	Code.gs:302	Standard compliance
5	exceptionLogging is "STACKDRIVER", deprecated name for Cloud Logging.	Medium	appscript.json	Standard compliance
6	All user-visible text says “Data Studio”. Google rebranded to “Looker Studio” in October 2022.	Medium	appscript.json, Code.gs	Standard compliance
7	Cache key does not include the requested field list. A cached response for fields A+B is returned for a subsequent request for fields A+B+C, the extra field silently returns empty strings.	Medium	DataCache.gs:30	Bug
8	validateCredentials null-checks credentials but not empty string. An empty Integration Key passes validation and makes an invalid API request.	Medium	Auth.gs:38	Bug
9	API endpoint URLs are assigned as properties on the cc (DataStudioApp) object, mutating a third-party global.	Low	Code.gs:23-24	Code quality
10	No timeout on UrlFetchApp.fetch() calls. Connector can hang for up to 30 seconds on a slow API response.	Low	Code.gs:302, Auth.gs:50	Code quality
11	throwConnectorError re-instantiates DataStudioApp.createCommunityConnector() instead of using the module-level cc.	Low	Code.gs:385	Code quality
12	DataCache.REQUEST_CACHING_TIME comment says “6 hours, Google’s max” but the value is 1800 seconds (30 minutes).	Low	DataCache.gs:18-20	Code quality
13	getColumns uses for (var i in array) to iterate numeric arrays. Harmless today with 1 to 2 elements, but for…in over arrays is a V8 foot-gun and blocks any future refactor that adds non-numeric properties.	Low	Code.gs:371, 384	V8 hygiene
14	appscript.json lacks an explicit runtimeVersion: "V8". If the project was created before 2020 it may still be on Rhino, which retires 2026-01-31.	Critical	appscript.json	Runtime

All 14 issues are addressed in §02, Code Updates. The V8-runtime-specific triage and migration procedure are in §05, V8 Runtime Migration. The rewritten files are in connector-rewrite/ (browse on GitHub).

---

Next: Code Updates