citydna-app-townhall-experience

This is the experience run on the 3D model/led screen in the north wing of the town hall commons space. It's final production build is a react component not a react app that is deployed and served.

Usage no npm install needed!

<script type="module">
  import citydnaAppTownhallExperience from 'https://cdn.skypack.dev/citydna-app-townhall-experience';
</script>

README

citydna-app-townhall-experience

This is the experience run on the 3D model/led screen in the north wing of the town hall commons space. It's final production build is a react component not a react app that is deployed and served.

Instead, the final build is a UMD package that's published to NPM. From there, the platform-host-app consumes the package and side-loads the code in at runtime.

It's important to remember when developing this app that it's just loaded in like a component within the platform-host-app, so any context, theming, etc will influence the final output. This is intentional and allows for rapidly building websocket enabled experiences.

Contents

There are three components that get built for the production package in this app:

  • Settings
  • Screen
  • Projection

Each of these can be considered their own 'mini app' and are loaded onto one device at a time. For example, the Settings are automatically loaded onto a controller iPad (CONTROLLER device type), the Screen is loaded onto the large LED screen in the THC space (SCREEN device type, allocated via platform-host-app) and Projection is loaded onto the projector in the THC space (SCREEN device type, allocated via platform-host-app).

All of these apps communicate via websockets through the @citydna/platform package.

General user flow

The initial cut of this app is pretty rudimentary.

  1. A user can scan the QR code on their mobile device
  2. They are directed to the citydna-app-townhall-public live URL along with some parameters from the QR code (information such as auth token, websocket channel to join, which experience to display and which stack to connect to)
  3. The public app anonymously authenticates their pusher websocket client (via the authenticatepusherpublic lambda from the Amplify API, in platform-admin).
  4. Once authenticated their avatar will display on screen, matching the avatar they've been assigned in the citydna-app-townhall-public app.
  5. The user can then browse around content on their phone and load up a larger preview onto the screen by adding it to the tour.
  6. When the user's content is up in the queue, they are notified and the on-screen map flies to the property they've loaded up. It's also highlighted in magenta on the 3D model via the projector.

Custom layers - CLUE, Tree canopies, etc

Custom, citywide layers similar to have not been built in yet, though the code has been scaffolded in:

  • src/led-screen/CardStack.tsx:78-88,138-140,202
  • src/projection/StopsProvider.tsx:34:48
  • src/projection/Map.tsx:40,51

I saw this being built as following:

  1. Custom code for custom layers is exported in ./src/custom-layers that exports an object like:
{
  CUSTOM_LAYER_ID: {
    led: LedReactComponent,
    model: ModelReactComponent,
    modelViewport: {...} // ArcGIS viewport
  }
}
  1. When a card comes up that has a customLayerId attribute - via the useCardStack onEnter option - it'd set in local state the relevant component in state (in both the Model and the Projection components) by accessing the custom_layer_object[CUSTOM_LAYER_ID].model
  2. Setting the component in state will cause it to render, running the useEffect cycles outlined in the LedReactComponent and ModelReactComponent
  3. Unset the local state component in the useCardStack onLeave option

Within the LedReactComponent and ModelReactComponent you have access to the ArcGIS view object (for the model) and the useMapboxRef/useDeckGL hooks in the projection, allowing you to do pretty much anything.

The custom layer pins would show up on the public facing app by adding them to the FOI_CITYDNA_CustomLayers FeatureCollection in the arcgis-editor. You'd also have to add the resource to the citydna config json file in S3.

As mentioned though, this is incomplete and untested.

Development

The @citydna/platform exposes a helper component called AppPreview that helps you rapidly create apps for the platform. It's a development environment only and is not intended for production use. When you run yarn start for development, the 'app' will load up an instance of this and mock the devices. Read more.

Common components/code between this experience and the citydna-app-townhall-map have been abstracted out into a special @citydna/experience package for code reusability.

.env file

You'll have to create a .env file in the root of this app that has the following variables:

  • REACT_APP_AMPLIFY_USERNAME - amplify login username
  • REACT_APP_AMPLIFY_PASSWORD - amplify login password
  • PUBLIC_URL - public app URL
  • REACT_APP_QR_ORIGIN - public app URL
  • REACT_APP_MAPBOX_API_ACCESS_TOKEN - mapbox token

Scripts

  • yarn start - enter local development mode.
  • yarn start:dev - enter remote development mode. This will build your app using webpack and serve the resulting package at a public URL.
  • yarn build:app - create a package via webpack ready for distribution to NPM
  • yarn publish - publish the app to NPM (after running yarn build:app).

Config

Config for the apps are stored in the citydna-configs-bucket. These control things such as;

  • what data/resources are displayed and used
  • copy & translations for the apps, as well as custom images
  • how the app displays on the user's phone

A local copy of these is kept in /apps/citydna-app-townhall-public/public/config.