Skip to content

Google Search Console

Everything else in the SEO Engine is its own opinion: rules, findings, score. The Google Search Console supplies the only figures that come from outside — how often a page was seen in the search results, how often it was clicked, and under which search terms. That makes three things possible that are not possible without it: prioritising the work (the page with 4,000 impressions and a 0.4 % click rate first), deriving the focus keywords instead of guessing them, and proving whether an applied text achieved anything.

The connection is optional. Without it, the audit, the score and the Copilot drafts work unchanged; only the search figures stay empty, and the rules that depend on them stay silent.

How to get there: Via Tell me Search Console Connections, in the setup via the field Connections in the Search Console group or the action Search Console Connections, on the dashboard via the action group Search Console (Search Console Fetches, Search Metrics, Search Terms) and the actions Focus Keyword Suggestions and What the New Texts Did. On the Marketplace Item Card, Search Metrics and Search Terms lead to the figures of exactly that listing.


Two ways in

Way What it delivers Effort
API connection Impressions, clicks, click rate and position per page, plus the search terms per page — automatically every night Once, an OAuth client of your own in your Google Cloud project; then one row per shop
CSV import Impressions, clicks, click rate and position per page, for the period of the export One export in the Search Console, one dialog in Business Central

Why the search terms only come through the API

In the Search Console, queries and pages are two separate tables without a link. The export delivers both side by side, but not paired — which query belongs to which page is written nowhere. The API returns page and search term together. Focus keyword suggestions, the rule Focus Keyword Not Searched and the search terms in the Copilot draft therefore exist only with an API connection.


Setting up the connection

One row in Search Console Connections per shop: a Search Console property describes one website, and each shop's listings are matched against the addresses of its own property.

Your own OAuth client, read access only

The SEO Engine ships no Google access. You create an OAuth client in your own Google Cloud project. Search Console access is a sensitive scope at Google: a client the app offered to every customer would have to pass Google's verification, and every customer's access would hang on that one registration. A project of your own needs no verification for your own use, and revoking it is up to you. Only the Search Console read scope is requested (webmasters.readonly); the SEO Engine cannot change anything there.

In the Google Cloud Console (once)

Sign in with the Google account that owns the property in the Search Console. Another account can create a client but does not see the property — which only shows at Test Connection.

  1. Create a project or take an existing one.
  2. Enable the Search Console API.
  3. Under Google Auth Platform (formerly OAuth consent screen), fill in branding and audience. Without that no client can be created.
  4. Under APIs & Services → Credentials, create an OAuth client of type Desktop app.
  5. Note the client ID and the client secret. Google shows the secret only once.

Set the publishing status to “In production”

In status “Testing”, Google admits only explicitly listed test users — Grant Access then ends immediately with “Access blocked” (403: access_denied). Adding yourself as a test user only seems to help: in “Testing” the refresh token expires after seven days. The connection runs for a week and then fails on every fetch with invalid_grant.

The app can only be published once Branding lists a home page, a privacy policy, terms of service and the authorised domain; existing, reachable pages are enough. With “In production”, consent shows the notice “Google hasn't verified this app” once — Advanced takes you through, because it is your own client for your own account. With Google Workspace, the audience “Internal” is the cleaner choice (no warning, no seven-day limit), provided the project belongs to the organisation.

In Business Central (per shop)

Step What you do
1. Create the row Enter Marketplace Code, Sub-Account Code, Property URL and OAuth Client ID. The property URL exactly as the Search Console property picker shows it: https://www.example.com/ with the trailing slash, or sc-domain:example.com for a domain property. Google compares it literally.
2. Enter Client Secret The secret from your Google Cloud project. It is stored encrypted and never displayed again; the field Client Secret then only shows Stored.
3. Grant Access Opens Google's consent page in your browser. Sign in with the account that sees the property and approve.
4. Copy the address Google then redirects to http://localhost. That page does not load — this is expected. Copy the whole address from the address bar.
5. Enter Authorization Code Paste the address into Address or Code. The page picks the code out itself. The code is valid once and only for a few minutes — paste it right after the consent. Authorized At fills in, Access shows Granted.
6. Test Connection Asks Google whether the property can be read with the stored access and reports the account's permission. The test fetches no figures — that is what Fetch Figures Now is for.

