Develop and Test a WebAR Experience Locally
The license purchased for a particular domain can only be used when the WebAR SDK and the developed AR experience is hosted on a HTTPS webserver having the same domain name. But when developing and testing an AR experience, it would be inconvenient to republish to the Remote HTTPS webserver after every code change.
Do not worry. WebAR SDK's Developer mode allows you to run and test your AR experience in your local HTTPS server having a private IP address as the domain name and provided you have a Valid License purchased from Blippar.
There are many ways to setup a local HTTPS server using a Self-Signed SSL Certificate in a development environment. This section explains setting up a local development environment using Visual Studio Code.
- Find the IP Address of your PC
- Download the WebAR SDK
- Open a WebAR Project
- Open a Terminal in VSC
- Install the mkcert tool
- Create the Self-Signed SSL Certificate
- Install a Live Server Extension in VSC
- Configure the HTTPS Server
- Start the HTTPS Server
- Experience WebAR in a Mobile Browser
Step 1: Find the IP Address of your PC
Note down the IP address of your PC which is connected to a LAN/WiFi network. In the following steps a HTTPS server will be setup which will be accessed using the ip address of your PC. The goal after completing all the following steps is to access the local HTTPS server from the mobile browser via https://<your_PC_ip_address>:5500/example/index.html url
- Let's say for example, the IP address of your PC is 192.168.68.105 and the same will be used in the commands of the following steps. Make sure in all the following commands to replace this example IP address(192.168.68.105) with the actual IP address of your PC.
- Dynamic IP address: When your PC connects/reconnects to your Home Network Router via LAN/WiFi, its IP address could change i.e it would be different from what you see now in this Step. So you have to repeat this step whenever you start your PC or your mobile browser fails to access HTTPS server via https://<your_PC_ip_address>:5500/example/index.html url
- Static IP address: To avoid change of IP address allocated by your Home Network Router to your PC, check your Router user manual to see how to assign a static IP address permanently.
The following slide shows how to identify the IP address of a MacBook connected to a WiFi network to which the mobile phone is also connected. Similarly identify the IP address on your respective OS platform.
Step 2: Download the WebAR SDK
After purchasing a License, download the WebAR SDK and unzip it in a folder.
As you may see, it has two folders:
- example - contains an example index.html and a sample model to try the WebAR SDK
Step 3: Open a WebAR Project
Install Visual Studio Code (VSC)
Download Visual Studio Code from this link and Install it on your Windows/Linux/macOS PC.
After installation is complete, open a Visual Studio Code application to see an empty Project.
From the empty Project opened in VSC,
- Click the Explorer icon on the left panel
- Click the Open Folder Button
- After navigating to the unzipped WebAR SDK folder, click the Open Button
Step 4: Open a Terminal in VSC
A Self-Signed SSL Certificate can be generated in many ways. Here we use the mkcert tool to generate a Self-Signed SSL. If you use any other methods to generate a Self-Signed SSL, make sure the IP address of your PC is used as the domain name of the Certificate.
In VSC, go to Terminal -> New Terminal to open a Terminal console in the bottom panel.
The mkcert tool can be installed from the package manager of the corresponding OS platform. So first make sure the platform's package manager is installed.
On Linux & Windows: Install package manager
Follow the instructions in this page and install the package manager of your OS platform which is needed to install the mkcert tool and go to the next Step.
On macOS: Install brew package manager
The brew package manager is needed to install the mkcert tool. If brew is not already installed, type the following command in the Terminal console to install brew first.
Skip this command if you have already installed brew.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
While running the command, it will ask for the `sudo` access password.
Enter your MacBook login password for installation to complete successfully. Also make sure there are no errors at the end.
Step 5: Install the mkcert tool
On Linux & Windows:
Follow the instructions in this page and install the mkcert tool using the package manager of your OS platform and then go to the next Step.
In the Terminal console, type the following command to install the mkcert tool.
brew install mkcert
Step 6: Create the Self-Signed SSL Certificate
In the terminal, go to home directory and create a new directory named ssl and create the SSL certificate in this folder.
Create ssl directory
Run the following commands inside the ssl directory to generate the Self-Signed Certificate.
Note: In the second line of the above command, make sure to replace 192.168.68.105 with the ip address of your PC.
The above command will generate two files: a certificate and a key.
- 192.168.68.105.pem - Certificate
- 192.168.68.105-key.pem - Key
- The actual certificate file names will be different as they will be based on the IP address of your PC
- Dynamic IP address: When your PC connects/reconnects to your Home Network Router via LAN/WiFi, its IP address could change i.e it would be different from what you have noted down in Step 1. So you have to repeat Step 1 and Step 6 whenever you start your PC or your mobile browser fails to access HTTPS server via https://<your_PC_ip_address>:5500/example/index.html url
- Static IP address: To avoid the change of IP address allocated by your Home Network Router to your PC, check your Router user manual to see how to assign a static IP address permanently.
Note down the full/absolute path of the certificate and key files which will be needed in the coming steps.
On macOS & Linux:
Type the following command inside ssl folder to see the certificate and key files with full/absolute path which will be needed in the coming steps.
ls -1 -d "$PWD/"*
Step 7: Install a Live Server Extension in VSC
Live Server is an easy to setup and simple HTTPS server which will server your WebAR application.
- Click the Extensions icon on the left panel.
- Search for Live Server.
- Click Install to install the extension.
Step 8: Configure the HTTPS Server
- In the left Explorer panel, click in the empty space below the example folder
- Click the New Folder icon to create a folder named .vscode
- Inside the .vscode folder click the New File icon to create a file named settings.json
- Open the settings.json file and copy paste the following json content
"enable": true, //set it true to enable HTTPS server.
"key": "", //full path of the private key
"cert": "", //full path of the certificate
- Copy paste the full/absolute path of the Self-Signed SSL key file generated in Step 6 and enter it as the string value of the "key" parameter as in the following json file
"key" : "/Users/<user_name>/ssl/192.168.68.105-key.pem"
- Copy paste the full/absolute path of the Self-Signed SSL certificate file generated in Step 6 and enter it as the string value of the "cert" parameter as in the following json file
"cert" : "/Users/<user_name>/ssl/192.168.68.105.pem"
In points 5 and 6 above:
- Replace <user_name> with your actual system user name you see on your terminal.
- Replace 192.168.68.105 with the actual IP address of your PC or use the actual certificate and key files name created from Step 6
Step 9: Start the HTTPS Server
- Open the example/index.html file and enter a valid License key purchased from Blippar.
- On the bottom right corner of VSC, click Go Live to start the HTTPS server and look for status changing to Starting... and the Port:5500
- Open Safari/Chrome browser on PC and enter the following url
Replace 192.168.68.105 with the actual IP address of your PC.
Append port 5500 to your IP address as this is the port number configured in the .vscode/settings.json file in Step 8
- On the browser you can see the WebAR SDK desktop page with a QR code and a Green coloured banner on top displaying DEV MODE.
Step 10: Experience WebAR in a Mobile Browser
On your mobile phone,
- Make sure it is connected to the same LAN/WiFi network as your PC and it is not behind any VPN or Gateway.
- Open the Camera app and Scan the QR code displayed from Step 9
- On an Android phone, click the Lens icon to scan the QR code
- Click the url scanned from the QR code to open it in the Android Chrome or Safari browser
- When loading a site from a self-signed certificate for the first time, you may see a Your connection is private warning
- On Android Chrome, click Advanced and then click Proceed to 192.168.68.105(unsafe)
- Now you can see the WebAR experience loaded with a Green coloured banner on the top displaying DEV MODE.