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 with AEM 6.5 and with AEM as a Cloud Service, for a store finder already on your site and for a new one. Most of it happens in the Dispatcher, the Apache web server in front of AEM. One step needs an AEM developer. It takes five steps.

What you need

Access to your Dispatcher configuration, or someone who has it. On AEM as a Cloud Service, that is the dispatcher folder of your Git repository, and access to Cloud Manager

An AEM developer, for step 3

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. Each store gets its own address under it

Which AEM you have

Some steps differ between the two. To find out, ask whoever runs your AEM, or look at Cloud Manager:

• a) AEM 6.5: AEM runs on your own servers, or Adobe runs it for you (Adobe Managed Services). Older versions, such as 6.4, follow the same steps.
• b) AEM as a Cloud Service: your program's environments in Cloud Manager have addresses such as publish-p12345-e67890.adobeaemcloud.com.

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 the ones the includes repeat (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 ones the includes repeat.
• Your site's scripts, in the page's source and in your site's JavaScript files: calls to UberallStorefinderMount or UberallStorefinderRestart.

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

Your pages' title and description

Uberall gives every store finder page its own canonical link. The title, the description and the preview image for social media come from Uberall only when they are set up there:

• The store finder's main page, and its directory pages (the lists of stores by country, region or city): only what is set up at Uberall. With nothing set up, these pages have no title and no description.
• A store's page: always a title and, when the store has one, a description: the store's name and short description, unless others are set up. The image is the store's photo.

In step 3 you take your own title and description off these pages. So check with Uberall first that a title and a description are set up for your store finder, or send yours to be saved with it.

Step 1: Connect your Dispatcher to Uberall

a) AEM 6.5

These Apache modules must be on: include, proxy, proxy_http, ssl, headers and rewrite. Most Dispatchers have them already. If not, whoever runs your Dispatcher can turn them on.

Open your site's virtual host file, the one with your <VirtualHost>, and paste this inside the <VirtualHost> block. Replace YOUR_RENDER_TOKEN with your token:

SSLProxyEngine on
SSLProxyVerify require
SSLProxyVerifyDepth 10
SSLProxyCACertificateFile /etc/pki/tls/certs/ca-bundle.crt
<Location "/api/locator-fragments/">
    Require expr %{IS_SUBREQ} == 'true'
    RequestHeader set x-uberall-render-token "YOUR_RENDER_TOKEN"
    RequestHeader unset Accept-Encoding
    RequestHeader unset Cookie
    RequestHeader unset Authorization
    RequestHeader unset Proxy-Authorization
    RequestHeader unset Via
    ProxyAddHeaders Off
    ProxyPass "https://uberall.com/api/locator-fragments/" connectiontimeout=2 timeout=10
    ProxyErrorOverride On
</Location>

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

The certificate file lists the authorities your system trusts, and where it is depends on the system:

If yours is not there, openssl version -d shows the folder where OpenSSL keeps it.

b) AEM as a Cloud Service

All the modules it needs are on already.

First, give the Dispatcher your token. In Cloud Manager, open each environment that serves your site, go to Configuration, and add a variable:

• Name: UBERALL_RENDER_TOKEN
• Value: your render token
• Step applied: All
• Type: a normal variable, not a secret. The Dispatcher cannot read secrets.

The token is not a secret there: people with access to the environment's configuration in Cloud Manager can read it. Visitors never see it.

Then open your site's virtual host file, in dispatcher/src/conf.d/available_vhosts/, and paste this inside the <VirtualHost> block:

SSLProxyEngine on
<Location "/api/locator-fragments/">
    Require expr %{IS_SUBREQ} == 'true'
    RequestHeader set x-uberall-render-token "${UBERALL_RENDER_TOKEN}"
    RequestHeader unset Accept-Encoding
    RequestHeader unset Cookie
    RequestHeader unset Authorization
    RequestHeader unset Proxy-Authorization
    RequestHeader unset Via
    ProxyAddHeaders Off
    ProxyPass "https://uberall.com/api/locator-fragments/" connectiontimeout=2 timeout=10
    ProxyErrorOverride On
</Location>

AEM as a Cloud Service does not allow the lines that check Uberall's certificate, so the connection is encrypted, but your Dispatcher does not check that it reached Uberall's server.

Step 2: Turn on includes for the store finder page

