Background/Foreground image URL requirements for /setMap


I’m playing around with setting a map’s background/foreground using the API. I’ve been able to achieve this successfully by passing the following map content to /setMap:

    'backgroundImagePath': image_url,

However, it only works if the image URL is that of an image that has been previously uploaded to Gather (manually via Mapmaker), like:<space_id>/<image_id>

If I try to use my own publicly-hosted image file URL from a non-gather domain, the API doesn’t seem able to set the background.

Is this expected? If so, is there an API to upload an image to Gather? I don’t see and endpoint advertised in the docs. Otherwise what’s the recommendation on how to upload/host images in this case?

Thanks for any help!

Without seeing any error logs from the space console, it is my guess that you are running into a CORS error, because either Gather or the image host isn’t letting the image data transfer.

For uploading images, check out the Gather Poster Upload Example:

It has an example of uploading an array of images to the Gather CDN. Ill have to check if there are any recent changes to this endpoint, but I believe it should get you going as is.

Thanks! That helps.

I see two types of errors in the console, one if I try to use an http image URL

Mixed Content: The page at 'blob:<GUID>' was loaded over HTTPS, but requested an insecure resource 'http://<redacted>.png'. This request has been blocked; the content must be served over HTTPS.

And indeed a CORS issue with https URLs:

Access to fetch at 'https://<redacted>.png') from origin '' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

That seems like it’s an issue on the image-hosting side potentially, not Gather, so I’ll keep trying to see if there’s a way to host the image over https without CORS getting in the way. Thanks again!

You may be able to just change http://{redacted}.png to https://{redacted}.png, and see if that works. I sometimes use an ftp that gives me http addresses, but the https versions also work.

And yeah, you may need to test a few different settings to fix CORS. Someone from Gather proper might have better insights on the specific site you are using.

Alright I think I arrived at the correct requirements now. I just tested a random https Imgur image URL ( ) and it works.

So I think as long as the URL:

  1. Is https, and
  2. Doesn’t have CORS access issues (testing with this site seemed helpful and correctly identified my previous URLs as CORPS-incompatible and Imgur as CORS-compatible)

Gather seems to be able to use it.

Thanks for the nudge in the right direction!

Thanks for the information @noemartinez. The CORS access test site is very helpful.

Does anyone have any suggestions for hosting audio files on Gather or a third party CORS-ready storage platform?

Hi there, quick response here

S3 would be a fine choice. Not an endorsement of S3, there are many other available options. Just put it in a cloud storage bucket (alternatives include GCP, Azure, DO Spaces, etc) and make it publicly available. If you already have your own dedicated server, you may also consider using Nginx, Traefik, etc to serve the static files from the server itself.

If you have extremely high volume, on the order of thousands of requests per minute, you can use a service like CloudFront or Akamai to improve performance. This is probably unnecessary for all but the heaviest users of Gather.

As I said above, none of this is an endorsement of a particular product or service by Gather, and should be taken as general engineering knowledge :slight_smile:

Hope this helps!

  • opalrose