Pitcher JavaScript Platform

# Ti-web

Ti-web is a node.js app for Mac OSX, that facilitates the development of Pitcher Impact "interactives" inside web browsers.
Some of the main advantages are:

  • Test responsive layouts
  • Hot reloading
  • Easier debugging by leveraging modern browsers' dev tools
  • Test web app in multiple browser engines
  • Develop an interactive without a iOS simulator available

NOTE

Currently ti-web supports only iOS mode in which only a small subset of native responses is implemented

# How does it work

Pitcher interactives, when running on the device, communicate with the native application layer using Ti: a globally exposed js API. This communication is done via events using the Ti.App.fireEvent command. When Ti receives an event, it usually responds back with some data, either from the locally stored SQLite DBs or the locally stored .json files etc. Ti-web simulates the Ti layer's responses so that interactive development and debugging can be performed in a web browser.

Ti-web consists of 3 parts:


# ti-web-files folder

All files needed for Ti-web to function are stored inside a special folder named ti-web-files.
The ti-web-files folder gets created the first time you run ti-web. This folder contains a copy of:

  • the Pitcher SQLite DB
  • the current instance's SQLite DB
  • the current instance's config.json file
  • other .json files relevant for the current instance

The folder contents are populated automatically when running the ti-web-collect-ios command

# ti-web.js

The ti-web script is responsible for intercepting the Ti.App.fireEvent calls and redirecting them to an express.js web server that's running in the background. It does so by following a naming conversion convention: Ti events are converted to kebab-case and are forwarded to the equivalent end-point on the express server as a POST request. E.g a call to Ti.fireEvent('dbFunction', { ...data }) is converted to an http://localhost:8000/db-function POST request with the data appended as the request's body. It also contains the functionality for redirecting fetch requests of .json files to the ti-web-files folder.

# express.js web server

The express webserver is the "heart" of Ti-web, it listens to port 8000, and it's responsible of responding to the calls received from the "frontend" side. It exposes a series of endpoints, each one of them dedicated to a specific Ti.App.fireEvent command.

# Supported Ti.fireEvent events

# Other supported operations

  • Downloading of instance's .json files via fetch requests.

# Setup ti-web for new a project

  • Run npm install --save-dev @pitcher/ti-web

  • Add the following section to .gitignore

# ti-web
ti-web-files
  • Add the following lines into package.json scripts entries
"scripts": {
  ...
  "ti-web:serve": "ti-web",
  "ti-web:collect-ios": "ti-web-collect-ios"
}
  • Add a proxy attribute to the devServer entry in vue.config.js
devServer: {
  ...
  proxy: {
    // Proxy all requests to ti-web
    '/': { target: 'http://localhost:8000' }
  }
}
  • Create a new file ti-web.config.json inside the project's root folder. ti-web.config.json contains the configuration of the interactive.
Property Description Required
configFileId The project's Pitcher Zero Config json file id Yes
userId The id of the applications's user Yes
interactiveFileID The id of the applications's interactive (the one used for kudu deploys) No
accountId The id of the applications's account No
language The language of the application Yes
iosSimulatorPath The path of the iOS simulator files No
instanceDbName The name of the instance DB No

You can use the following snippet to populate the config. Open the desired instance on the iPad simulator, attach Safari Dev Tools and run it in the JS console. Example config will be copied to your clipboard.

copy(
  JSON.stringify({
    configFileId: (window.serverJSON.files.find((f) => f.vType === 'json' && f.keywords.includes('config')) || {}).ID,
    interactiveFileID: window.serverJSON.appID,
    language: window.serverJSON.config.langV,
    iosSimulatorPath: null, // window.documentPath
    instanceDbName: window.serverJSON.appName,
  })
)

Example ti-web.config.json file:

{
  "configFileId": "977022",
  "interactiveFileID": "945055",
  "userId": "00509000000JCLQAA4",
  "accountId": "00109000003RghEAAS",
  "language": "EN",
  "iosSimulatorPath": "",
  "instanceDbName": "pitcher_apps_development@pitcher.com"
}
  • Open the entry point of the interactive, usually that is public/index.html, and add the following inside the <head> tag, preferably at the top.
<script src="http://localhost:8000/ti-web.js"></script>

An additional data-user-agent attribute can be passed to the script tag.
This is used internally by the ti-web.js script to impersonate a different browser agent.
Possible values can be for example: iPhone, windows, android etc.

If the value emulate-ios is passed to the data-user-agent attribute, then the browser agent is set to iOS thus allowing, in conjunction with Vue SDK, testing in other browsers (e.g IE11).

NOTE

This mode should not be used as an IE11 testing replacement, but only for troubleshooting common/basic IE11 problems such as UI issues (CSS etc), build issues, polyfill issues, library compatibility issues etc.

Example:

<script data-user-agent="emulate-ios" src="http://localhost:8000/ti-web.js"></script>

# Run ti-web

NOTE

In order to be able to download the project's Pitcher Zero Config .json file you must have kudu installed.
If you don't have kudu installed you can follow the instructions here.

  • Start the project's development build, usually this is npm run serve

  • In a new terminal start ti-web

npm run ti-web:collect-ios

and

npm run ti-web:serve

NOTE

When you want to view the interactive as another user or account, you'll have to also update the relevant entries inside the ti-web.config.json file.

← Kudu →