How to debug an iOS WebRatio app

by Ombretta Malinverno
17,411 views Published on Nov 27, 2017
Applies to: 8.0 or higher
Table of contents

Introduction

WebRatio Mobile Platform lets you build Android and iOS apps that you can test on your mobile device or submit to the Google Play Store or Apple App Store. It is also possible to debug the mobile application to find and solve any issue that may come out during the development. RemoteDebug iOS WebKit Adapter is a third party software that can be used to debug the iOS apps.

This article guides you step by step in the app debug process, showing how to install, configure and use RemoteDebug iOS WebKit Adapter for to test a mobile application generated by WebRatio Mobile Platform.

Prerequisites

  • A device with iOS 8 or higher.

  • The mobile application package installed on your device. To learn how to build your Mobile Project and get the mobile application package refer to Build and Test iOS App.

  • A USB cable to connect the device to the computer.

  • Google Chrome browser.

  • iTunes for debugging iOS apps.

Configure Your Workstation

You must configure your workstation to use WebKit Adapter to debug an iOS application.

Windows

  1. Install the Google Chrome browser. RemoteDebug iOS WebKit Adapter requires the Google Chrome browser to host its Debugger user interface. If your workstation does not have Google Chrome installed, please download the Google Chrome installer and install it before proceeding.
  2. Install the latest release of Apple iTunes. RemoteDebug iOS WebKit Adapter uses a few libraries provided by iTunes to communicate with the iOS devices.
  1. If your workstation does not have iTunes installed, please download iTunes and install and activate it (agree to the license) before proceeding.
  2. Instead, if you have already installed iTunes, update it to the latest version if it is not already.
  1. Install nodejs. Node.js is required to download and install RemoteDebug iOS WebKit Adapter from the command line. If your workstation does not have node.js installed, please install it (download the LTS version) and set the Environment Variables.
  1. Open the Control Panel of your workstation, choose the System > Advanced system settings > Environment Variables and refer to the "User variables for {YOUR USERNAME}" section.
  2. Select PATH and choose to edit it.
  1. If the PATH variable is empty, change it to this: C:\Users\{YOUR USERNAME HERE}\AppData\Roaming\npm;C:\Program Files\nodejs.
  2. If the PATH variable already contains C:\Users\{YOUR USERNAME HERE}\AppData\Roaming\npm, append the following right after: ;C:\Program Files\nodejs.
  3. If the PATH variable contains information, but nothing regarding npm, append this to the end of the PATH: ;C:\Users\{YOUR USERNAME HERE}\AppData\Roaming\npm;C:\Program Files\nodejs.
  1. Install the latest version of the RemoteDebug iOS WebKit Adapter. Using the command prompt execute the npm install remotedebug-ios-webkit-adapter -g command with Administrator privileges.
  2. Download iOS WebKit Debug Proxy. The ios_webkit_debug_proxy proxies allow developers to inspect Safari and UIWebViews (a view that embeds Web content in your app) on real and simulated iOS devices via the DevTools UI and WebKit Remote Debugging Protocol.
  1. Download the latest release "ios-webkit-debug-proxy-1.8-x64-bin.zip" file using this link that contains the executable file to run the proxy.
  2. Unzip the file in the following directory C:\Users\{YOUR USERNAME HERE}\AppData\Roaming\npm\node_modules\remotedebug-ios-webkit-adapter\node_modules\vs-libimobile\ios-webkit-debug-proxy-1.8-win64-bin.
  3. Edit the file C:\Users\{YOUR USERNAME HERE}\AppData\Roaming\npm\node_modules\remotedebug-ios-webkit-adapter\out\adapters\iosAdapter.js.
    On line 132, it reads:
    const proxy = path.resolve(__dirname, '../../node_modules/vs-libimobile/lib/ios_webkit_debug_proxy.exe');
    Change this location to point to the location of the "ios_webkit_debug_proxy.exe" you unzipped earkuer. I changed this line to say:
    const proxy = path.resolve(__dirname, '../../node_modules/vs-libimobile/ios-webkit-debug-proxy-1.8-win64-bin/ios_webkit_debug_proxy.exe');
  1. Restart the workstation to confirm the installations.

Linux (tested with Ubuntu 17.04)

  1. Install the Playonlinux program. This allows for installing the iTunes program. Using the terminal, execute sudo apt-get install playonlinux command.
    NOTE. It may require the sudo dpkg --configure -a command, and an update of the packages; in this case, use sudo apt-get update command.
  2. Install the Wine software. It is a compatibility layer capable of running Windows applications on Linux. Run the Playonlinux program; from the menu, select Tools and then "Manage wine versions" option. Choose the stable version 2.17 x86 and install it.
  3. Install the latest version of iTunes for Windows (32 bit). Using the Playonlinux program again, find and run the installation of the iTunes. During the procedure:
  1. It will be indicated to download the 64bit version of Wine, but go on by pressing the Next button.
  2. Later, the installer of iTunes 32 bit will be prompted (download it from the website) and select the zip when it is needed.
