How to load super nice Mapbox maps in WeChat apps?
Mini programs are becoming a Pre-App, testing the functionality and user scenarios of apps in a lightweight manner, enabling smarter decisions in the official app development.
Unfortunately, in WeChat mini programs, only the platform's own maps are supported, such as basic map displays.
So, are developers only able to longingly look at Mapbox's stunning styles?
Of course not!
Let Mapbox China Maps Engineer Mofei show you below
Whether it's showcasing geographic locations
Or data visualization
Or even navigation information...
All your desires can be fulfilled
Let's take a look at some effectsIn WeChat mini programs, you can not only display maps in Chinese
But also switch map styles
Various artistic style map styles in Mapbox Studio can be freely added
Indoor 3D maps are supported
Data analysis is also possible, like the currently popular and cool heat maps
And even cloud maps from satellites
Isn't that amazing!
Mini programs and maps can be so cool
How is this achieved?
⚖️ The Principle
That's right! Perhaps you've guessed it already, it's implemented through WeChat's web-view component, simply put, by opening an interactive webpage directly inside the mini program (time to show off your Mapbox GL JS skills).
That sounds easy! We just released a tutorial on creating interactive web pages with Mapbox a couple of weeks ago "Mapbox Interactive Story Maps" Beginner's DIY Guide | With 27 Types of Interactive Animation Source Code, why not just use that directly?
Two Requirements for Displaying Mapbox in Mini Programs
However, according to the documentation, to call Mapbox maps through web-view, the following two conditions must be met: 1. The mini program must be owned by a corporation, as WeChat's web-view component is not open to personal types of mini programs. 2. You need to have your own domain and verify it in the WeChat backend when embedding web pages (only web pages under your own domain can be correctly displayed, you can't just use any public link).
If you meet these two conditions, then you can happily follow our step-by-step operation!
Specific Implementation Steps
Preparation of Learning Materials
- Mapbox GL JS Official Open Source Examples: Here, you can find a rich variety of open-source web pages. You only need to copy the source code and save it as an "xxx.html" file, then upload it to your own server, and it can be accessed at "https://yourdomain/xxx.html".
- WeChat Mini Program Official Quick Start: If you have some programming background but have never developed a mini program, you can quickly grasp it through this document.
- WeChat Mini Program web-view Official Documentation: You can understand the basic and advanced features of web-view in detail, which is convenient for your understanding.
- Alibaba Cloud Server and Domain Setup: If you do not have your own domain and server, you can spend about 2 hours to set it up from scratch (excluding the time for domain registration), you may consider purchasing a domain (which requires registration + SSL certificate authentication) + cloud virtual host. You can find out more by checking Alibaba Cloud's official website, no more explanations here.
Domain Verification
Due to WeChat's regulations, the address pointed to by web-view must be a domain registered in the WeChat mini program backend, otherwise a "Opening non-business domain names is not supported, please reconfigure" message will appear.
First, we find the Development > Development Settings > Business Domain Module in WeChat's backend, and fill in the domain you need to bind.
It is important to note that the domain here is forced to use https, you need to configure the https certificate properly, and when purchasing a server, make sure to buy one that supports https.
Next, we need to download a verification file from WeChat, place it in the root directory of your domain, and ensure it is accessible.
Specifically, if your domain is abc.com, and WeChat's verification file is WATLNxupm4.txt, you need to ensure that https://abc.com/WATLNxupm4.txt can be accessed publicly.
Once confirmed, click save to successfully save.
Embedding a web-view with a map
This process is actually quite simple, find your WeChat mini program's .wxml file and add the following code
<web-view src="https://abc.com/map.html"/>
Where https://abc.com/map.html
is an H5 page with a map. This H5 page is actually created with Mapbox GL JS, and you can build this page in two ways:
- Copy the source code from Mapbox GL JS official open-source examples and save it as an html file.
- Refer to the official Mapbox GL JS documentation and add a map to your existing H5 page.
Regardless of the method used, as long as “https://yourdomain/xxx.html” is accessible, it can display the page you want to show.
It's important to note that: the web-view in WeChat mini programs can only be full-screen and will cover all other components on the page.
Some tips for mini program web-view
- To determine if it is within a WeChat mini program in a webpage, you can use window._wxjsenvironment === 'miniprogram' for the check.
- If the webpage wants to pass information to the mini program, it can use the wx.miniProgram.postMessage method.
- The mini program can listen to data passed back from the webpage through the postMessage method, but this method only triggers at specific times (mini program back, component destruction, sharing), and cannot pass messages in real-time.
Summary
In summary, embedding maps through web-view is a workaround, and the interaction and performance might not be as smooth as WeChat mini programs, but this approach also provides us with some new solutions to problems.
For specific needs, we can accomplish some functions through web-view that are impossible or inconvenient to implement with WeChat components, and then pass them back to the WeChat mini program through postMessage.
It's strongly discouraged to place everything in an H5 and directly embed it into the WeChat mini program. Not to mention passing WeChat's review, there's a significant gap in the interaction experience between many functionalities in the page and WeChat mini program's native components.
Show off more effects!
Besides what has been introduced at the beginning, the flexibility and open-source nature of Mapbox allow you to quickly achieve numerous effects in a short time.
Below are the effects that developers have implemented in just a few hours in mini programs
Hope you can add beautiful Mapbox maps to your mini programs!