Search Console (μόνο για ανάγνωση)

Πίνακας Google Search Console μόνο για ανάγνωση: τα κορυφαία ερωτήματα και οι σελίδες σας με εμφανίσεις, κλικ, CTR και μέση θέση, συνδεδεμένα με τις σελίδες που γνωρίζει ήδη ο σαρωτής — ώστε να βλέπετε σε ένα σημείο ότι «αυτή η σελίδα έχει προβλήματα και χάνει εμφανίσεις». Είναι ανενεργός από προεπιλογή.

Τρία στοιχεία καθορίζουν τον σχεδιασμό:

• Αυστηρά μόνο για ανάγνωση. Η ενσωμάτωση ζητά ένα μόνο πεδίο πρόσβασης OAuth — webmasters.readonly — ορισμένο σταθερά στον κώδικα του πακέτου. Διαβάζει μόνο Search Analytics: δεν υποβάλλει ποτέ χάρτη ιστοτόπου, δεν ζητά ευρετηρίαση ούτε αλλάζει οτιδήποτε στο Search Console. Δεν υπάρχει ρύθμιση που να διευρύνει το πεδίο πρόσβασης.
• Δική σας ιδιοκτησία, δικά σας διαπιστευτήρια. Τα αιτήματα πηγαίνουν από τον δικό σας διακομιστή απευθείας στο Google, με έλεγχο ταυτότητας μέσω των δικών σας διαπιστευτηρίων λογαριασμού υπηρεσίας ή OAuth. Δεν μεσολαβεί διακομιστής του πακέτου, ούτε μέτρηση χρεώσιμης χρήσης ή μεταπώληση, και το πακέτο δεν στέλνει τηλεμετρία.
• Τα σφάλματα εμφανίζονται στο σχετικό σημείο. Διαπιστευτήρια που λείπουν, απάντηση 403, σφάλματα ορίων χρήσης ή λήξεις χρόνου εμφανίζουν ενσωματωμένο μήνυμα χωρίς να διακόπτουν την απόδοση του πίνακα. Η εντολή συγχρονισμού ιστορικού αναφέρει τις αποτυχίες και σταματά την ανάκτηση επόμενων ημερών, όπως περιγράφεται παρακάτω.

Τι παρέχει

• Σελίδες που χρειάζονται προσοχή — ο ουσιαστικός συνδυασμός: σελίδες με ανοιχτά προβλήματα σάρωσης που εξακολουθούν να δέχονται κίνηση από αναζητήσεις, με προτεραιότητα στη μεγαλύτερη ευκαιρία (τις περισσότερες εμφανίσεις μεταξύ των σελίδων με προβλήματα). Διορθώστε πρώτα αυτές.
• Κορυφαίες σελίδες και Κορυφαία ερωτήματα — οι συνήθεις πίνακες Search Analytics.

Στον πίνακα ελέγχου Filament είναι η σελίδα Search Console στην ομάδα πλοήγησης SEO (εμφανίζεται μόνο όταν είναι ενεργή η ενσωμάτωση). Σε headless χρήση, τις ίδιες μετρήσεις παρέχουν η εντολή seo-pro:search-console και το SeoPro::searchConsole().

Εγκατάσταση και ρύθμιση

Χρειάζεστε διαπιστευτήρια Google με πρόσβαση ανάγνωσης στην ιδιοκτησία Search Console. Υποστηρίζονται δύο τρόποι· ο λογαριασμός υπηρεσίας είναι ο απλούστερος για διακομιστή.

Λογαριασμός υπηρεσίας (προτείνεται)

1. Στο Google Cloud, ενεργοποιήστε το Search Console API και δημιουργήστε λογαριασμό υπηρεσίας· κατεβάστε το κλειδί JSON του.
2. Στο Search Console → Ρυθμίσεις → Χρήστες και δικαιώματα, προσθέστε το email του λογαριασμού υπηρεσίας (…@….iam.gserviceaccount.com) ως χρήστη (η περιορισμένη πρόσβαση αρκεί για ανάγνωση).
3. Ορίστε στο πακέτο το κλειδί και την ιδιοκτησία:

SEO_PRO_GSC_ENABLED=true
SEO_PRO_GSC_CONNECTION=service_account
# The raw JSON, OR an absolute path to the .json key file:
SEO_PRO_GSC_CREDENTIALS=/etc/secrets/gsc-service-account.json
# The property exactly as it appears in Search Console:
SEO_PRO_GSC_SITE_URL=https://example.com/
# or a Domain property:  SEO_PRO_GSC_SITE_URL=sc-domain:example.com

Αν παραλείψετε το SEO_PRO_GSC_SITE_URL, η ιδιοκτησία προθέματος URL προκύπτει από το app.url.

OAuth (refresh token για πρόσβαση εκτός σύνδεσης)

Αν έχετε πελάτη OAuth και refresh token μεγάλης διάρκειας, κατά προτίμηση εξουσιοδοτημένο μόνο για webmasters.readonly, ρυθμίστε το παρακάτω. Κάθε ανανέωση ζητά αυτό το πεδίο πρόσβασης. Το πακέτο απορρίπτει το token που επιστρέφεται αν η απάντηση δεν επιβεβαιώνει ρητά ακριβώς το πεδίο μόνο για ανάγνωση· δεν θεωρεί δεδομένο ότι το Google περιορίζει πάντα μια ευρύτερη εξουσιοδότηση.

SEO_PRO_GSC_ENABLED=true
SEO_PRO_GSC_CONNECTION=oauth
SEO_PRO_GSC_OAUTH_CLIENT_ID=xxxx.apps.googleusercontent.com
SEO_PRO_GSC_OAUTH_CLIENT_SECRET=...
SEO_PRO_GSC_OAUTH_REFRESH_TOKEN=1//...
SEO_PRO_GSC_SITE_URL=https://example.com/

Δημοσιεύστε τη μετανάστευση token

Η κρυπτογραφημένη cache access token βρίσκεται στον πίνακα seo_gsc_tokens. Δημοσιεύστε τη μετανάστευση και εκτελέστε τη μία φορά:

php artisan vendor:publish --tag=seo-pro-migrations
php artisan migrate

Έπειτα επιβεβαιώστε τη ρύθμιση με το php artisan seo:doctor — αναφέρει αν το Search Console είναι ενεργό και ρυθμισμένο (χωρίς κλήση δικτύου, χωρίς να εμφανίζει ποτέ μυστικό).

Headless χρήση

# Pages with open issues AND search traffic (the default view):
php artisan seo-pro:search-console

# Top pages / top queries:
php artisan seo-pro:search-console --view=pages
php artisan seo-pro:search-console --view=queries

# Window + size, and machine-readable output:
php artisan seo-pro:search-console --view=queries --days=7 --limit=25 --json

use Rankbeam\Seo\Pro\Facades\SeoPro;

$gsc = SeoPro::searchConsole();

$gsc->isConfigured();             // bool, no network
$gsc->topQueries();               // SearchConsoleResult (rows: GscRow[])
$gsc->topPages(days: 7);          // SearchConsoleResult
$gsc->pagesNeedingAttention();    // rows annotated with issueCount + score

$result = $gsc->topQueries();
if ($result->ok) {
    foreach ($result->rows as $row) {
        // $row->key, ->clicks, ->impressions, ->ctrPercent(), ->position
    }
} else {
    // $result->errorCode (a stable code), $result->errorMessage (sanitized)
}

Ιστορικές μετρήσεις

Ο παραπάνω πίνακας και η εντολή διαβάζουν ζωντανό κυλιόμενο χρονικό παράθυρο — το ίδιο το Search Console είναι ο μόνος χώρος αποθήκευσης. Για ιστορικό ανά ημέρα που μπορείτε να αναζητήσετε για οποιαδήποτε παλαιότερη περίοδο, εκτελέστε την εντολή συγχρονισμού, η οποία αποθηκεύει μετρήσεις ανά ημέρα, ανά ερώτημα και ανά σελίδα στον πίνακα seo_gsc_metrics:

# Publish + run the migration once (creates seo_gsc_metrics):
php artisan vendor:publish --tag=seo-pro-migrations
php artisan migrate

# Backfill on the first run, then keep it current — schedule it daily:
php artisan seo-pro:gsc-sync

# Pull a specific number of days back (forces a full re-pull of that window):
php artisan seo-pro:gsc-sync --days=180

// app/Console/Kernel.php (or bootstrap/app.php withSchedule)
$schedule->command('seo-pro:gsc-sync')->daily();

• Η πρώτη εκτέλεση ανακτά αναδρομικά sync.backfill_days (προεπιλογή 90· το Search Console διατηρεί περίπου 16 μήνες, οπότε αυξήστε την τιμή για περισσότερα). Οι επόμενες εκτελέσεις συνεχίζουν από την τελευταία αποθηκευμένη ημερομηνία, ανακτώντας ξανά sync.overlap_days στο τέλος του παραθύρου ώστε να συμπεριλάβουν την καθυστερημένη οριστικοποίηση πρόσφατων δεδομένων του Search Console. Το παράθυρο τελειώνει πάντα 3 ημέρες πριν (λόγω της καθυστέρησης δεδομένων).
• Ιδιοδύναμος συγχρονισμός. Οι γραμμές εισάγονται ή ενημερώνονται με βάση το (date, dimension, key), οπότε η επανεκτέλεση είναι ασφαλής. Ημέρα που αποτυγχάνει (π.χ. λόγω ορίου χρήσης) σταματά ομαλά την εκτέλεση και αναφέρει πόσες γραμμές αποθηκεύτηκαν· η επόμενη εκτέλεση συνεχίζει από εκεί που σταμάτησε.
• Πού χρησιμοποιείται. Οι μεγαλύτερες μεταβολές Search Console της αναφοράς με δική σας επωνυμία χρησιμοποιούν πραγματικό ιστορικό σύγκρισης περιόδων (αυτή η περίοδος έναντι του αμέσως προηγούμενου ισοδύναμου διαστήματος), μόλις ο πίνακας καλύπτει και τις δύο περιόδους, αντί να υπολογίζουν διαφορές από το στιγμιότυπο της προηγούμενης αναφοράς. Αποτελεί επίσης τη βάση για πιο εκτενή ανάλυση λέξεων-κλειδιών.

Αποθηκεύονται μόνο συγκεντρωτικές μετρήσεις — το κείμενο του ερωτήματος, η URL της σελίδας και οι τέσσερις μετρήσεις (κλικ, εμφανίσεις, CTR, θέση) ανά ημέρα. Δεν ανακτώνται ούτε γράφονται ποτέ δεδομένα ανά χρήστη ή ανά αίτημα.

Διαχείριση δεδομένων και ασφάλεια

• Έλεγχος πεδίου πρόσβασης μόνο για ανάγνωση. Το JWT λογαριασμού υπηρεσίας ζητά μόνο webmasters.readonly. Το ίδιο κάνουν τα αιτήματα ανανέωσης OAuth, και το πακέτο απορρίπτει απάντηση χωρίς πεδίο πρόσβασης ή με ευρύτερο πεδίο. Χρησιμοποιήστε διαπιστευτήρια εξουσιοδοτημένα μόνο για ανάγνωση. Το πακέτο δεν περιέχει κλήση που να μεταβάλλει το Search Console.

• Τα διαπιστευτήρια παραμένουν στο περιβάλλον. Το κλειδί λογαριασμού υπηρεσίας / το μυστικό OAuth και το refresh token διαβάζονται από τις κατονομασμένες μεταβλητές περιβάλλοντος τη στιγμή της κλήσης, ακριβώς όπως το κλειδί AI — επομένως το php artisan config:cache δεν τα γράφει ποτέ στο bootstrap/cache/config.php. Διαθέστε τα στο περιβάλλον της διεργασίας όταν η αποθηκευμένη cache ρυθμίσεων εμποδίζει τη φόρτωση του .env.