NOTE. Ignore the error:
Error in POL_Wine
Wine seems to have crashed
If your program is running, just ignore this message

And do not send the bug report.
  1. Install iOS WebKit Debug Proxy. The ios_webkit_debug_proxy proxies allows developers to inspect MobileSafari and UIWebViews (a view that embeds Web content in your app) on real and simulated iOS devices via the DevTools UI and WebKit Remote Debugging Protocol. Using the terminal, execute:
  1. sudo apt-get install autoconf automake libusb-dev libusb-1.0-0-dev libplist-dev libplist++-dev usbmuxd libtool libimobiledevice-dev
  2. git clone https://github.com/google/ios-webkit-debug-proxy.git
    NOTE. It may require git; to install it, use sudo apt install git
  3. cd ios-webkit-debug-proxy
  4. ./autogen.sh
  5. make
  6. sudo make install
  1. Install python dev. It is required to install the "libimobiledevice" from the command line. Using terminal execute sudo apt-get install python2.7-dev .
  2. Install openssl. It is required to install the "libimobiledevice" from the command line. Using terminal execute sudo apt-get install openssl .
  3. Install libssl-dev. It is required to install the "libimobiledevice" from the command line. Using terminal execute sudo apt-get install libssl-dev .
  4. Install libimobiledevice. Download the zip file from this website; unzip it in a temporary folder and access the inside of it with the terminal. Execute the following commands:
  1. ./autogen.sh
  2. make
  3. sudo make install
  1. Install the Google Chrome browser. RemoteDebug iOS WebKit Adapter requires the Google Chrome browser to host its Debugger user interface.
  1. Go to the Google Chrome website and download the ".deb" package. 
  2. Decompress the package to install "gdebi", executing sudo apt-get install gdebi command.
  3. Open the ".deb" package with another program, selecting "gdebi", and install Google Chrome.
  1. Install nodejs. Node.js is required to download and install RemoteDebug iOS WebKit Adapter from the command line. If your workstation does not have node.js installed, please install it by executing sudo apt-get install nodejs-legacy command.
  2. Install npm. It is required to download and install RemoteDebug iOS WebKit Adapter from the command line. If your workstation does not have npm installed, please install it by executing sudo apt install npm command.
  3. Install the latest version of the RemoteDebug iOS WebKit Adapter. Execute the sudo npm install remotedebug-ios-webkit-adapter –g command.

Configure Your iOS Device

Your Apple device must have the iOS Safari Webkit debugging setting enabled.

  1. On your iOS device, open the Settings app.
  2. Scroll down, and select Safari.
  3. Select the Advanced option.
  4. Enable the Web Inspector.

Debug an App on your device Using RemoteDebug iOS WebKit Adapter

Let’s use the Warehouse Manager App available on the WebRatio Add-ons as a case study for the mobile application debug. What you need to do is to download and create a debug build of the project for your device and install the mobile application.

  1. Connect the device through the USB cable to the computer and then authorize the debug from the device and from iTunes.
  2. Launch the proxy with the executable file present in the path "C:\Users\{CURRENT USER}\AppData\Roaming\npm\node_modules\remotedebug-ios-webkit-adapter\node_modules\vs-libimobile\ios-webkit-debug-proxy-1.8-win64-bin" (for Windows) or open the terminal and execute the ios_webkit_debug_proxy to start the debug (for Linux). When the device is detected, the console will display the listening port for that device (e.g. 9222).

  1. Open another command prompt as the current user; go to the "npm" folder present in the path "C:\Users\{CURRENT USER}\AppData\Roaming\npm" and execute the remotedebug_ios_webkit_adapter --port=9000 command.

  1. Open the Google Chrome browser and go to the chrome://inspect page. Add localhost:9000 and localhost:9222 in the configuration of the "Discover network targets" to listen to them.

  1. Open a new browser tab and open localhost:9000. A message like this is shown:
    {“msg”: “Hello from RemoteDebug iOS WebKit Adapter”}
  2. Open localhost:9221 to see if the device is correctly found.
  1. Go back on chrome://inspect page, and the device is detected.
  2. Open the Safari browser to any website (e.g. www.google.com) on a device to test whether the configuration is correct. The visited page should appear on the list.
  3. Click on the inspect link, and the inspection console will open. If the debug works properly, you should see and inspect the page in the opened console.
 
  1. Now you can open the app that you want to debug. When it is detected, click on the inspect link and start to debug the app.
 
 
Now you can see the same screen of the mobile application visible on the device, and you can use the same debugging tools that are used for debugging with the emulator:
 
  • Elements
  • Console
  • Sources
  • Network
  • Application