Why the detour through the address bar?

Business Central online has no endpoint Google could redirect to. Carrying the code across through the address bar is awkward to describe but reliable, and nothing has to be hosted. The eBay connector has used the same route for years.

If Google reports “Google granted access but no refresh token”, the account had already approved this client once — Google grants the lasting permission only on the first approval. Remove the app from the Google account under myaccount.google.com → Third-party access and grant the consent again. If the account sees the property only as a restricted user, the fetches succeed but return no figures; give it full access in the Search Console under Settings → Users and permissions.

Fields

Field Meaning
Marketplace Code / Sub-Account Code / Shop Name The shop as the hub knows it. Its listings are matched against the addresses of this property.
Enabled Whether figures are fetched for this shop. Switch it off to keep the connection without collecting anything.
Property URL The property, literally as in the Search Console.
OAuth Client ID The client ID of your OAuth client. Not a secret — Google shows it in plain text, and it is part of every consent address.
Client Secret Stored or Not stored. Choosing it opens the input to enter or replace it.
Access Granted or Not granted — whether Google has granted lasting access for this shop.
Authorized At / Authorized By When and by whom the consent was last granted.
Last Fetch At / Last Fetch Error When figures were last fetched, and what went wrong, if something did.

Actions

Action Effect
Enter Client Secret Stores the secret of this row's OAuth client.
Grant Access Opens Google's consent page (step 1 of 2).
Enter Authorization Code Trades the code from the redirect address for lasting access (step 2 of 2).
Withdraw Access Removes the stored client secret and the lasting access of this shop, for example to hand the property to another Google account. The figures already fetched stay. The access in the Google account itself remains until you remove it there.
Fetch Figures Now Fetches the search figures for this shop — the same fetch as at night, but without the page check that follows it and without an audit.
Test Connection Checks access to the property without fetching figures.
Export Redirect Map Downloads a text file pairing every product number of the shop with the URL path its listing has today, ready for an Apache RewriteMap. After slugs were changed, it sends old product addresses that end in the product number on with a 301 instead of a 404. The directives are in the file header.
Fetch History / Search Terms Open the Search Console Fetches and the fetched search terms of these shops.

Who may set up connections

Only users who may change the Search Console connections can enter, replace or remove the client secret and the access — the permission set mC SEO Engine - Admin. With mC SEO Engine - User the connections are read-only; the page checks this before any input dialog opens.

Where the credentials are kept

What Where
OAuth Client ID In the field on the connection row. It is not a secret.
Client secret In the hub's merchantCENTRAL Credential Store, per company and shop. Not readable anywhere after entry, not even for administrators.
Refresh token (the lasting permission) Also in the Credential Store, per company and shop — two companies with the same shop do not share one consent.
Access token Never stored. It lives about an hour and is kept in memory for the length of a session only.

The nightly fetch

There is no job queue entry of its own. The SEO Engine's daily entry (setup → Create Job Queue Entry) first fetches the figures of every enabled connection and then audits the listings — in that order, so that the rule Focus Keyword Not Searched and the keyword suggestions run on fresh figures. Without a connection the first step costs nothing.

  • Always the same period: 28 days, ending three days ago. Google's figures for the last few days are incomplete and still moving. Because every run rewrites the same window, a second run changes nothing, and a missed night is caught up by the next one.
  • Shop by shop: a failed fetch does not stop the other shops. It is logged, and the connection row carries the error in Last Fetch Error.
  • After the fetch the engine calls the most-seen pages without a listing in the shop (see What the shop answers).

Prerequisite

Under Extension Management → Configure, Allow HttpClient Requests must be on for the SEO Engine — otherwise Business Central reaches neither Google nor the shop.

