01 — 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 — April 2026 audit

#	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–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: 02 — Code Updates