Locator Upgrade - Imperia Steps
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. Imperia publishes your pages to a web server, and most of the steps happen on that server, Apache or Nginx. Two steps need your Imperia developer. It takes five steps.
What you need
Access to the configuration of the web server Imperia publishes to, or someone who has it. On Apache, a .htaccess file is not enough
Your Imperia developer, for steps 3 and 5. If an application builds your store finder page (see below), that application's developer
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
How your site serves the store finder page
Some steps differ with your web server and with where the page comes from. To find out, ask whoever runs your web server.
Your web server is Apache or Nginx. Each step shows both.
The page comes from one of two places:
-
a) Imperia publishes it as a file. Imperia writes each page it publishes into the document root of your web server: the page
https://www.example.com/store-locatoris a file such as/var/www/site/store-locator/index.htmlthere. Find out: look for that file on the web server. On a site with several languages, Imperia may name itindex.html.deor similar: then use that name wherever this guide saysindex.html. -
b) An application builds it. On some sites, an application behind the web server builds the pages and puts content from Imperia into them. The web server passes the page's address on to the application, with
ProxyPassor aRewriteRulewith[P]on Apache, orproxy_passon Nginx. Find out: the page has no file under the document root, and the web server's configuration sends its address to the application.
If your published pages have lines such as <!--#include virtual="/ssi/navigation/..." --> and your menus show on the site, Imperia brings your menus in as includes, and your web server already runs them. The steps below still apply.
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 theincludes repeat (step 3), anddata-baseurl, which you remove in step 3 - settings your site's scripts pass to
UberallStorefinderMountorUberallStorefinderRestart, other thanwithoutMap
To find them, look in two places:
-
The store finder's
div, in the page's source: anydata-attribute other than the ones theincludes repeat. -
Your site's scripts, in the page's source and in your site's JavaScript files: calls to
UberallStorefinderMountorUberallStorefinderRestart.
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 web server to Uberall
On Apache
These Apache modules must be on: include, proxy, proxy_http, ssl, headers and rewrite, and for b), deflate too. Most servers have them already. If not, your hosting provider can turn them on.
Open your site's configuration, the file 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/ssl/certs/ca-certificates.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>
Paste it below the <Location> blocks your <VirtualHost> already has, such as a <Location "/"> that sends addresses to an application, and do the same with the <Location> of step 2. When two <Location> blocks set the same thing for an address, the later one wins.
On Nginx
Open your site's configuration file, usually in /etc/nginx/sites-enabled/ or /etc/nginx/conf.d/. Paste this inside the server { ... } block, and replace YOUR_RENDER_TOKEN with your token:
location /api/locator-fragments/ {
internal;
proxy_pass https://uberall.com;
proxy_ssl_server_name on;
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
proxy_pass_request_headers off;
proxy_set_header x-uberall-render-token "YOUR_RENDER_TOKEN";
proxy_connect_timeout 2s;
proxy_read_timeout 10s;
proxy_intercept_errors on;
error_page 400 401 403 404 405 408 413 414 429 431 500 502 503 504 /empty-fragment;
}
location = /empty-fragment {
internal;
return 200 "";
}
On both
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:
| System | File |
|---|---|
| Debian, Ubuntu, Alpine | /etc/ssl/certs/ca-certificates.crt |
| Red Hat, CentOS, AlmaLinux, Rocky, Amazon Linux | /etc/pki/tls/certs/ca-bundle.crt |
| openSUSE | /etc/ssl/ca-bundle.pem |
If yours is not there, openssl version -d shows the folder where OpenSSL keeps it.
Step 2: Turn on includes for the store finder page
a) A page Imperia publishes, on Apache
In the same <VirtualHost>, paste this. Replace /var/www/site/store-locator with the folder that holds your store finder page:
<Directory /var/www/site/store-locator>
Options +IncludesNOEXEC
AddOutputFilter INCLUDES .html
SSIErrorMsg "<!-- -->"
</Directory>
If your menus already come in as includes, paste it anyway: SSIErrorMsg keeps an error message off the page when the store finder content does not arrive.
a) A page Imperia publishes, on Nginx
In the same server { ... } block, paste this, with your store finder's address:
location ~ ^/store-locator(/|$) {
ssi on;
}
It takes the store finder's address with and without the / at the end. Paste it above every other location ~ and location ~* block in that server: Nginx uses the first of them that matches.
For the store finder's addresses, this location takes over from the one that served them before. If that one sets anything, such as root, add_header or access rules, copy those lines into this one.
b) A page an application builds, on Apache
In the same <VirtualHost>, paste this, with your store finder's address:
<Location "/store-locator">
Options +IncludesNOEXEC
SetOutputFilter INFLATE;INCLUDES;DEFLATE
SSIErrorMsg "<!-- -->"
</Location>
The page comes from the application, not from an .html file, so it needs SetOutputFilter. INFLATE unpacks the page when the application sends it compressed: Apache does not run the includes in a compressed page. DEFLATE compresses it again for browsers that accept it.
Paste it below your own <Location> blocks, as in step 1: a SetOutputFilter in a later block for the same address would replace this one.
b) A page an application builds, on Nginx
In the same server { ... } block, paste this, above every other location ~ and location ~* block. Replace /store-locator with your store finder's address, and http://YOUR_APPLICATION with the scheme, host and port from the proxy_pass line that sends the application's pages today, such as http://127.0.0.1:8080. Leave out anything after the port, even a /: in this location, Nginx refuses a proxy_pass with a path.
location ~ ^/store-locator(/|$) {
ssi on;
proxy_set_header Accept-Encoding "";
proxy_pass http://YOUR_APPLICATION;
}
Accept-Encoding "" asks the application for the page uncompressed: Nginx does not run the includes in a compressed page.
For the store finder's addresses, this location takes over from the one that sent them to the application. Copy into it that one's other proxy_ and include lines, such as include proxy_params;, and the proxy_set_header lines of your server and http blocks: a location with a proxy_set_header of its own takes none from them.
Step 3: Put the store finder on its page
The page needs the two includes and the store finder snippet shown below. Replace YOUR_LOCATOR_KEY with your locator key, in all three places.
On Apache:
<head>
<!-- ... 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>
On Nginx:
<head>
<!-- ... your head, without its own title, canonical, description and og: tags ... -->
<!--# include virtual="/api/locator-fragments/head?key=YOUR_LOCATOR_KEY&path=$request_uri" wait="yes" -->
</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 first include goes just before </head>. The second goes inside the store finder's div. Keep path=${REQUEST_URI}, or path=$request_uri on Nginx, at the end of each line.
Where the lines go
Each include line is an HTML comment, and they must reach the web server exactly as written above.
- a) A page Imperia publishes: your Imperia developer puts them in the template the store finder page is published with, or in a code include of it, where your menus' include lines are. Not in the editor: by default, Imperia's editor removes HTML comments (Imperia admin manual). If other pages share that template, the lines go in a part only the store finder page uses: on other pages, they would ask Uberall on every visit and get nothing back.
-
b) A page an application builds: the application's developer puts the first line in the page's
<head>, in the application's template. Thediv, the second line and thescriptcan come from the application's template, or from a template or code include in Imperia, but not from text typed in Imperia's editor.
The store finder's div
The div must be in the page's HTML, with the second include inside it.
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.
On the store finder pages, 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).
If the page already has the store finder snippet, keep it, once its settings are at Uberall (the section above): add the two includes.
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).
Imperia's menus can link to a page by its file, such as /store-locator/index.html. The store finder reads whatever follows its address as a store's address, so on that link it finds no store. Link to the store finder by its address, or set up the address with the file name in it, such as https://www.example.com/store-locator/index.html.
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=:
| Snippet attribute | Include parameter | Without it |
|---|---|---|
data-key |
key |
Required |
data-widgetoriginurl |
widgetOriginUrl |
The store finder's address set up at Uberall |
data-language |
lang |
The language set up at Uberall |
data-countries |
countries |
The stores of every country set up at Uberall |
With data-language="de", data-countries="US,DE" and data-widgetoriginurl="https://www.example.com/store-locator" on the snippet, the first include reads, on Apache:
<!--#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, such as /store-locator/l/berlin/.... Your server has to answer all of them with the store finder page. It has to answer the store finder's own address without the / at the end too: that is the one Uberall puts in the page's canonical link.
a) A page Imperia publishes, on Apache
In the same <VirtualHost>, paste this, with your own address and page:
RewriteEngine on
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} !-f
RewriteRule ^/store-locator(/|$) /store-locator/index.html [PT,L]
Without the rule, Apache sends a visitor of /store-locator on to /store-locator/, and answers a store's address with "Not Found". The RewriteCond leaves alone the files Imperia publishes in the store finder's folder, such as images.
a) A page Imperia publishes, on Nginx
Add one line to the location from step 2, with your own page:
location ~ ^/store-locator(/|$) {
ssi on;
try_files $uri /store-locator/index.html;
}
b) A page an application builds, on Apache
The application answers its page, but not the addresses under it. In the same <VirtualHost>, paste this above your other RewriteRules. Replace http://YOUR_APPLICATION/store-locator with the address your server sends the store finder page to, from its ProxyPass line:
RewriteEngine on
RewriteRule ^/store-locator/ http://YOUR_APPLICATION/store-locator [P,L]
If your server sends every address to the application with a RewriteRule, add this line just above that rule, or the includes go to the application too:
RewriteCond %{REQUEST_URI} !^/api/locator-fragments
It also keeps the includes of a second store finder, at /api/locator-fragments-2/ (below), away from the application.
b) A page an application builds, on Nginx
Add one line to the location from step 2, with your own address:
location ~ ^/store-locator(/|$) {
ssi on;
proxy_set_header Accept-Encoding "";
rewrite ^ /store-locator break;
proxy_pass http://YOUR_APPLICATION;
}
rewrite names the page as the application knows it. If the proxy_pass line you took the application's address from had a path, such as http://127.0.0.1:8080/cms/, put that path in front: rewrite ^ /cms/store-locator break;.
Step 5: Publish, restart and check
For a), your Imperia developer has the store finder page generated again with the change from step 3, and published. Imperia keeps the HTML a page was generated with until then, and your web server gets the new HTML only when Imperia publishes it. In Imperia, that is Structure → Template Reparser, with Re-generate the content and Add reparsed documents to the publishing list (Imperia admin manual), or Reparse on the page in the document browser (Imperia user manual).
Then check that the published file has both include lines exactly as in step 3, ${REQUEST_URI} or $request_uri included:
grep 'include virtual' /var/www/site/store-locator/index.html
For b), check the page the application sends in the same way, at the address the application knows it by:
curl -s http://YOUR_APPLICATION/store-locator | grep 'include virtual'
If a line is missing or different, see step 3.
Then restart your web server:
sudo apachectl configtest && sudo apachectl graceful
or, on Nginx:
sudo nginx -t && sudo nginx -s reload
Check on your live site, not in Imperia's preview: steps 1, 2 and 4 set up the web server Imperia publishes to, not Imperia itself.
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. Check in the browser, not with a command such as curl: browsers ask for compressed pages, and on b) only a compressed page shows whether step 2 is right.
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 block from step 1 sends one. So the second store finder gets a block of its own. Paste it below the one from step 1, and replace YOUR_OTHER_RENDER_TOKEN with the second store finder's token.
On Apache:
<Location "/api/locator-fragments-2/">
Require expr %{IS_SUBREQ} == 'true'
RequestHeader set x-uberall-render-token "YOUR_OTHER_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>
It differs from the first only in its address, /api/locator-fragments-2/, and in the token. Do not paste the first one twice with another token: Apache would send the last token for both store finders.
On Nginx:
location /api/locator-fragments-2/ {
internal;
proxy_pass https://uberall.com/api/locator-fragments/;
proxy_ssl_server_name on;
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
proxy_pass_request_headers off;
proxy_set_header x-uberall-render-token "YOUR_OTHER_RENDER_TOKEN";
proxy_connect_timeout 2s;
proxy_read_timeout 10s;
proxy_intercept_errors on;
error_page 400 401 403 404 405 408 413 414 429 431 500 502 503 504 /empty-fragment;
}
It differs from the first in its address, /api/locator-fragments-2/, in proxy_pass, which ends in /api/locator-fragments/ here, and in the token.
Then follow steps 2 to 5 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
| What you see | What to do |
|---|---|
configtest or nginx -t reports an error |
A module from step 1 is off, a block is outside <VirtualHost> or server { ... }, or the certificate file does not exist. Ask your hosting provider. |
nginx -t says "proxy_pass" cannot have URI part
|
Remove everything after the port from the proxy_pass of step 2. |
The published file, or the application's page, has no include lines |
Imperia or the application removed or changed them, or the page was not generated again. See steps 3 and 5. |
The source still shows the include lines, and Imperia publishes the page |
Check step 2: the folder or location is not the one of the page, on Apache the page's file name has no .html in it, or on Nginx another location ~ comes first. |
The source still shows the include lines, and an application builds it |
Check step 2: on Apache, SetOutputFilter INFLATE;INCLUDES;DEFLATE, the deflate module, and no later <Location> with its own SetOutputFilter; on Nginx, proxy_set_header Accept-Encoding "";. |
| The page shows "[an error occurred while processing this directive]" | Add the SSIErrorMsg line from step 2. |
The store finder's address without / sends you on to the address with /
|
Check step 4. |
| A store's page says "Not Found" | Check step 4. |
__ubSfSsr is not in the source, and an application builds the page |
The includes may go to the application: see the end of step 1 on Apache, and the RewriteCond in step 4. |
__ubSfSsr is not in the source |
Check the token and the key in step 3, and that your store finder's address is set up at Uberall. Then contact Uberall. |
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. There is no need to publish again in Imperia: the includes fetch the stores each time the page is opened.
If your server or your CDN caches your pages, add the time your cache keeps them: each store finder page in that cache keeps the content it had when it was cached. And a page your cache stored while the content did not arrive stays without its stores, for search engines, until your cache stores it again.