How a Google address finds its listing

First through the listing's SEO slug — it is the listing's own address and wins where several things match. If an address matches no slug, the engine keeps trying in this order; steps 1 to 3 also work for listings without a slug:

  1. What the shop answered: if the page check saw the address redirect to a listing, it belongs to that listing — that is how old Shopware 5 addresses find their product.
  2. The number in the number parameter (old Shopware 5 variant addresses such as …?number=13.102.038.58).
  3. The last path segment as a number (Shopware addresses such as /Product-Name/12.3456.78).
  4. The last segment of the slug — for Shopify, which keeps products under /products/<handle>. If the slugs of two listings end the same, neither gets anything; the row then counts as without a listing instead of landing on the wrong product.

In steps 2 and 3 the comparison is with the listing's SKU, or — for listings without a variant — with the item number instead.

Search Console Fetches

The log of every fetch (Tell me Search Console Fetches or dashboard → Search Console Fetches):

Column Meaning
Outcome What the fetch achieved — or what stopped it, in plain words
Listings Matched For how many listings Google reported figures
Listings With a Slug How many listings of this shop could be matched at all
Searches Written How many search terms were stored
Rows Without a Listing Reported rows that belong to no listing. Choosing the number opens the pages behind it
Impressions Fetched The total across all matched listings
Period End The last day the fetch asked for — always three days ago
Data Through The last day for which Google actually had finished figures
No New Days Google had no day the previous fetch did not already have

From every row, Search Console Connection, Search Metrics, Search Terms and Pages Without a Listing lead on.

Read the two columns side by side

If Google reports 400 pages, only 11 find a listing, and Listings With a Slug also says 11, you have a slug problem, not a Search Console problem. And when comparing fetches, compare Data Through, not the period end: Google closes its days at different speeds.

invalid_grant after it ran for a week?

Then the OAuth client is still on “Testing”. Set the status to “In production” and repeat Grant Access once — client ID and client secret stay the same, the figures already fetched are not affected.


The CSV import

Without an API connection — or to get started — the page figures can be imported from a file:

  1. In the Search Console under Performance, set the period and export the Pages table as CSV.
  2. In Business Central open Listing Search Metrics and choose Import from Search Console.
  3. In the dialog Import Search Console Figures, enter the shop's Marketplace Code and Sub-Account Code and the Period Start and Period End. The file carries no period — figures filed under the wrong period make every later comparison wrong.
  4. Only then does Business Central ask for the file.

The columns are read by position, not by heading — the headings are translated into the language of whoever exported the file, the order is not. The import detects the separator (comma, semicolon or tab) itself, and both number formats. Matching works through the slug as with the fetch; the pages without a listing replace the shop's list just as a fetch does. An export contains no search terms.


What the SEO Engine makes of it

Search metrics and missed clicks

Listing Search Metrics shows per listing and period Impressions, Clicks, Click Rate % and Average Position, plus SEO Score and Missed Clicks. That column says how many clicks the page would have had at the Target Click Rate % from the setup, beyond what it actually got. A page that reaches the target shows zero.

Pages Worth Fixing sorts by missed clicks — not by impressions. At a target of 3 %, a page with 10,000 impressions at 2.9 % misses ten clicks, one with 4,000 impressions at 0.2 % misses 112. Many impressions with a low click rate means the page is found and passed over — usually because of its title and meta description. Draft Content with Copilot requests a draft for the selected row right away; Show All Pages removes the filter again.

Changing the target

The missed clicks are stored with the target click rate. If you change the target, the app recalculates every stored period and shows a progress dialog while doing so.

Search terms

The page Search Terms shows per listing and period what was actually typed — with impressions, clicks, click rate and position, and next to it the applying Focus Keyword. Google withholds queries that too few people used; rare searches are therefore missing on purpose. With the API fetch, the engine builds the page figures from exactly these search term rows — search terms and page figures add up to the same total, a little below the page totals the Search Console itself shows. Page figures from a CSV import, by contrast, are Google's page totals and therefore a little higher. Both numbers are right.

