The iframe will only work if we've whitelisted your domain. You can test it out on localhost or 0.0.0.0 sites though. To get your domain whitelisted, see below.
No worries, if you just want something simple (for example if you’re a token and want to display your map on your showcase website) it’ll most likely be free. Contact us and we’ll discuss it, we might even want to share your initiative on our socials.
We have multiple pricings depending on volume, customization options, indexed tokens, marketing support, etc. Please, get in touch for more details.
You can iframe a bubble map by simply specifying the url of the map in the src attribute, like this:
<iframe src="https://app.bubblemaps.io/bsc/token/0x603c7f932ed1fc6575303d8fb018fdcbb0f39a95" />
The app automatically detects that it is displayed in a iframe and automatically handles the hiding of unwanted components like the navbar.
Note the simple structure of the url: https://app.bubblemaps.io/[chain]/token/[contract_address]. For now, available chains are eth, bsc, ftm, avax, cro, arbi, poly, base, sol and sonic.
Of course, you still have to style your iframe in terms of size and border to place it correctly in your layout. Keep in mind that browsers usually apply a default border on iframes, so if you don’t want it you’ll have to specify border:none; on your styling.
Please also note that only the graph view is available for iframing, other pages like the homepage or the listed token page will display errors if you try to iframe them.
If you are not on a custom plan, Bubblemaps non-premium restrictions apply in the same way they do on the main website. Which means that to be fully functionnal, the iframe has to reference a publicly available bubble map. This includes all the tokens listed on Bubblemaps, and specific tokens or NFT collections that we specifically made public. (If you need more tokens than this, get in touch with our team to discuss about our custom plans.)
To make things easier on your side, we’ve created an endpoint that you can call before rendering an iframe for a token or NFT collection to check if its bubble map is publicly available AND ready to display (ie already computed, in order to avoid any waiting or potential errors on the iframe). The endpoint guarantees that the map will be displayed fast and without restriction. We highly advice you to use it to conditionally render bubble maps iframes on your app.
It is called with a chain and a token parameter, just like the iframe:
https://api-legacy.bubblemaps.io/map-availability?chain=bsc&token=0x603c7f932ed1fc6575303d8fb018fdcbb0f39a95
It will always return a status field that can be OK or KO.
- If it's
OK, another fieldavailabilitywill be there with a boolean value. Atruevalue indicates that the corresponding iframe is ready to be displayed.
{"status":"OK", "availability":true}
- If it's
KO, a fieldmessagewill be available, with an explanatory value likeInvalid chain parameterfor example.
{"status":"KO", "message":"Invalid token parameter"}
The endpoint mentions legacy because we're working on the new version of Bubblemaps that will come with a new and more complete API, and we don't want any confusion between the two systems. But the legacy API is what is currently used on Bubblemaps and will be maintained as long as this iFrame system is maintained.
We made theming available on iframes so that Bubblemaps can be integrated smoothly in your interface.
For that, please ask our team to prepare a custom color palette. Then, your theme will simply be available by adding the corresponding theme query parameter to the iframe src attribute.
The theme is loaded dynamically, which means that if color changes are needed, they can be performed by our team without any code change on your side.
However, this also means that the standard Bubblemaps dark background will be showing while the theme is loading at the very beginning of the iframe render, resulting in a quick "flash". To avoid that, you can specify a second query parameter loading_color to define a color to display while the theme is loading. Basically, using the same color as the background will make the whole process seamless to the eyes of the user.
In the end, it should look like this:
<iframe src="https://app.bubblemaps.io/bsc/token/0x603c7f932ed1fc6575303d8fb018fdcbb0f39a95?theme=themename&loading_color=ffffff" />
By default, scrolling on a bubble map allow to zoom or dezoom the visualisation. In the case of an iframe integration, this means that the scroll behaviour is 'hijacked' by the iframe when the user is hovering it.
Depending on your layout, it could disrupt the user experience on your site. So if you want to, you can disable this behaviour with the prevent_scroll_zoom query parameter. No worries, the users will still be able to handle the zoom of the visualisation by double-clicking on it or by using the zoom buttons at the bottom right.
<iframe src="https://app.bubblemaps.io/bsc/token/0x603c7f932ed1fc6575303d8fb018fdcbb0f39a95?prevent_scroll_zoom" />
Depending on your overall layout, the space you saved for the Bubblemaps iframe might be small, thus making the Bubblemaps elements like the top buttons or the wallets table feel a bit 'squeezed'. Some options are available to make up for this:
small_text: Will make the texts, buttons, and a variety of other elements a little smaller. This will help to get some feeling of space.hide_context: Will remove the name of the token and the scanner link from the top buttons. This will lighten the iframe, while this information is most likely already available on the page you integrated the iframe into.
<iframe src="https://app.bubblemaps.io/bsc/token/0x603c7f932ed1fc6575303d8fb018fdcbb0f39a95?small_text&hide_context" />