The Dispatcher fetches your store finder page from AEM by its path in AEM, such as /content/example/en/store-locator.html. You need that path here and in step 4. To find it, open the page in AEM Sites: it is the page's path, with .html at the end. If your Dispatcher's rewrite rules map your public addresses to AEM paths, it is what they turn the store finder's address into.

In the same <VirtualHost> as step 1, paste this. Replace the path with yours, and keep the \ before .html:

a) AEM 6.5:

<LocationMatch "^/content/example/en/store-locator\.html$">
    Options +IncludesNOEXEC
    AddOutputFilter INCLUDES .html
    SSIErrorMsg "<!-- -->"
</LocationMatch>

b) AEM as a Cloud Service:

<LocationMatch "^/content/example/en/store-locator\.html$">
    Options +IncludesNOEXEC
    AddOutputFilter INCLUDES .html
</LocationMatch>

AEM as a Cloud Service does not allow SSIErrorMsg. Step 3 has a line in the page that does the same.

Step 3: Put the store finder on its page

This step is for your AEM developer. The store finder page, as AEM delivers it, needs the includes and the store finder snippet shown below. Replace YOUR_LOCATOR_KEY with your locator key, in all three places.

<head>
  <!--#config errmsg=" " -->
  <!-- ... your head, without its own title, canonical, description and og: tags ... -->
  <!--#include virtual="/api/locator-fragments/head?key=YOUR_LOCATOR_KEY&path=$REQUEST_URI" -->
</head>
<body>
  <!-- ... -->
  <div id="store-finder-widget" data-key="YOUR_LOCATOR_KEY">
    <!--#include virtual="/api/locator-fragments/body?key=YOUR_LOCATOR_KEY&path=$REQUEST_URI" -->
  </div>
  <script src="https://locator.uberall.com/locator-assets/storeFinderWidget-v2.js"></script>
</body>

The config line goes first in <head>. It keeps an error message off the page when the store finder content does not arrive. On AEM as a Cloud Service it is required, on AEM 6.5 it does no harm.

The first include goes just before </head>. The second goes inside the store finder's div. Keep path=$REQUEST_URI at the end of each line.

This is what has to be true of the page:

• The lines arrive in the page exactly as shown. They are HTML comments, and AEM can drop or escape them: rich text editors remove them, and HTL escapes markup in most contexts. $REQUEST_URI has no braces on purpose: HTL reads ${...} as its own expression, even in a comment, and would leave path= empty.
• The head lines come from your page component or template, for example its customheaderlibs.html, and only on the store finder page.
• The body line comes from a component that writes it unchanged, inside the store finder's div.
• The script comes from locator.uberall.com, as shown, not from a copy on your own server.

To check it, open the published page, not the page in the AEM editor, choose View page source, and search for #include. You should find both lines exactly as above.

On the store finder page, your site must not add its own canonical link, og:url or og:type tag: Uberall always sends them. With two canonical links, search engines may ignore both, or take yours, which is the same address for every store. Leave out your own title, description and other Open Graph tags there too, once they are set up at Uberall (see above).

The store finder's address comes from what is set up at Uberall. Check with Uberall that it is set up, and without #!: the server only sees the part of an address before #. To use another address on this page, set it on the snippet and on the includes (below).

Where the store finder's div comes from

The div has to be in the page's HTML as AEM delivers it, so the include can go inside it. To find out where yours comes from, open the store finder page, choose View page source (not the browser's inspector), and search for store-finder-widget:

• a) You find the div: it is in the page's HTML. Keep it, once its settings are at Uberall (the section above), and add the include inside it.
• b) You do not find it: your site's JavaScript adds the div once the page has loaded. Put the div into the page's HTML instead, with only the include inside it, as shown above, and remove the code that adds it. Keep the code that loads the script, if it waits for the visitor's consent first.

The snippet and the includes must match

These attributes of the snippet are also parameters of both includes. Whatever the snippet sets, the includes must set too, with the same value, before &path=:

With data-language="de", data-countries="US,DE" and data-widgetoriginurl="https://www.example.com/store-locator" on the snippet, the first include reads:

<!--#include virtual="/api/locator-fragments/head?key=YOUR_LOCATOR_KEY&lang=de&countries=US,DE&widgetOriginUrl=https://www.example.com/store-locator&path=$REQUEST_URI" -->

