@citydna/platform

The official SDK for creating apps for the Melbourne CityDNA platform.

Ecosystem

Works great with @citydna/common (branded component library), @citydna/maps (mapping components) and the @material-ui/core package for all your other UI needs. We've chosen to enforce typescript to avoid common mistakes, however, these packages can be used without it.

Installation

This package must be used in conjunction with react, you can install it by running the following command.

$ yarn add @citydna/platform

API

AppContext

This provides injected miniapps with runtime configuration, this is rarely needed and is only kept for legacy purposes.

AppContextProvider

Used to provide values globally to your app. The value you provide to the context is not restricted, it can be anything you're injected app requires.

import { AppContextProvider } from '@citydna/platform`

export const RunningApp = () => {

  return (
    <AppContextProvider value={{appId: ""}}>
      <RunningApp/>
    </AppContextProvider>
  )
}

useApp

Hook to access the value from the provider.

import { useApp } from "@citydna/platform"

export const App = () => {
  const value = useApp()
  return <>{value}</>
}

AppEnvironmentContext

This is a crucial part of the platform, this allows a container application such as the platform host app, to pass through environment specific variables. This is to remove any environment variables from common packages and inject applications.

AppEnvironmentContextProvider

Provider to use to feed in environment variables, this is to avoid using environment variables in packages that are deployed to public places such as NPM.

// platform-host-app/src/RunningApp.tsx
import { AppEnvironmentContextProvider } from '@citydna/platform`

export const RunningApp = () => {

  return (
    <AppEnvironmentContextProvider value={{baseMapUrl: process.env.BASE_MAP_URL}}>
      <RunningApp/>
    </AppEnvironmentContextProvider>
  )
}

useAppEnvironment

Hook to access the value from the provider.

// some-experience-application/App.tsx
import { useApp } from "@citydna/platform"

export const App = () => {
  const { baseMap } = useAppEnvironment()
  return <Map url={baseMap} />
}

AuthProvider

Collection of wrappers around AWS Amplify.

AuthenticationContextProvider

Provides your app with context of a variety of functions, described below.

useAuth

Used to access the following functions:

• signIn
• signOut
• forgotPassword
• changePassword
• completeNewPassword

UserContextProvider

This stores the AWS cognito user object, it has vital information about the currently logged in user.

useUser

Get access to the user, will be undefined if no one is logged in.

import { useUser } from "@citydna/platform"

export const App = () => {
  const user = useUser()
  return <>{user.firstName}</>
}

RoomProvider & PublicRoomProvider

These two components provide similar functionality, they give you access to the pusher room and allow socket communication between clients. They have the same API in fact, they differ in that the PublicRoomProvider allows for restrictions to be in place for the user.

All the functionality provided uitlise pusher, which is a SAAS for websocket communication. It uses presence channels which require each client to be authenticated.

RoomProvider

This is a provider which should be wrapped around your application. It allows access to the pusher instance. It requires a name for the channel you want to connect to.

PublicRoomProvider

This is identical to the above RoomProvider, but allows you pass through certain control mechanisms. These can be obtained by using the useControls() hook below.

Controls passed through:

• emitLimit - number of emits allowed for the user
• emitLimitResetTime - when the above limit should be reset

useRoom

It's best to avoid using this hook, instead use useCurrentRoom() as described below.

useCurrentRoom

This hook returns you a set of functions that you can use to emit and receive events. This

// src/Controller.citydna.tsx
import React from "react"
import { useCurrentRoom } from "@citydna/platform"

const MyControllerComponent = () => {
  // 1. grab the emit function
  const { emit } = useCurrentRoom()

  // 2. set up your event handler
  const sendEventToScreen = () => emit("my-event", "Hello world")

  // 3. use your event handler.
  return <button onClick={sendEventToScreen}>Send event to screen</button>
}

export default MyControllerComponent

// src/Screen.citydna.tsx
import React from "react"
import { CityDNAComponent, useCurrentRoom } from "@citydna/platform"

const MyScreenComponent: CityDNAComponent = () => {
  // 1. get event listener hook
  const { useEvent } = useCurrentRoom()

  // 2. use it to respond to events
  useEvent("my-event", (data) => {
    console.log(data) // => "Hello World"
  })

  return <>I am the screen!</>
}

hooks

useControls

This hook wraps graphql calls to fetch controls based on the appId. You can then pass it through to the PublicRoomProvider to provide control measures for public users.

useWaitingRoom

This hooks allows you to control how many users are in a space, it does this through pusher events. Currently this only works with the public app, with logic to respond to the pusher events.

The hook returns a list of devices that are in the room, based on the roomCapacity.