diff --git a/docs/engine/overview.md b/docs/engine/overview.md index eeaba54..3bb3b0b 100644 --- a/docs/engine/overview.md +++ b/docs/engine/overview.md @@ -104,41 +104,22 @@ See documentation on the [Camera Pipeline Module API](/docs/api/engine/camerapip ### Test on Mobile -To test your project on mobile devices, especially for AR experiences that require camera access, you'll need to serve your development server over HTTPS. +To test your project on mobile devices, especially for AR experiences that require camera access, you'll need to serve your development server over HTTPS. We recommend using [ngrok](https://ngrok.com/) to create a secure tunnel to your local server. -1. If you do not already have `npm` installed, follow the instructions on this [page](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to set it up. -2. Run `npm install --global http-server` to install the [http-server](https://www.npmjs.com/package/http-server) npm package as a global CLI tool. -3. Install [openssl](https://github.com/openssl/openssl) and generate key.pem and cert.pem files using this command: -``` -openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem -``` - -You will be prompted with a few questions after entering the command. Use `127.0.0.1` as value for Common name if you want to be able to install the certificate in your OS's root certificate store or browser so that it is trusted. - -This generates a cert-key pair and it will be valid for 3650 days (about 10 years). - -Then you can run `http-server` with `-S` for enabling SSL and `-C` for your certificate file: -``` -npx http-server [project-path] -S -C cert.pem -``` - -Example: -``` -npx http-server gettingstarted/aframe/ -S -C cert.pem +1. Go to [ngrok.com](https://ngrok.com/) and create an account. Once signed in, follow the steps on the dashboard to install ngrok. +2. Update (or verify) your project configuration. In the `config` folder, open `webpack.config.js` and look for the `devServer` object. Add (or verify) ngrok as an `allowedHost`: +```javascript +devServer: { + // ... existing config + allowedHosts: ['.ngrok-free.dev'] +} ``` - -There should be some logs that list a series of local URLs like: -```sh -Available on: - http://127.0.0.1:8080 - http://192.168.20.43:8080 - http://172.29.29.159:8080 +3. `cd` to the project root and run `npm install`. Run `npm run serve` to run the local development server. +4. Open a seperate terminal window and run the following command (in most cases, `[port]` will be `8080`) +```bash +ngrok http [port] ``` -:::note -The first IP address listed is `127.0.0.1:8080` (which is the loopback device aka "localhost") and your mobile phone won't be able to connect to that IP address directly. Please use one of the other IP addresses. -::: - -Window users need to run the http-server command using a standard Command Prompt window (cmd.exe). The script may generate errors if run from PowerShell. +In the output you should see an ngrok URL that uses HTTPS and forwards to your local development server. You can paste this into your browser window and test your project on a mobile device. -Learn more in the [http-server documentation](https://github.com/http-party/http-server#tlsssl). +![](/images/getting-started/ngrok-terminal.png) diff --git a/docs/getting-started/testing.md b/docs/getting-started/testing.md index 5035f18..7a3d599 100644 --- a/docs/getting-started/testing.md +++ b/docs/getting-started/testing.md @@ -16,11 +16,28 @@ sidebar_position: 6 To test your project on mobile devices, especially for AR experiences that require camera access, you'll need to serve your development server over HTTPS. We recommend using [ngrok](https://ngrok.com/) to create a secure tunnel to your local server. -After setting up ngrok, add the following configuration to `config/webpack.config.js` under the `devServer` section: - +1. Go to [ngrok.com](https://ngrok.com/) and create an account. Once signed in, follow the steps on the dashboard to install ngrok. +2. Update (or verify) your project configuration. In the `config` folder, open `webpack.config.js` and look for the `devServer` object. Add (or verify) ngrok as an `allowedHost`: ```javascript devServer: { // ... existing config allowedHosts: ['.ngrok-free.dev'] } ``` +3. Relaunch the desktop app or exit/reopen the project to refresh the build after updating the webpack configuration +4. Open the Simulator/Preview and click the browser pop-out button + +![DesktopPopout](/images/getting-started/desktop-pop-out.png) + +5. From the new browser window, copy the port number appended to the end of the localhost URL + +![SimulatorPort](/images/getting-started/simulator-port.png) + +4. Open a terminal window and run the following command, replacing [port] with the port obtained from the simulator browser pop-out +```bash +ngrok http [port] +``` + +In the output you should see an ngrok URL that uses HTTPS and forwards to your local development server. You can paste this into your browser window and test your project on a mobile device. + +![](/images/getting-started/ngrok-terminal.png) diff --git a/static/images/getting-started/ngrok-terminal.png b/static/images/getting-started/ngrok-terminal.png new file mode 100644 index 0000000..c1a3e24 Binary files /dev/null and b/static/images/getting-started/ngrok-terminal.png differ diff --git a/static/images/getting-started/simulator-port.png b/static/images/getting-started/simulator-port.png new file mode 100644 index 0000000..a68ae9f Binary files /dev/null and b/static/images/getting-started/simulator-port.png differ