vndangkhoa/open-design
1
0
Fork 0
mirror of https://github.com/nexu-io/open-design.git synced 2026-06-01 03:14:35 +07:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
open-design/docs/seo-daily-report.md
ashleyashli 65e760b88a
feat(seo): add GSC report opportunities (#2388) 
Co-authored-by: ashley li <ashleyli@ashleydeMacBook-Air-2.local>
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-20 16:19:14 +08:00

3.6 KiB
Raw Blame History

SEO Daily Report

seo-daily-report posts a daily Google Search Console summary for sc-domain:open-design.ai to a Feishu group bot.

Workflow

  • Workflow: .github/workflows/seo-daily-report.yml
  • Script: apps/landing-page/scripts/seo-daily-report.ts
  • Schedule: every day at 09:00 Asia/Shanghai (cron: 0 1 * * *)

The report uses T-2 Search Analytics data and compares it with T-9, the same weekday one week earlier. GSC backfills recent dates, so T-2 is the stable daily reporting window. The workflow explicitly requests Search Analytics dataState: all so recently collected data is included even before Google marks it final.

Card contents

  • Site totals: clicks, impressions, CTR, average position
  • Week-over-week deltas
  • Device breakdown over the latest stable 7-day window
  • Country / region Top 5 over the latest stable 7-day window
  • Search appearance breakdown when GSC returns rich-result rows
  • Top 5 page risers by click delta
  • Top 5 page fallers by click delta
  • Top 5 query risers by click delta
  • Optimization opportunities from the latest stable 7-day window:
    • doorway queries ranking in positions 11-20
    • high-impression, low-CTR queries
    • high-ranking, low-CTR pages
    • mobile / desktop CTR gaps

Required GitHub Secrets

GSC auth reuses the same secrets as the existing blog indexing workflows. One of these auth modes must be configured:

Secret Required Notes
GSC_SERVICE_ACCOUNT_KEY Yes, unless OAuth is configured Full service-account JSON key. The service-account email must have access to the open-design.ai Search Console property.
GSC_OAUTH_CLIENT_ID Yes, for OAuth mode Existing OAuth mode used by blog indexing workflows.
GSC_OAUTH_CLIENT_SECRET Yes, for OAuth mode Existing OAuth mode used by blog indexing workflows.
GSC_OAUTH_REFRESH_TOKEN Yes, for OAuth mode Existing OAuth mode used by blog indexing workflows.

Feishu posting requires:

Secret Required Notes
FEISHU_WEBHOOK_URL Yes Custom bot webhook URL from the target Feishu group.
FEISHU_WEBHOOK_SECRET No Required only if signing verification is enabled for the custom bot.

Data windows

The report uses two windows:

Section Window Why
Site totals and Top 5 movers T-2 vs T-9 Same-weekday daily comparison.
Device, country, search appearance, optimization opportunities T-8 through T-2 A 7-day window smooths daily noise and gives enough volume for action candidates.

All Search Analytics calls use dataState: all so recent GSC rows are included before Google marks them final.

Opportunity thresholds

These environment variables tune the optimization section:

Variable Default Meaning
OPP_MIN_IMPRESSIONS 30 Minimum impressions before a query/page is considered actionable.
OPP_LOW_CTR 0.01 CTR below this value is treated as low CTR.
OPP_MOBILE_DESKTOP_CTR_GAP 0.30 Relative CTR gap between mobile and desktop before surfacing a device issue.

The current defaults are intentionally low because open-design.ai is still building GSC history. Tighten them as traffic grows.

Manual test

From GitHub Actions:

  1. Open Actions -> seo-daily-report.
  2. Click Run workflow.
  3. Optional: set dry_run to true to build the card and print JSON without posting to Feishu.
  4. Optional: set today to a YYYY-MM-DD value to test a fixed reporting date.

From a local checkout with secrets exported:

pnpm --filter @open-design/landing-page exec tsx scripts/seo-daily-report.ts --dry-run

Remove --dry-run to post to Feishu.