If your page loads storeFinderWidget-v2-withoutMap.js, or starts the store finder with withoutMap: true, add withoutMap=true to both includes too, before &path=.

If they differ, search engines get a page built with the values of the includes, and your visitors' browsers build the page again with the values of the snippet.

Step 4: Send every store's address to the store finder page

Each store's page lives at an address under the store finder. Your Dispatcher has to answer all of them with the store finder page. It does that inside the Dispatcher: the address in the browser stays exactly as it is, and nothing redirects.

To find out which addresses your stores have, open one of your stores in the store finder and look at the address bar:

a) /store-locator/l/berlin/..., without .html before /l/:

RewriteRule ^/store-locator/(l|s)(/|$) /content/example/en/store-locator.html [PT,L]

b) /en/store-locator.html/l/berlin/..., with the page's .html before /l/:

RewriteRule ^/en/store-locator\.html/(l|s)(/|$) /content/example/en/store-locator.html [PT,L]

c) /store-locator#!/l/berlin/..., with #!: your stores' addresses become real paths under the store finder's address, without #!. The main page's address stays. Google ignores everything after #, so nothing that ranks today changes. Ask Uberall to set up your store finder's address without #!, then use the rule of a), or of b) if the page's address ends in .html.

In each rule, replace the first part with your store finder's address, and the second with its path in AEM from step 2. In b), keep the \ before .html.

The rule sends the store finder's own addresses to its page: /l with its store and directory pages, and /s with its searches. If a custom directory route or custom store addresses are set up for your store finder at Uberall, they need a rule of their own.

Where the rule goes:

• a) AEM 6.5: in the same <VirtualHost>, after RewriteEngine on and above your other RewriteRules. The Dispatcher must fetch the address the rule gives it, so DispatcherUseProcessedURL must be On. It usually is.
• b) AEM as a Cloud Service: in dispatcher/src/conf.d/rewrites/rewrite.rules, above your other rules.

It goes above the others because it ends the rewriting for these addresses.

Step 5: Deploy and check

a) AEM 6.5: on each Dispatcher server, check the configuration and restart Apache:

sudo apachectl configtest && sudo apachectl graceful

With Adobe Managed Services, your Customer Success Engineer, or your Cloud Manager pipeline, deploys it.

b) AEM as a Cloud Service: check the configuration with the validator from the Dispatcher tools of the AEM SDK:

validator full dispatcher/src

It should report no issues. Then deploy with your Cloud Manager pipeline.

Then publish the store finder page from step 3.

Open your store finder in the browser, right click, and choose View page source. Search the source for __ubSfSsr. If you find it, it works.

Search the same source for <title and rel="canonical". Each should appear exactly once. If one appears twice, your head still has its own: see step 3. If <title is missing, the store finder has no title set up at Uberall yet.

Then open one of your stores and copy its address into a new tab. The store's page should open.

More than one store finder on the site

Each store finder has its own render token, and the <Location> from step 1 sends one. So the second store finder gets a <Location> of its own. Paste a copy of the one from step 1 below it, with two changes:

• its address: <Location "/api/locator-fragments-2/"> instead of <Location "/api/locator-fragments/">
• its token: the second store finder's token on AEM 6.5. On AEM as a Cloud Service, a second variable, UBERALL_RENDER_TOKEN_2, in each environment, and "${UBERALL_RENDER_TOKEN_2}" in the copy

Keep the ProxyPass line as it is. Do not paste the first one twice with another token: Apache would send the last token for both store finders.

Then follow steps 2 to 4 for the second store finder's page, with one change: its includes start with /api/locator-fragments-2/ instead of /api/locator-fragments/.

For a third store finder, use /api/locator-fragments-3/, and so on.

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 Dispatcher 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.

The Dispatcher's own cache adds nothing to that: it keeps the page with its includes, and they run each time the page goes out.

A CDN in front of the Dispatcher adds the time it keeps your pages. On AEM as a Cloud Service, Adobe's CDN keeps them for 5 minutes, unless your Dispatcher sends them with Cache-Control: no-cache or private. If you have a CDN of your own in front, add its time too. Each store finder page in a CDN keeps the content it had when it was cached. And a page the CDN stored while the content did not arrive stays without its stores, for search engines, until the CDN stores it again.