• Τα token κρυπτογραφούνται κατά την αποθήκευση. Το access token μικρής διάρκειας που εκδίδεται από τα διαπιστευτήριά σας αποθηκεύεται κρυπτογραφημένο (με το κλειδί εφαρμογής) στο seo_gsc_tokens και επαναχρησιμοποιείται μέχρι να πλησιάσει η λήξη του, ώστε η ανταλλαγή token να μη γίνεται σε κάθε προβολή. Τα διαπιστευτήρια μεγάλης διάρκειας δεν αποθηκεύονται ποτέ στη βάση δεδομένων — μόνο στο περιβάλλον σας.

• Κάθε αίτημα προστατεύεται από SSRF. Η ανταλλαγή token και η κλήση Search Analytics περνούν από το κοινό SsrfGuard (μόνο HTTPS, ο host πρέπει να επιλύεται σε δημόσια διεύθυνση), με ανενεργές ανακατευθύνσεις, ώστε ένα αίτημα να μην μπορεί ποτέ να ανακατευθυνθεί σε εσωτερική υπηρεσία.

• Δεν καταγράφονται μυστικά. Access token, κλειδιά και κεφαλίδες ελέγχου ταυτότητας δεν γράφονται ποτέ στα αρχεία καταγραφής· ένα σφάλμα API εμφανίζει μόνο το καθαρισμένο μήνυμα σφάλματος του ίδιου του Google, με περιορισμένο μήκος.

• Οι μετρήσεις αποθηκεύονται σε τοπική cache για seo-pro.search_console.cache_ttl δευτερόλεπτα (προεπιλογή 30 λεπτά), ώστε ο πίνακας να μην καλεί ξανά το API σε κάθε απόδοση. Ο ζωντανός πίνακας και η εντολή δεν αποθηκεύουν τίποτε πέρα από αυτή την cache και το κρυπτογραφημένο access token. Μόνο η προαιρετική εντολή seo-pro:gsc-sync γράφει μετρήσεις μόνιμα — συγκεντρωτικές μετρήσεις ερωτημάτων/σελίδων ανά ημέρα στο seo_gsc_metrics, χωρίς δεδομένα ανά χρήστη.

Αναφορά ρυθμίσεων

Όλα τα κλειδιά βρίσκονται στο config/seo-pro.php → search_console:

Κλειδί	Προεπιλογή	Σκοπός
enabled	false	Κεντρικός διακόπτης (SEO_PRO_GSC_ENABLED).
connection	service_account	service_account ή oauth.
site_url	προκύπτει από app.url	Η ιδιοκτησία (https://example.com/ ή sc-domain:example.com).
service_account.credentials_env	SEO_PRO_GSC_CREDENTIALS	Όνομα της μεταβλητής περιβάλλοντος με το κλειδί JSON ή τη διαδρομή του.
oauth.client_id	—	Αναγνωριστικό πελάτη OAuth (δεν είναι μυστικό).
oauth.client_secret_env	SEO_PRO_GSC_OAUTH_CLIENT_SECRET	Όνομα της μεταβλητής περιβάλλοντος με το μυστικό πελάτη.
oauth.refresh_token_env	SEO_PRO_GSC_OAUTH_REFRESH_TOKEN	Όνομα της μεταβλητής περιβάλλοντος με το refresh token.
default_days	28	Παράθυρο αναφοράς (τελειώνει 3 ημέρες πριν — τα δεδομένα GSC καθυστερούν).
row_limit	100	Κορυφαίες N γραμμές ανά αναφορά (μέγιστο API 25000).
cache_ttl	1800	Δευτερόλεπτα διατήρησης της ανακτημένης αναφοράς στην cache.
sync.backfill_days	90	Ημέρες που ανακτώνται στην πρώτη εκτέλεση gsc-sync (κενός πίνακας).
sync.overlap_days	2	Πρόσφατες ημέρες που ανακτώνται ξανά σε κάθε εκτέλεση (καθυστερημένη οριστικοποίηση).
sync.row_limit	5000	Μέγιστες γραμμές ανά ημέρα και ανά διάσταση που ζητά ο συγχρονισμός.