Introduction to the WeChat JS SDK & How to Build a Scanner App

A kickstarter for developers on how to use the functionalities of a wechat micro-website.

With the current WeChat hegemony that’s found in China, we find that our team has increasingly been working on mobile “HTML5” micro websites that are designed to run specifically in the Wechat browser. The smart guys at Tencent have put together a very nice javascript library that allows developers to leverage an array of native Wechat app functionalities directly within a web page : we’ll introduce here how it augments what you can do, through the specific example of building a QR scanning application directly within a web page.

AUGMENT YOUR WEB PAGE CAPABILITIES WHEN BROWSED WITH WECHAT

The Javascript Software Development Kit (or “JSSDK”) is one of the most fascinating features of the WeChat browser, as it allows us to implement a small javascript library file into our codebase, to leverage native WeChat functionalities directly within the page, such as scan a QR code, record a video, uniquely identify your visitor, or upload images, functionalities that would not be accessible to your website/page if it was browsed with another browser, such as your native smartphone browser. Think of this as your web page running on steroids, having features that would not be available by just using the native HTML capabilities.

That might still sound a little abstract like this, so here are a couple application examples:

— You can put a link or a button on a page to trigger WeChat’s QRcode scanner : the page to retrieve the scanned result to update the page’s content without having to leave the browser, as opposed to :

1. leave the wechat browser
2. tap on the “+” right menu
3. select scanner.

This could be used for an audioguide running in the wechat browser for example (either as a standalone page or behind an official account) :

— If we are selling merchandise we can use WeChat’s processing payments function directly inside our web page and allow the visitor to pay using WeChat Wallet.

— Or maybe we want to record the user’s voice and have it translated into text, we can also do this using WeChat’s speech to text function.

Getting excited? Let’s get to work then. In order to get these functionalities working, we will first need to familiarize ourselves with the Wechat JS SDK API.

DOCUMENTATION AND DIFFICULTIES FOR DEVELOPERS WITH LIMITED CHINESE CAPABILITIES

As WeChat is mostly targeting the Chinese market, we would be surprised if a few English resources were actually available on the web. Luckily for us, the WeChat developers took some time to translate a good part of their Chinese documentation into English. By reading through this documentation we will find just about everything we need to know to get us started.

Please note that the chinese documentation stands as a final reference and should be used whenever something is not clear on the English version.

WHAT YOU NEED

• An Official Account
• A Server with Php installed (the Php Curl library should be enabled)
• A Domain Name with proper ICP registration

STEP 1 : CONFIGURING THE OFFICIAL ACCOUNT AND GETTING THE APP ID & APP SECRET

To be able to work with the wechat API, we will need to authorize our website domain and obtain an APP ID and an APP secret.

To accomplish this log into your WeChat account here.

Now click on your account settings found on the top right, then on 功能设置 →JS接口安全域名, click on the button 设置.

After clicking the button a popup will appear where you can configure up to three different domain names.

These domains need to be registered with an ICP beforehand.

If your domain names have not been attached to an ICP registration, they will not be accepted and WeChat’s Administration will throw you a nice error “域名1不支持未通过ICP备案的域名”

Now let’s get our wechat APP ID and APP Secret. Go now to 开发 > 基本配置. On top you will find your AppID(应用ID) and AppSecret(应用密钥). Write them down somewhere, we will need to use them later.

Caution: I have seen people sharing their APP Secret, Please don’t do that, as its name suggests, that’s the variable that should stay secret from our users.

STEP 2 : USING THE SDK TO AUTHENTICATE YOUR APP WITH WECHAT

We will be using PHP to build a system that can get all the necessary information from the WeChat API. You can download the resulting source code on 31Ten’s Github account.

For the sake of simplicity and clarity, we will not be using any framework/library/wrapper, only simple php files.

Now open up 1_demo_all/all.php with your wechat browser, if everything is correct you should see an alert with the message {“errMsg”: “config:ok”}

WHAT’S HAPPENING BEHIND THE WHEELS

The authentication of Wechat is described in the documentation they provide, but here is a schema that sums up what’s happening:

Wechat has a two stage authentication mechanism based on 1) tokens 2) tickets : we need a logical process that will allow our server to generate tickets and tokens to keep our app communicating with the Wechat servers. So in the jssdk.php file we are calling two functions, getJsApiTickets and getAccessToken. Inside these functions we are implementing a logic to check if our current ticket and token are expired, if they are not expired then proceed with the request to the server. If the ticket or token is expired we are then making calls to WeChat’s server so they can provide us with an updated ticket and/or token..

STEP 3 : LET’S BUILD A SIMPLE WEB APP WITH QR CODE SCANNING CAPABILITY

Our goal here, as exposed in our audioguide example earlier, is to leverage the use of the native Wechat QR Code Scanner inside of a HTML5 page. To do so we will build a simple QR Code scanner web app that will:

1. Trigger the WeChat QR Scanner without leaving the browser, just by the press of a button
2. Scan a QR Code
3. Display the decoded information contained in the QR Code on the web page (a QR code is basically a two dimensional representation of a string of characters, a URL being the most common content in China)

Let’s look at our code:

First, we create a new file called “scanner.php”

Let’s call the JS SDK and input our APP ID and APP Secret

We add the CSS library Materialize to have a nice Graphical interface

Let’s improve the design of our webpage (for practical reasons, I put everything on the same page, but the CSS and JS files should be in separate files when working on production code).

Let’s create the html that will allow the user to scan a QR Code and have that information displayed to them.

Lets now add our JS, following the WeChat Documentation we must create a new wx.config and then we will have all the required parameters output by PHP.

Inside the wx.config, in the jsApiList we are specifically asking to use the scanQRCode function that WeChat provides for us.

Here is the basic code for retrieving the string produced by a successful scan

Let’s improve it a bit so that when a user scans a QRcode, it will create a new card on the page

Finally let’s add some processing code that parses the string of our result from the QR Code. If the QR Code begins with ‘http’ or ‘https’ we understand it as a link, if it ends with an image file extension we output an html image tag, and if it contains neither of these we display the resulting string as plain text. Let’s go back to the wx.ready function and refactor it.

There you have it, you now have a fully functional QR Scanner that will display whatever datas inside.

Lets wrap up the final code :

The whole source can be found there :

31ten/wechat-qrcode-scanner

Thanks for ready, let me know for any comments!