Focus keyword suggestions

The page Focus Keyword Suggestions shows one row per listing whose search figures contradict the applying keyword, strongest term first. The column Reason says what it is about:

Reason Meaning
No focus keyword yet A gap — fill it and move on.
Keyword found in no search The listing aims at a term nobody types.
A stronger term exists The keyword is not wrong, just smaller than what the page is found for.
Keyword searched but out of reach The target is right, but the page stands far too low for that term.

Next to it are Suggested Keyword, Current Keyword, the figures of the suggested term, its Share of Impressions % (high: the term is the page; low: the page is found for many things), Other Terms and Keyword from Item Category (whether the current keyword is inherited).

Accept writes the suggested term as the focus keyword onto every marked listing and audits them again straight away. A listing's own keyword is replaced; an inherited one is overridden for that one listing from then on. Nothing is sent to a channel — the focus keyword is what the audit and the drafts aim at, not a shop field.

  • The strongest term within reach is suggested, not the loudest. A shop page collects impressions on broad terms it ranks fortieth for; writing the texts towards them costs the terms it wins. The limits are set by Min. Impressions for a Suggestion and Max. Position for a Suggestion.
  • Only the most recent period per shop is evaluated. Bare numbers without words, which Google Shopping reports as queries, do not count as terms — neither here nor in the rule Focus Keyword Not Searched.
  • A listing whose strongest term already carries its keyword is not listed. The headline names both, for example "18 of 260 listings with search figures are being offered a different focus keyword".
  • The suggestions cost no points. They are an offer, not a rule; overruling a row is using the feature correctly.

What the new texts did

The one place where the app can be checked: for every applied content proposal, the figures before against after, largest gain first, with the deteriorations in the same list. Three rules keep the answer honest:

  1. Before is the last period that ended before the proposal was applied. A period that straddles the change carries both texts and is left out.
  2. After is the most recent period that started after it.
  3. After ends at the next applied proposal for the same listing — otherwise the first text would be credited with the second one's figures.

A proposal without a period on both sides gets no row but counts in the headline. Waiting is not the same as ineffective. Click Rate Change is measured in percentage points, not percent. Impressions and clicks are only comparable when Periods of Equal Length is set. Release for Redraft puts the marked listings back into the automatic draft queue once you can see what the applied texts did.

On the dashboard, the card What the new texts did sums this up in Click rate on average, Outcome and Measurable yet.

Pages without a listing

Rows Without a Listing does not say what was not matched. Choosing the number — or the action Pages Without a Listing — opens Search Console Pages Without a Listing: one row per address with impressions, clicks, position and number of search terms, most seen first, plus the Reason:

Reason Meaning Action needed?
Home page The root of the property No
Category or content page The address ends in / — that is how Shopware writes categories and content pages No
File A data sheet or picture (.pdf, .jpg …) Only if the file is missing
Unknown product number The address names a product number no listing of this shop carries — usually a removed or renamed item Yes: set up a redirect
Shared by several listings The end of the address matches the slugs of several listings Yes: make the slugs distinguishable
Not recognized None of the above — usually a listing without a slug or a slug that changed without a redirect Check

The list always shows only the latest state per shop: every fetch and every import replaces it. A repaired address disappears with the next fetch.

What the shop answers

The reason alone does not tell whether an old address redirects cleanly or runs into nothing. So the SEO Engine calls the addresses: after every successful nightly fetch the 100 most seen that were never checked or were checked more than two weeks ago, and on request through Check Addresses (about a second per page). The home page and files are not called. If the shop fails to answer five times in a row, the check stops for that shop — it is then unreachable or blocking the caller. The result is in Shop Response, together with Leads To and, for a listing, its item number:

Shop Response Meaning Action needed?
Leads to a listing The shop redirects to a listing or answers with its page No — from the next fetch on, the address's figures count for the listing
Leads to a page without a listing Usually a product redirected to a category; Google treats that like a vanished page Yes: redirect to the matching product, if there is one
Not found 404 or 410, also at the end of a redirect chain Yes: set up a redirect
Could not be checked The shop was not reachable or answered with an error; after five such answers in a row the check of the shop stops The next run tries again
Not checked Not called yet Wait, or Check Addresses

Only addresses on the property's domain (including its subdomains) are called, only over http/https; a redirect to a foreign domain is not followed. Where an address leads is read from the redirect or from the page's <link rel="canonical">.

Search terms in the Copilot draft

Once a connection is set up and fetched, every Copilot draft gets the listing's ten strongest search terms from the most recent period as a fact. Everything else in the fact set is what the company calls the product; this is what buyers call it. Without a connection the list stays empty and the draft is written from the catalogue data as before.

The cross-check of the focus keyword

The rule Focus Keyword Not Searched reports an info finding when Google reported search terms for a listing and none of them contains the applying keyword. It only speaks when there are search figures, weighs only terms from Min. Impressions for a Suggestion up and leaves bare numbers out — see Focus keyword.


Setup fields

In the SEO Engine Setup:

Group · Field Default Meaning
Rule Limits · Target Click Rate % 2 Below this click rate a page counts as found and passed over. Only determines the missed clicks and thus the order of Pages Worth Fixing. The honest value is the one your own best pages reach.
Keyword Suggestions · Min. Impressions for a Suggestion 10 How often a search term must have shown the listing before it may be suggested. 0 weighs every term Google reports. Also applies to the rule Focus Keyword Not Searched.
Keyword Suggestions · Max. Position for a Suggestion 20 How far down a term may stand and still be suggested. 20 is the end of the second results page; 0 removes the limit.
Search Console · Connections — Not an input field but the state in one sentence: Not connected, Connected, but the figures have never been fetched, The last fetch of at least one shop failed or Figures last fetched …. Choosing it opens Search Console Connections.
Automatic Drafts · Waiting Period Before a New Draft (Days) 28 For this long after a proposal was applied, no new finding puts the listing back into the queue — one Search Console period, so that What the New Texts Did can show the effect.

Limits

  • No slug, no figures. A listing without an SEO slug cannot be matched to a reported address (exceptions: the product number in the address, or a checked redirect).
  • Three days' delay, 28-day window. The most recent days are missing on purpose; older periods remain as history.
  • Rare searches are missing. Google withholds them. The fetched page figures are the sum of the reported search terms and therefore a little below the page totals in the Search Console; only page figures from a CSV import match those.
  • The CSV import delivers no search terms — and therefore no keyword suggestions, no cross-check of the focus keyword and no search terms in the draft.
  • The property has to match literally, and the account needs full access; a restricted user gets no performance figures.
  • The engine writes nothing to the Search Console and sets up no redirects in the shop. It shows where one is missing; setting it up is done in the shop (the Export Redirect Map helps).

Costs and data protection

  • Costs: none. Google's API is free for your own use and runs through your own OAuth client, not one of ALTENBRAND's.
  • What goes to Google: the property URL and the period requested. For authentication, the client ID, client secret and tokens go to Google's sign-in service. Item, text and price data do not leave Business Central.
  • What comes back: addresses, search terms and figures of your own property. They stay in your company.
  • What the page check calls: only addresses on your own property's domain.
  • What goes to ALTENBRAND: from the page check, counts only (called, leads to a listing, to another page, not found, could not be checked), or the error code when it breaks off — never an address, never a search term.
  • Credentials: client secret and refresh token in the merchantCENTRAL Credential Store, the access token never stored (see Where the credentials are kept).

Retention

Search terms grow the most — one row per listing, period and search term, a new period every night. Registered with the Business Central retention policies are the search terms (Fetched At), the Search Console Fetches (Run At) and the page check (Checked At). The SEO Engine creates no policy. Recommendation for the search terms: about one year — only the most recent period per shop is evaluated anyway. The pages without a listing are replaced by every fetch.


See also