Search engines and AI assistants often cannot see your store finder. When they visit the page, your stores are not on it yet: they only appear later, on the visitor's screen. So your stores can be missing from search results and from the answers AI assistants give.

After these steps, every store finder page arrives with its stores already on it, with names, addresses and opening hours. Search engines and AI assistants can find each of your stores and show it. Your visitors see the store finder as usual.

It works for a store finder already on your site and for a new one. It takes four steps, in your site's code. They are written for the developer who maintains the site. Some steps depend on how your site is set up: each of those says how to find out, and what to do in each case.

What you need

Drupal 11. On another Drupal version? Ask Uberall before you start.

Access to your site's code and its settings.php, and Drush

The Uberall Store Finder module, a zip file: uberall_store_finder-latest.zip

Your render token, from Uberall

Your locator key, from Uberall. If the store finder is already on your site, it is the data-key of its snippet:

<div id="store-finder-widget" data-key="YOUR_LOCATOR_KEY"></div>

Your store finder's address: the page it is on, such as https://www.example.com/store-locator, and on a site with more than one language, its address in each of them. Each store gets its own address under it

Step 1: Install the module

The module goes into your site's code. Find your site's web root: the folder with index.php and the core folder in it. It is web on most sites, and docroot on Acquia.

Unzip the file into the modules/custom folder of your web root, such as web/modules/custom. Afterwards, uberall_store_finder.info.yml is directly in web/modules/custom/uberall_store_finder.

Find your site's folder: if your web root has sites/sites.php, it is the folder that file gives for your site's address, or else the folder named after the address that has a settings.php, such as sites/www.example.com. Without sites/sites.php, or without such a folder, it is sites/default. If yours is not sites/default, or your site is in a folder of its domain, such as https://www.example.com/shop, run every drush command with your site's full address, folder included, such as drush -l https://www.example.com/shop pm:install uberall_store_finder. That goes for your host's cron command too: without the folder, Drush can make store addresses answer "Page not found".

Find out whether your configuration is in your repository: search it for a file named core.extension.yml, usually in config/sync.

a) Your repository has core.extension.yml

On a local or development copy of the site, run:

drush pm:install uberall_store_finder
drush config:export

Commit the module's folder and the changed core.extension.yml, and deploy as usual. The deployment's configuration import turns the module on. Do not turn it on only on the live site: the next import would turn it off again.

b) Your repository has no core.extension.yml, or you do not deploy from one

Deploy the module's folder as usual. Then, on the live site, go to Extend, check Uberall Store Finder and click Install, or run drush pm:install uberall_store_finder.

Step 2: Add your render token and your store finder's address

Add this to the end of the settings.php in your site's folder, usually web/sites/default/settings.php. Replace YOUR_LOCATOR_KEY with your locator key, and YOUR_RENDER_TOKEN with your token:

$settings['uberall_store_finder'] = [
  'pages' => ['/store-locator'],
  'tokens' => ['YOUR_LOCATOR_KEY' => 'YOUR_RENDER_TOKEN'],
];

In pages, put the address of your store finder page, as it is in the browser, without the domain:

• a) One store finder page: its address, such as ['/store-locator'].
• b) A store finder page for each language: each of them, with its language prefix, such as ['/store-locator', '/de/filialfinder', '/fr/magasins'].

The token stays on your server. Visitors never see it.

Find out whether settings.php is in your repository.

a) It is not, or you do not deploy from one: edit it on the server. Drupal makes it read-only, so allow writing it first, and make it read-only again afterwards.

b) It is, as on Acquia and Upsun: keep the token out of the repository. Commit settings.php without it, and keep the token where your host keeps secrets:

Upsun: add a variable named env:UBERALL_RENDER_TOKEN, marked Sensitive, and read it in settings.php. Without the env: prefix, getenv() does not see it.

'tokens' => ['YOUR_LOCATOR_KEY' => getenv('UBERALL_RENDER_TOKEN')],

Acquia: Acquia advises against environment variables for credentials. Put the token in a secrets.settings.php in your home directory, as Acquia's guide to storing sensitive information describes. Start the file with <?php, or PHP shows the token on every page instead of reading it:

<?php

$settings['uberall_store_finder']['tokens']['YOUR_LOCATOR_KEY'] = 'YOUR_RENDER_TOKEN';

Load it at the end of settings.php, after the block above:

$secrets_file = $_ENV['HOME'] . '/secrets.settings.php';
if (file_exists($secrets_file)) {
  require $secrets_file;
}

Every address under a store finder page belongs to the store finder: Drupal shows the store finder page for it, and the store finder shows the store. Do not put other pages under it: a page whose address starts with the store finder page's shows the store finder instead. For the same reason, a redirect from an address under the store finder page does not apply. To link to one of your stores from a menu or a link field, or to redirect to it, use its full address, such as https://www.example.com/store-locator/l/berlin/...: Drupal reads a short one, such as /store-locator/l/berlin/..., as the store finder page itself.

Step 3: Put the store finder on its page

The module puts your stores into the store finder's div on the page Drupal sends. So the div has to be in that page, not added later by a script.

Find out where your snippet is: open your store finder page in a private browser window, signed out of Drupal. Right click, and choose View page source. Do not use the browser's developer tools: they show the page after scripts have changed it. Search the source for store-finder-widget.

a) The store finder is not on your site yet

Edit the store finder page. Under the body, choose the text format Full HTML, click Source in the editor's toolbar, and add the store finder snippet. Replace YOUR_LOCATOR_KEY with your locator key, and the address with your store finder page's full address:

