π 11.4 β Client A β GSC + Vercel Full Implementation Handbook
Dabbo 11 Β· Client Reporting System Β·
Gujarati-English | Updated 06 Nov 2026
Boundary:Β Current Netlify production is untouched. Vercel is Preview/migration only. Do not change production branch, domain, alias, or promote without owner approval.
11.4.A 0. Ek line ma architecture
GSC β daily scheduler (05:30 IST) β GitHub main/data.json β Vercel API β dashboard.
Vercel = hosting/deployment + serverless API. Vercel GSC data scheduler NAHI. 05:30 nu data collection existing scheduled automation kare che β e 13 GSC properties fetch kare, historical rows merge kare ane data.json commit kare.
11.4.B 1. Hal nu known setup
| Item | Value |
|---|---|
| GitHub repo | client-a-store/gsc (private) |
| Data branch | main |
| Vercel Preview branch | migration/vercel |
| Vercel project | team nu Vercel project (Vercel dashboard ma dekhay) |
| Team slug / ID | Vercel dashboard ma dekhay |
| Project ID | Vercel dashboard ma dekhay |
| Plan / region | Hobby / bom1 |
| Scheduler ID | team na records ma check karo |
| Scheduler | Daily 05:30 Asia/Kolkata |
Last documented manual GSC sync: 04 Nov 2026; commit (team na records ma). Ae sync pachhi Vercel Preview health pass thayo (13/13 projects valid). Netlify live endpoint ae environment ma independently verify thayu nahi β aanu matlab e nathi ke Netlify down che.
Boundary: Current Netlify production untouched. Vercel = fakt Preview/migration. Production branch, domain, alias ke promotion owner na written approval vagar NA badalvu.
11.4.C 2. Vercel shu kare che
- Static HTML/CSS/JS host kare.
- GitHub sathe connect thay, push par deploy kare.
- Non-production branches ne Preview deployments male.
- Configured production branch production ma deploy thay.
- api/*.js files server-side Node.js Functions bane.
- Environment Variables ma secrets server-side store thay.
Important: 05:30 nu GSC collection existing scheduled automation kare, Vercel Cron nahi. /api/gsc-health par Vercel Cron fakt data CHECK kare β e GSC fetch nathi kartu ke GitHub update nathi kartu.
11.4.D 3. Repo Vercel sathe connect karo
- vercel.com/dashboard par sign in karo.
- Team select karo, personal account nahi.
- Add New β Project.
- GitHub repo client-a-store/gsc import karo.
- Existing project reuse karo β duplicate project NA banavvo.
- Framework preset: Other.
- Root directory: repo root.
- Aa plain HTML + Node API source ma root package.json ke vercel.json nathi, etle build command/install ni jarur nathi β Vercel defaults j rakho (pachhi repo ma build system aave to change).
- Git connection ane Preview branch deployment confirm karo.
- Production Branch NA badalvo ane production domain NA attach karo β aa fakt Preview setup che.
Branch discipline
- main: canonical saved GSC snapshot ane existing production workflow.
- migration/vercel: Vercel Preview migration.
- Preview code fakt migration/vercel par push karo; commit + Preview URL verify karo.
- Production promotion/domain/alias changes mate written approval joie.
Example push:
git checkout migration/vercel
git pull origin migration/vercel
git status
git diff
git add api/gsc.js api/gsc-health.js index.html
git commit -m "fix: update GSC dashboard API"
git push origin migration/vercel11.4.E 4. GitHub token β Vercel Environment Variable
API private GitHub main/data.json vanche che, etle Vercel ne server-side GITHUB_TOKEN joie.
- GitHub β Settings β Developer settings β Personal access tokens β Fine-grained tokens.
- Resource owner: client-a-store.
- Repository access: fakt gsc repo.
- Permissions: Contents Read-only; Metadata Read-only/default.
- Token generate karo; copy fakt Vercel ma j karo. Chat, docs, source code, HTML, screenshot ke logs ma KYAREY paste na karo.
- Vercel β tamaro project β Settings β Environment Variables.
- Name: GITHUB_TOKEN; value: token; target: Preview (branch-specific preview env use karta hoy to branch restriction migration/vercel).
- Save karo ane latest Preview deployment redeploy karo. Environment changes already-built deployments par automatic apply nathi thata.
- /api/gsc-health test karo; expected: ok:true, 13 expected/checked projects, allProjectsValid true.
Token browser ma kyarey return thavu NA joie. Exposed ke expired thay to rotate karo.
11.4.F 5. API route map
| File | Route | Kam |
|---|---|---|
| api/gsc.js | /api/gsc?site=Client A&start=2026-10-01&end=2026-10-31 | Private GitHub snapshot vanchi ne daily rows filter kare |
| api/gsc-health.js | /api/gsc-health | 13 projects ane numeric daily rows validate kare |
| index.html | / | Dashboard UI; /api/gsc call kare |
11.4.G 6. Copy/paste: api/gsc.js
File path exactly api/gsc.js banao:
const SITES = {
/* team na 13 client projects nu mapping β naam public ma share karvana nahi */
};
export default async function handler(req, res) {
res.setHeader("Cache-Control", "no-store, max-age=0");
res.setHeader("Content-Type", "application/json; charset=utf-8");
if (req.method !== "GET") return res.status(405).json({ ok: false, error: "Method not allowed." });
const site = String(req.query.site || "Client A");
const hasStart = Boolean(req.query.start);
const hasEnd = Boolean(req.query.end);
// Site-only request = safe health check, full saved history aape.
// Dashboard hamesha explicit start/end dates pass kare.
const start = hasStart && hasEnd ? String(req.query.start) : (!hasStart && !hasEnd ? "1900-01-01" : "");
const end = hasStart && hasEnd ? String(req.query.end) : (!hasStart && !hasEnd ? "9999-12-31" : "");
const datePattern = /^\d{4}-\d{2}-\d{2}$/;
if (!SITES[site]) return res.status(400).json({ ok: false, error: "Unknown project selected." });
if (!datePattern.test(start) || !datePattern.test(end) || start > end) {
return res.status(400).json({ ok: false, error: "Provide both valid start and end dates, or omit both for a full-history health check." });
}
const token = process.env.GITHUB_TOKEN;
if (!token) return res.status(500).json({ ok: false, error: "GitHub read token is not configured on this Vercel environment." });
try {
const url = "https://api.github.com/repos/client-a-store/gsc/contents/data.json?ref=main&nocache=" + Date.now();
const response = await fetch(url, {
cache: "no-store",
headers: {
Accept: "application/vnd.github+json",
Authorization: "Bearer " + token,
"X-GitHub-Api-Version": "2022-11-28",
"Cache-Control": "no-cache, no-store",
Pragma: "no-cache"
}
});
if (!response.ok) throw new Error("GitHub snapshot request failed (" + response.status + ").");
const file = await response.json();
if (file.encoding !== "base64" || !file.content) throw new Error("GitHub snapshot content is missing or not base64 encoded.");
const snapshot = JSON.parse(Buffer.from(file.content.replace(/\s/g, ""), "base64").toString("utf8"));
const project = snapshot.projects && snapshot.projects[site];
if (!project) throw new Error("No saved GSC snapshot exists for this project yet.");
const daily = (project.daily || [])
.filter(row => row.date >= start && row.date <= end)
.map(row => ({
date: row.date,
clicks: Number(row.clicks || 0),
impressions: Number(row.impressions || 0),
ctr: Number(row.ctr || 0),
position: Number(row.position || 0)
}));
return res.status(200).json({
ok: true,
project: project.name,
siteUrl: project.siteUrl,
start,
end,
fetchedAt: snapshot.updatedAt,
daily,
pages: [],
source: "github-api-private-snapshot"
});
} catch (error) {
console.error("GSC snapshot load failed:", error);
return res.status(502).json({ ok: false, error: "Could not load the scheduled GSC snapshot. Check the GitHub token permissions and Vercel Function logs." });
}
}11.4.H 7. Copy/paste: api/gsc-health.js
File path exactly api/gsc-health.js banao:
const EXPECTED = ["Client A","client_d","client_d","client_e","client_f","client_g","Client Bbox","client_h","client_i","client_j","client_k","client_l","client_m"];
export default async function handler(req, res) {
res.setHeader("Cache-Control", "no-store, max-age=0");
res.setHeader("Content-Type", "application/json; charset=utf-8");
if (req.method !== "GET") return res.status(405).json({ ok: false, error: "Method not allowed." });
const token = process.env.GITHUB_TOKEN;
if (!token) return res.status(500).json({ ok: false, error: "GitHub read token is not configured." });
try {
const url = "https://api.github.com/repos/client-a-store/gsc/contents/data.json?ref=main&nocache=" + Date.now();
const response = await fetch(url, {
cache: "no-store",
headers: {
Accept: "application/vnd.github+json",
Authorization: "Bearer " + token,
"X-GitHub-Api-Version": "2022-11-28",
"Cache-Control": "no-cache, no-store",
Pragma: "no-cache"
}
});
if (!response.ok) throw new Error("GitHub snapshot request failed (" + response.status + ").");
const file = await response.json();
if (file.encoding !== "base64" || !file.content) throw new Error("GitHub snapshot content is missing or not base64 encoded.");
const snapshot = JSON.parse(Buffer.from(file.content.replace(/\s/g, ""), "base64").toString("utf8"));
const projects = snapshot.projects || {};
const checks = EXPECTED.map(key => {
const project = projects[key];
const daily = project && Array.isArray(project.daily) ? project.daily : [];
const latestDate = daily.reduce((latest, row) => row.date > latest ? row.date : latest, "");
const validRows = daily.every(row =>
/^\d{4}-\d{2}-\d{2}$/.test(row.date) &&
Number.isFinite(Number(row.clicks)) &&
Number.isFinite(Number(row.impressions)) &&
Number.isFinite(Number(row.ctr)) &&
Number.isFinite(Number(row.position))
);
return { key, present: Boolean(project), rows: daily.length, latestDate, validRows };
});
const ok = checks.every(item => item.present && item.validRows);
return res.status(ok ? 200 : 503).json({
ok,
source: "github-api-private-snapshot",
branch: "main",
fetchedAt: snapshot.updatedAt || null,
expectedProjects: EXPECTED.length,
checkedProjects: checks.length,
allProjectsValid: ok,
projects: checks
});
} catch (error) {
console.error("GSC health check failed:", error);
return res.status(502).json({ ok: false, error: "Could not verify the GitHub GSC snapshot. Check GitHub token permissions and Vercel Function logs." });
}
}11.4.I 8. data.json schema
Root keys: updatedAt, projects. Darek project ma: name, siteUrl, daily. Daily fields: date, clicks, impressions, ctr, position. CTR decimal ratio ma store thay (0.01 = 1%).
{
"updatedAt": "2026-11-04T05:55:52.339Z",
"projects": {
"Client A": {
"name": "Client A Products",
"siteUrl": "https://client-a-store.com/",
"daily": [
{"date":"2026-11-01","clicks":29,"impressions":2500,"ctr":0.0116,"position":8.4}
]
}
}
}
Aa fakt ek project nu abbreviated schema sample che, full production data nahi.
11.4.J 9. Front-end API fetch example
Browser same-origin Vercel API ne j call kare; browser mathi GitHub private API KYAREY call na karo:
async function loadGsc(site, start, end) {
const params = new URLSearchParams({ site, start, end });
const response = await fetch(`/api/gsc?${params.toString()}`, {
method: "GET",
cache: "no-store",
headers: { "Accept": "application/json" }
});
const data = await response.json();
if (!response.ok || !data.ok) {
throw new Error(data.error || `GSC API failed (${response.status})`);
}
return data;
}
Aa reference helper che; index.html ni existing dashboard rendering logic preserve rakho.
11.4.K 10. Daily 05:30 scheduler workflow
- 05:30 Asia/Kolkata trigger.
- 13 GSC properties query karo.
- Daily date rows ane metrics normalize karo.
- Date key thi junia history sathe merge karo; duplicate rows nahi; juna rows preserve.
- data.json GitHub main ma commit karo.
- main/data.json pacho vanchi ne JSON ane project count validate karo.
- Vercel Preview health endpoint call karo.
- /api/gsc ane dashboard smoke-test karo.
GSC reporting ma delay hoy shake. Missing dates ne zero thi NA bharo β next scheduled run data available thay tyare backfill/merge kare. Existing scheduler ID team na records ma check karo. Approved tested migration vagar duplicate schedules NA banavvo.
11.4.L 11. Vercel Cron β optional, current data-fetch system NAHI
Vercel Cron deployed route par HTTP request moke che. E GSC connect nathi kartu ke GitHub write nathi kartu. Cron /api/gsc-health call kare to fakt snapshot check thay. Full GSC ETL mate OAuth/service-account auth, API query code, merge/write logic, retries, idempotency/locking ane monitoring joie. Replacement end-to-end test thaya sudhi current working scheduler j rakho.
11.4.M 12. Verification URLs
| Check | Request | Expected |
|---|---|---|
| Homepage | Preview URL / | HTTP 200, HTML |
| Health | /api/gsc-health | HTTP 200, ok:true, 13/13 valid |
| Full history | /api/gsc?site=Client A | HTTP 200, daily array |
| Date filter | /api/gsc?site=Client A&start=2026-10-01&end=2026-10-31 | fakt requested dates |
| Unknown site | site=unknown with valid dates | HTTP 400 |
| Ek date missing | fakt start supplied | HTTP 400 |
11.4.N 13. Daily checklist
- Aaj nu 05:30 run complete thayu?
- 13 properties fetch thai? Failures log thaya?
- Latest GSC date check kari; zero-filling nathi?
- GitHub main commit ane updatedAt check karya?
- JSON valid, 13 projects hazar, duplicate dates nathi?
- Health endpoint HTTP 200 / ok true / allProjectsValid true?
- /api/gsc response ane dashboard display check karya?
- GA4/Shopify business conversions alag source thi lidha?
11.4.O 14. Troubleshooting
| Error | Likely cause | Fix |
|---|---|---|
| API 500 token missing | Preview env var missing | GITHUB_TOKEN Preview ma umero; redeploy karo |
| API 502 | GitHub API, token scope, rate limit, invalid JSON | Vercel Function logs juo; token read scope + JSON verify karo |
| GitHub 404 | Khotu repo/path/ref ke private repo access | Repo, data.json, ref=main verify karo |
| GitHub 403 | Token/org approval/rate limit | GitHub token repo access ane approval check karo |
| API 400 | Invalid site/date args | Exact site key ane banne YYYY-MM-DD dates vapro |
| Health 503 | Missing project ke invalid row | JSON structure ane merge inspect karo |
| Homepage OK, API fails | Function/env problem | Health endpoint test karo; function logs juo |
| Preview current, Netlify stale | Alag hosting pipelines | Assume na karo ke Preview Netlify update kare |
| Latest date absent | GSC delay | Absent j raheva do; next run ma backfill |
11.4.P 15. Security
- Code/docs/chat/screenshots ma secrets nahi.
- GitHub fine-grained token fakt selected repo + Contents Read-only sudhi limited.
- Secrets Vercel Environment Variables ma store.
- Token browser ke error response ma return nathi.
- Leaked/expired token rotate karo.
- Private repo ane Vercel team access restrict karo.
- Production secrets valo unreviewed code deploy na karo.
- Approval vagar Preview promote ke domain/alias change na karo.
11.4.Q 16. GSC metrics vs business goals
- Clicks, impressions, CTR, position β GSC.
- Organic Search sessions/users ane engagement β GA4.
- Purchases/revenue β Shopify + GA4 purchase event.
- Leads/forms/calls β GA4 event + CRM/call/form tracking.
- CTR = clicks Γ· impressions Γ 100.
- GSC period-level average position vapro; daily average positions nu manually average NA karvu.
- Example goal: 700 clicks baseline, 770 target (+10%); actual/target Γ 100 = achievement. Targets team-defined che.
11.4.R 17. Production cutover / rollback
Current state = fakt Preview. Cutover pehla test karo: badhi 13 properties, historical data, API, mobile/desktop, analytics, env vars, domain, SSL ane rollback. Production branch/domain/alias changes mate written approval lo. Vercel production stable prove thaya sudhi existing Netlify deployment available rakho. Aa SOP ma production change NAHI.
11.4.S 18. Minimum-deployment strategy β badha projects ma reusable
Goal: minimum unnecessary Vercel deployments, GitHub API reads/writes, GSC queries, automation runs ane AI/token usage sathe reliable dashboard.
18.1 Recommended architecture: code rarely deploy karo, data alag update karo
| Layer | Minimum strategy | Usage kem bade |
|---|---|---|
| Hosting | Darek genuinely alag app/repo mate ek Vercel project. Same dashboard ghana sites use kare to config-driven site list valo ek shared multi-site app. | Duplicate projects ane repeated build/deploy work oche. |
| Deployments | Fakt code/config changes mate deploy. Feature work Preview par; Production fakt approval pachhi. | Data refresh mate navi deployment jaruri nathi. |
| Data | Ek canonical GitHub JSON snapshot; file size measured problem bane to j partition. | Scheduled batch dida ek j merge/write. |
| API | Ocha serverless endpoints query parameters thi badha site keys serve kare. | Same API na 13 copies bachave. |
| Scheduler | Ek scheduled job configured properties par loop kare. | Property dida automation ane duplicate polling bachave. |
| Health | Successful data commit pachhi ek health check. | High-frequency checks bachave. |
| Secrets | Deployment/repo boundary dida least-privilege read-only GitHub token. | Secret sprawl ane permission surface ghatare. |
18.2 Deployment decision rule
- Data-only change (data.json ma navi rows): Vercel redeploy NA karo. API request vakhte latest GitHub main snapshot vanche.
- Dashboard/API code change: migration/vercel par ek reviewed commit push karo; Git integration ek Preview deployment banave.
- Preview pass + release approved: production release process follow karo. Daily data refresh mate deploy NA karo.
- Same dashboard ma vadhare properties: site config entry umero; darek site mate whole dashboard/API clone NA karo.
- Alag client/team jena secrets, access rules, billing ke branding alag hoy: isolation joie to alag project/repo vapro.
- Related code/config edits batch kari ne ek var deploy karo; environment-variable changes ne pan effect mate navi deployment joie.
18.3 GitHub, GSC ane API usage ocho rakho
- GSC: daily run ma property dida required date window mate ek Search Analytics query; fakt required dimensions (date) ane metrics. Same run ma identical queries repeat na karo.
- Backfill: fakt missing/recent dates ke bounded lookback query karo; date key thi idempotently merge karo.
- GitHub: merged JSON memory ma taiyar kari ne badha properties process thaya pachhi ek var commit karo; site/date dida commit nahi.
- Scheduler GitHub reads: merge pehla ek var vancho ane commit pachhi validation mate ek var pacho vancho.
- Dashboard: fakt selected site ane selected date range fetch karo; portfolio totals na joie to darek page view par badhi 13 sites fetch na karo.
- Health: commit pachhi ek var; dar thoda seconds polling nahi.
- No-op: content unchanged hoy to commit skip kari ne "no new finalized GSC rows" record karo; no-op mate KYAREY deployment trigger na karo.
- Retries: transient 429/5xx ne exponential backoff ane ocha max attempts sathe retry karo; Retry-After honor karo; KYAREY infinite loop nahi.
- Existing 05:30 automation duplicate karva second Vercel Cron NA umero.
18.4 Reusable multi-project config
Navi authorized GSC property umeravi hoy to API files copy karva na badle site configuration ma key/name umero:
const SITES = {
/* team na 13 client projects nu mapping β naam public ma share karvana nahi */
};
Matching project key data.json ma ane health endpoint ni expected project list ma pan hovo joie. Aa lists sync ma rakho; ideally project registry ek shared config module ma move karo jethi drift na thay.
18.5 Minimum-usage operating profile
| Activity | Recommended cadence | Avoid |
|---|---|---|
| GSC fetch | Property dida daily 05:30 IST ek var | Repeated same-window queries/hourly polling |
| GitHub commit | Batch dida max ek data snapshot commit | Property/date dida commit |
| Vercel deploy | Fakt reviewed code/config changes | Darek data refresh pachhi deploy |
| Health endpoint | Commit pachhi ek var + manual diagnosis | Continuous high-frequency polling |
| Dashboard API | Page load / selected filter change | Badha projects repeatedly re-fetch |
| Preview builds | Meaningful code push dida ek | Tiny commits je ghana builds trigger kare |
Quota note: Vercel plan limits, GitHub API limits, GSC quotas ane AI/automation usage account pramane alag hoy ane time sathe badlay. Aa guide free-tier quotas hard-code nathi karti. Hard numeric caps nakhta pehla Vercel Usage/Billing, GitHub rate-limit headers ane current GSC quota docs check karo.
18.6 Trade-offs ane safeguards
- Shared multi-site dashboard duplicate deployments ghatare, pan badha sites same release cycle share kare; representative properties test karo.
- Ek moto JSON simple che ane GitHub operations minimize kare. Response size ane performance measure karya pachhi j project/month pramane partition karo.
- Serverless instances in-memory cache reliably share na pan kare. Correctness mate memory cache par KYAREY rely na karo.
- Short caching repeat GitHub reads ghatare pan briefly stale data batavi shake. Freshness matter kare to current no-store behavior j rakho; acceptable hoy to j measured short TTL umero.
- Current API darek request par private GitHub main/data.json vanche. Safest savings = duplicate browser fetches ocha karva, authorization remove karvo ke failures hide karva nahi.
Reusable principle: one scheduler β one batch fetch β one merge β one commit β one health check; deploy fakt tyare jyare code change thay.
11.4.T 19. Onboarding checklist
- GitHub repo ane correct branch access
- Vercel correct team/project access
- Preview deployment READY
- Preview GITHUB_TOKEN configured (secret kyarey share nathi)
- Health endpoint pass
- GSC API date filter pass
- Daily 05:30 automation enabled ane run history inspect karyu
- Historical data preserved / duplicate dates nathi
- GA4/Shopify conversion sources documented
- Approval vagar production untouched
11.4.U Official docs β shu vanchvu
Vadhare detail joie to aa official docs search kari ne vancho (trainee mate search terms):
- "Vercel deployments docs" β deployments kevi rite kam kare
- "Vercel git docs" β Git integration ane Preview/Production branches
- "Vercel environment variables docs" β env vars set karva
- "Vercel functions docs" β serverless Node.js functions
- "GitHub fine-grained personal access token docs" β token banana ane permissions
- "Search Console API searchanalytics.query docs" β GSC data query format
Important: Aa API code blocks 06 Nov 2026 na inspected migration/vercel branch mathi copied che. Scheduler OAuth/connector credentials janbuji ne include nathi β darek operator potanu authorized account securely connect kare.