Embedding

Embedding lets you place a Topologis view inside your own website.

Embeds use the same view model as shared links, but the delivery method is different. Instead of opening a hosted /view/{viewId} page, your site loads a script for a specific view and mounts the map into a container element on your page.

How embeds work

Embedding always starts from a view.

The embed runtime loads that view’s current saved settings, including its layers, filter behavior, style choices, tooltip settings, and embed layout options. If you need to control what the embedded map looks like first, configure the view before you copy the embed code. For the full view model, see Views.

Copy the embed script

Open the view you want to embed and use the Embed section in the view settings.

Topologis generates a script tag for that view. The current pattern is:

<script src="EDGE_URL/embed/VIEW_ID/topologis.js" defer></script>

Use the exact script generated by the editor. It includes the current view ID and points to the embed runtime that will request the published map for that view.

Add the container element

After the script, add the container element that will hold the embedded map.

The current pattern is:

<div id="VIEW_ID"></div>

The container id must match the embedded view ID. The runtime looks for that exact element before it mounts the map. If the container is missing or the id does not match, the embed cannot render into the page.

Choose an embed size

Embed sizing is configured on the view, not in the script itself.

In the Embed section for the view, Topologis lets you choose:

• Landscape
• Square
• Portrait

These options define the view’s preferred aspect ratio for the embedded map. This is useful when you want one view optimized for a wide website section and another view optimized for a narrow or card-style layout.

Aspect ratio and fill options

The same Embed section also controls how the map fills its container.

The current fill options are:

• Fill width
• Fill height

If only one fill option is enabled, Topologis uses the view’s aspect ratio to size the embed. If both Fill width and Fill height are enabled, the aspect ratio is ignored and the map fills both dimensions instead.

In practice, Fill width is the safer default for most pages. If you enable both dimensions, make sure the surrounding layout gives the map enough space to render cleanly.

Allowed hosts

Embeds are protected by an allowed-host check.

Before an embed is allowed to load, Topologis checks the requesting page’s host against the allowed host list configured in the dashboard Allowed Hosts page. If the host is not allowed, the embed script returns a Topologis error panel instead of the map.

The current host check is strict:

• It matches by hostname
• It ignores port numbers
• It does not automatically allow other subdomains

This means example.com and www.example.com should be treated as different hosts when you configure embeds.

Testing your embed

After adding the script, container, and allowed host entry, load the page where the map should appear.

Check these basics first:

• The embedded view is the one you intended to publish
• The script tag and container both use the same view ID
• The current site host has been added to the allowed host list
• The view has been saved after any recent changes

If those conditions are correct, the map should load into the container on your page.

Troubleshooting embeds

If the embed does not work, start with the most likely failure points.

If you see a Topologis error message inside the embed area, the host check is the first thing to verify. If the page shows no map, confirm that the container exists and that its id exactly matches the view ID from the generated embed code.

If the map loads but looks wrong, the issue is usually in the view rather than the embed code. Recheck the view’s enabled layers, style choices, filters, camera, and embed size settings. If you are comparing a shared link and an embed, remember that both are driven by the same underlying view, while host restrictions only apply to the embed path.