<div
  id="store-finder-widget"
  data-key="YOUR_LOCATOR_KEY"
  data-widgetoriginurl="https://www.example.com/store-locator"
></div>
<script src="https://locator.uberall.com/locator-assets/storeFinderWidget-v2.js"></script>

Click Save.

b) You found store-finder-widget in the source

The snippet is in the page already: in the body, in a block, in Layout Builder or in your theme's templates. All of these work. Leave it where it is, and:

1. Check its settings, as described in If the store finder is already on your site.
2. Add data-widgetoriginurl with your store finder page's full address, if the div has none.

c) The store finder shows in the browser, but store-finder-widget is not in the source

A script adds it after the page has loaded, for example a tag manager such as Google Tag Manager. The module cannot reach it there. Move the snippet into the page:

1. Add it as in a), with the settings it has today.
2. Remove it from the tag manager, or wherever the script adds it, so it is not on the page twice.

Either way, keep the div empty, as above: the module puts the stores inside it. The space the editor puts into an empty div is fine. If the div has anything else inside it, even text, the page is served without them.

If the div has data-baseurl, remove it. With any address in it other than https://locator.uberall.com, the store finder does not take over the stores in the page: it shows them again on the visitor's screen.

The module sends Uberall the div's data-key, data-language, data-countries and data-widgetoriginurl, so the stores in the page always match what the store finder shows. On a site with more than one language, each language's page has its own snippet: set its language and its own address on it, such as data-language="de" and data-widgetoriginurl="https://www.example.com/de/filialfinder".

If your snippet loads storeFinderWidget-v2-withoutMap.js, the store finder shows no map, and its pages arrive without one too. Nothing to add.

If its addresses have #! in them today, check with Uberall that your store finder is set up without it.

If the store finder is already on your site

After these steps, your store finder pages use only the settings saved at Uberall. What is set on the page itself no longer applies there:

• attributes on the store finder's div, other than data-key, data-language, data-countries and data-widgetoriginurl, and data-baseurl, which you remove in step 3
• settings your site's scripts pass to UberallStorefinderMount or UberallStorefinderRestart, other than withoutMap

To find them, look in two places:

• The store finder's div, in the page's source: any data- attribute other than the five above.
• Your site's scripts, in the page's source and in your site's or theme's JavaScript files: calls to UberallStorefinderMount or UberallStorefinderRestart.

If you find any of these settings, send them to Uberall before you go on, to be saved with your store finder. Until then, leave the page as it is: the store finder keeps working as it does today.

Step 4: Deploy and check

Deploy, then clear Drupal's caches: run drush cache:rebuild, or go to Configuration, Performance, and click Clear all caches.

Open your store finder in a private browser window, signed out of Drupal. Right click, and choose View page source. Search the source for __ubSfSsr. If you find it, it works. Signed in to Drupal, or with anything else in the session, such as a shopping cart, the page comes without it: Drupal builds those pages for each visit, and search engines never have a session.

Then open one of your stores and copy its address into a new tab. The store's page should open, with the store's name as the page title.

On a site with more than one language, check the store finder page in each of them.

What changes on your store finder pages

On the store finder's pages, the module replaces part of what Drupal and modules such as Metatag put in the page's head with what Uberall sends for each store:

• the title, the canonical link and the description
• the Open Graph tags, with the twitter: tags that go with them
• the structured data (application/ld+json)

It only replaces what Uberall sends. What Uberall does not send for a page stays as your site has it. For example, if no description is set up at Uberall for your store finder's main page, the page keeps the description your site gives it.

A store's page also leaves out the links to the store finder page in your other languages (hreflang), which Drupal adds: they name the store finder page, not the store. The store finder page itself keeps them.

More than one store finder on the site

Each store finder has its own locator key and its own render token. Add each of them to tokens, and each store finder page, in every language, to pages:

$settings['uberall_store_finder'] = [
  'pages' => ['/stores', '/de/filialen', '/showrooms', '/de/ausstellungen'],
  'tokens' => [
    'STORES_LOCATOR_KEY' => getenv('UBERALL_RENDER_TOKEN_STORES'),
    'SHOWROOMS_LOCATOR_KEY' => getenv('UBERALL_RENDER_TOKEN_SHOWROOMS'),
  ],
];

The module takes each page's token by the data-key of its snippet. Then follow step 3 for each page.

If it does not work

When the store finder content does not arrive

The store finder keeps working in every case. If the content does not arrive, because your server cannot connect to Uberall, the connection takes too long or it returns an error, the page loads without it, and the store finder appears on the visitor's screen as usual.

When changes show

A change at Uberall, to your stores or to your store finder's settings, takes a few minutes to show on these pages.

Drupal's page cache keeps a store finder page for signed-out visitors for an hour at most, and the module tells a cache in front of Drupal, such as Varnish or a CDN, to do the same, apart from the extra time a stale-while-revalidate or stale-if-error your site sends gives it. That cache counts its time from when it gets the page, and it may get it from Drupal's page cache near the end of Drupal's hour. So a page can be up to two hours old. Nothing tells your caches when your stores change at Uberall, so a change shows once they store the page again. That goes for a change to your own setup too, such as the token or the snippet: to check one at once, add ?check to the page's address, which your caches keep apart. When the content does not arrive, the module keeps the page out of Drupal's page cache, and sends Cache-Control: no-store with it, so a later visit tries again. A page that is not set up yet, with no token, no data-key or no empty store finder div, is cached like any other: clear Drupal's caches once you fix it.

A cache that sets its own time for your pages, rather than the one Drupal sends, may keep them longer, and keep a page without its stores. If yours does, exclude the store finder's addresses, such as /store-locator/*, from it.