codeforboston / plogalong Goto Github PK

License: MIT License

JavaScript 98.61% HTML 1.39%

plogalong's Introduction

Plogalong

Plogalong is an app for iOS and Android designed to encourage new and existing ploggers to record the litter they pick up while walking, running, or exercising outdoors.

This is a project of Code for Boston. If you would like to get involved in helping us develop the app, join us at the next Hack Night, and we can help you get started.

We're in the beginning stages of development, but we have a very detailed Mockup.

Architectural Overview

React-Native + Expo: React Native is built on the same bones as React for web, except that instead of building user interfaces from DOM elements, you use platform-native views (UIViews on iOS, Views on Android). Expo is a managed version of React Native that includes a library of components known to be compatible with each other. It adds some tooling that help in the development cycle.
Redux for managing local state
Database - Firebase
Authentication - Firebase

Setup Instructions

Clone this repository (How To Clone A Git Repository)
Node (10.x or 12.x) -- ensure that you have a recent version installed - https://nodejs.org/en/download/ Please use a LTS (even) version
Make sure that /usr/local/bin is in your $PATH by opening Terminal and typing in echo $PATH (if it's not, follow directions here: https://opensource.com/article/17/6/set-path-linux)
(iOS) Install Xcode This may take a while... why not go plogging for an hour?
...then launch it at least once so that you can agree to its Terms and Conditions.
(Android) Install Android Studio and create a virtual device.

See here for detailed instructions To create a virtual device from the Android welcome screen, click configure>AVD Manager To edit your virtual device selection from somewhere other than the welcome screen, click on the AVD Manager icon in the toolbar on the top right (looks like a phone with a green android alien)
n.b. Since this app will be deployed on the Google Play Store, when creating a virtual device in the AVD Manager, try to choose a device that has the triangular Google Play Store icon next to it. Download an available system image
(Optional) Install yarn: https://yarnpkg.com/lang/en/docs/install/
Install Expo: npm install expo-cli --global or yarn global add expo-cli npm install expo-cli --global)
Configure Firestore connection: create a new file in the firebase/ folder, name it config.js. Add the proper values to firebase/config.js by copying in the new config info (which you can find pinned in the #plogalong Slack channel).
Install node modules: npm install or yarn install
If you need to install an additional dependency, that dependency's documentation may give you instructions for using npm or yarn. If you encounter problems with the npm installation, using the yarn installation might work better. There are also instances when you may need to do npm install after pulling in new changes from the CfB master branch.
If you're planning on running this on an Android simulator, you'll have to install the Expo app via the simulated device's Google Play Store. To do so, open Android Studio, open the AVD Manager (icon looks like a phone with a green Android alien in the top right toolbar), click the Play button under "Actions" to launch the simulator. You can then open the Google Play Store on the simulated device. Now search for the Expo app and install it to the simulated device. You may have to launch the simulator from Android Studio each time you want to run the app via Expo.
In a terminal window, navigate to the root directory of your local clone of this repository. Type expo start to launch Metro bundler and Expo's browser-based developer tools.
While Expo runs, you can type i to run the app in the iOS simulator. In order to use the Android emulator, launch the Android Virtual Device emulator via Android studio (described above), then type a at the terminal to run the app in the Android emulator. You can also use Expo's local web interface to launch the app.

If you type 'i' and get an error, run 'sudo xcode-select -s /Applications/Xcode.app'
To run Plogalong on an iOS device:
1. Install Expo on your iOS device from the App Store.
2. Connect both your computer and your iOS device with same Wi-Fi.
3. In Expo XDE in your browser, select Connection > LAN
4. Use the Camera App on your iOS (iOS 11+)Device or any QR code reader (iOS 9 & 10) to scan the QR Code.
5. Your QR code reader / Camera App, will ask if you want to launch the App in Expo Client App, select "Yes"
6. Plogalong should load accordingly
To run Plogalong on an Android device:
1. Install Expo on your Android device from the Google play store.
2. In Expo XDE in your browser, select Connection > Tunnel. Wait for a new link and QR code to generate below the connection options, and then click on the link to copy it to your clipboard.
3. Open Expo on your Android device. If you are on an emulated Android device, then select Open from Clipboard. Otherwise, select Scan QR Code.
4. There should be a message saying 'Building JavaScript Bundle as the Application loads.
5. Boom! You're ready to Plog.

API Keys

Firebase

Using the shared Firebase project

Check on our Slack channel for the shared configuration file. Save it to firebase/config.js.

Setting up your own Firebase project

Install Firebase CLI: npm install -g firebase-tools
In the firebase/project directory, run firebase login. If prompted, log in to your Firebase account.
Choose the project to use:
- An existing project: Run firebase use --add and follow the prompts. (I use the alias "default".)
- A new project: Run firebase projects:create and follow the prompts
In firebase/project/functions run npm install.
Deploy with firebase deploy. (See firebase deploy --help for additional options.)

Additional setup: see the section on SendGrid below.

Local Configuration

Some Firebase features require additional configuration in the shared app config (app.config.js). When building, you can optionally specify a LOCAL_CONFIG_FILE environment variable. If given, it should be set to the path (relative to the working directory) of a JS module that exports a config object. See app.config.js for the keys you can override.

SendGrid

What it's for: this API is used to send certain transactional emails: for example, user feedback.

Get API Key

Create an account
In the SendGrid dashboard, open API keys
Create a new API key. If you choose to customize the access levels, set "Mail Send" to Full Access.
Copy the API key

Sender Authentication

Open the Sender Authentication page under Settings
Choose "Authenticate Your Domain" and follow the instructions

Configure Firebase

In this repo, cd to firebase/project
Set the email configuration options:

plogalong.sendgrid_api_key=SG.xxxxxxx plogalong.admin_email=xxxxxx

Replace SG.xxxxxxx with the API key you got earlier. The plogalong.admin_email option determines the email address that will receive admin alerts (comment submissions, for instance). It will also be the sender email unless you provide a separate plogalong.sender_email option. In either case, you must complete "Sender Authentication" (above) for the sender domain or address.

OpenWeatherMap (optional)

What it's for: this API is used to populate the Current Weather box on the Plog screen

What to do: Register for a free account on Open Weather. Copy your key from the "API Keys" tab and paste it into the openWeatherMapKey of your config.json file.

Updating

After a pull request is merged, it may specify that node_modules will need to be deleted. When this is the case, delete the node_modules folder on your local repo and execute yarn install in your terminal.
n.b. if you are using npm, execute npm install instead of yarn install
The time may come when you will have to update Expo on your simulator. To do so on the iOS simulator, execute expo client:install:ios in your terminal. If it doesn't take on the first try, try once more. If you're still stuck after two times, consult an expert.

Remote Debugging

Debugging Plogalong should be no different than debugging any other React Native project, but below are some useful tools for your convenience.

Option 1: React-DevTools

If you're already familiar with debugging React web apps via Chrome DevTools, this is pretty similar. The React Native documentation points out that "the React Developer Tools Chrome extension does not work with React Native" and offers a standalone version of React Developer Tools for debugging.

Installation

The steps for installation can be found here.

Option 2: React Native Debugger

Similar to React-DevTools is the React Native Debugger published on GitHub by user jhen0409. This standalone app is based on the DevTools in Option 1 above, but may provide more functionality.

Installation

For installation via Homebrew, you can follow the README instructions.
Otherwise, you can simply download the appropriate prebuild binary from the release page (choose the .dmg file for macOS and .exe for Windows)

Usage

Open React Native Debugger app, and notice that the default port is set to 8081. With this default window open, select Debugger > New Window (or more simply ⌘T or Ctrl+T) to change the port to 19001. Confirm the new packager port.
Fire up the Plogalong app via expo start just like you always do.
Navigate to the Expo Developer Menu with a shake gesture (Ctrl ⌘ Z in an iOS Simulator, Cmd+M in an Android Emulator), and select "Debug Remote JS" from the menu that pops up on the device.
The React Native Debugger should connect and you'll see console.log() statements print in the console, be able to inspect elements by triggering the Expo Developer Menu (shake gesture > Toggle Element Inspector), and set breakpoints in the Debugger by navigating to Sources > Page > RNDebuggerWorker.js
When you're finished, you'll save yourself some trouble the next time you start Plogalong if you remember to "Stop Remote Debugging" via the Expo Developer Menu (shake gesture).

How to Contribute

Join us on the Code for Boston Slack. We're in the #plogalong channel.

plogalong's People

Contributors

Stargazers

Watchers

plogalong's Issues

Plogging Events

Usability testing debrief

Update team on findings from 4 sessions with older users.

Updates from Research

Changes/findings based on 2 moderated usability sessions conducted by Eva on 9/23/2019:

The basic concept of a timer was intuitive/made sense.
In this sessions, users continue to note that it is not clear what the meaning of points is. Therefore, points will be replaced with 'plogging minutes,'
It made sense to users to see the Local page after recoding a plog, but ONLY if their own plog appeared as first in the list. Prototype will be updated accordingly.
Heart icon (updated from leaf) worked better/was intuitive to 4 out of 4 users
Trash type detail worked well in general - one user wanted more detailed list/option to enter text descriptions (for MVP, 'other' will be added to the detailed list; free text entry deferred indefinitely due to moderation not being feasible for foreseeable future). There are clearly two opposite user perspectives that we need to accommodate - those who are detail-oriented and want to record a lot of information, and those who want to focus on the real-world plogging and record quickly.

Changes to MVP (based on 4 moderated remote usability sessions conducted by Corey/Eva):

Timer functionality was added to address the needs of users wanting to 'plog as they go'
Changed default on plog page to 'Misc Trash'
Cut Flagging trash (to be re-envisoned as reporting to 311 in the future)
Removed tabbed nav on Local
Defer follow functionality on local to phase 2
Changed 'leaf' icon to heart (FB like equivalent)
Make sure that the app does not time out if a user starts a plog and then returns after they finished plogging to finish uploading data
Think about refining the trash type nav, and think about localized or seasonal options
on local page, mix in offers with feed instead of separating
on local blank slate, connect achievement with the first plog
think about reordering plog form so photos are first/more prominent

Basic content layouts

Create simple layout for pages that are text only, to be accessible from this page:
https://marvelapp.com/96b0bd4/screen/45307048

They should have a basic back button - like this:
https://marvelapp.com/96b0bd4/screen/53564657

Related Screen(s) and dependent screens
https://marvelapp.com/96b0bd4/screen/45307048

Tasks (to complete this issue)

Create basic layout
implement back button

Tests (acceptance requirements)

Related Issues

Comments

Individual profile

Populate and store individual plogger profile

https://marvelapp.com/96b0bd4/screen/53525464

Related Screen(s) and dependent screens

Tasks (to complete this issue)

Create basic layout
Store/pull data in firebase
Set default username to Local Plogger
Use https://www.dropbox.com/s/dsqtvmqchtc8e7x/avatar.svg?dl=0 as default avatar
Allow user to set profile image and store in Firebase
Auto-populate home location when user hits the location icon

Firebase table:
Users

UserID
Email
UserType (Personal | Group |
Biz)
Alias
HomeLocation
PrivacyShare
PrivacyMarketing
AlertsActivity
AlertsWeather
CreatedDate
SocialConnect (No | FB | Other)
AvatarRef

Tests (acceptance requirements)

Related Issues:

Comments

Populate content for More>About Plogalong

More screen

Lay out screen for more info

Link to related wireframe page
https://marvelapp.com/96b0bd4/screen/45307048

Related Screen(s) and dependent screens
sub-screens

Tasks (to complete this issue)

Layout screen
Implement in-page nav

Tests (acceptance requirements)

Related Issues

Comments

Plog Leaderboard

#label

Prototype screen:
https://marvelapp.com/96b0bd4/screen/53619178

Plog Log Form - take photo

Database

Create DB diagram
Create DB in Firebase
Create sample content

Invite Users

Pretty self-explanatory - should open the appropriate social network. Pre-filled content coming.
https://marvelapp.com/96b0bd4/screen/53524041

Get Photo roll permissions

Currently camera roll will error out if it hasn't been given photo roll permissions

Trash types

Trash type selection has been streamlined.

By default, users are choosing from only 3 options.
But, if they want, they can click report detail.
https://marvelapp.com/96b0bd4/screen/53564903

This will expand the section to show custom trash types and other stuff that can eventually be seasonal and customized.
https://marvelapp.com/96b0bd4/screen/61131926

At thtis point, either clicking Report detail again, or selecting from the main trash types above will close the 'report detail' area and return to default.

If a user reports detail once, expanded view should be stored as their default, so that if they record a new plog, they will see the detailed view.
If they can collapse it back, that flag is reset.

(The logic above assumes that there are some people who will want to report detail most of the time, and others who don't care about it and want to get through form quickly. This interaction allows them to have their preferred view open when they plog).

Invite

I believe the screen is already there, but the buttons are not hooked up.

https://marvelapp.com/96b0bd4/screen/53524041

Photo Spec

Related Screen(s) and dependent screens
Sample photos of trash:
https://www.dropbox.com/sh/u2107zazyv2sdft/AADJYZCinq1jQxN3lW8U132-a?dl=0

Tasks (to complete this issue)

(complete) When user uploads or takes a photo, show in a square 'mask'; allow user to drag photo within the mask (like Instagram, but don't allow anything other than square format)
(?)On the back end, crop and reduce file size to a 'reasonable' file size
(?) Constrain Firebase to only accept photos of a maximum file size
(Eva) Include note in terms and conditions re: taking photos of people, ownership of photos, etc.
(?) On the Plog form, photos should be saved locally even if user closes the app (to allow for taking photos as you plog)
(incomplete) Allow users to click thumbnails and have them open in a modal; modal is not prototyped, but should look like other modals (https://marvelapp.com/96b0bd4/screen/45440813) , with X in upper right. Buttons below photo should be as follows: Close and Report Photo buttons on Local page | Close and Remove Photo button on Plog form or History;
(complete) Photo should be centered vertically within the modal
(incomplete) For MVP, Report photo button should flag photo in firebase, hide it from view automatically, and send an email to [email protected]

Tests (acceptance requirements)

User can take/upload up to 5 photos (complete)
Photos show/are stored in a square format (complete)
User can enlarge their own or others' photos (incomplete)
User can report a photo in the Local feed (incomplete)
User can remove a photo loaded into the Plog form or History (incomplete)

Related Issues

#65 (open)
#49 (needs QA)
#48 (closed)
#83 (open)

Related User Research/Usability Test Findings

Photo upload design was intuitive to participants
Some were more interested/focused on photos than completing other information about their plog

Comments

Style Log button

Button should be green and does not fully span the screen horizontally.

Consider privacy implications of design

User name visibility
Location visibility and granularity -- can we avoid storing precise location data entirely?
- Uses of location: "hyper-local" specials, aggregate
Think about ethics so that the engineers don't have to! (That was a joke.)

Add screener question to respondent

Draft a multi-checkbox question asking participants what kinds of outdoor activities they do regularly (walking, hiking, jogging, etc.)

Time/Location Based Notifications

Weather alert: between 9am and 6pm local time; if it's sunny or partly cloudy and temperature is between 40-75 degrees F

"It's a nice day for a plog!"

Plogging activity alert: someone else has shared a plog with the Local feed within 1 mile radius of user's current location
"Someone else just plogged nearby. Maybe you could too."

https://marvelapp.com/96b0bd4/screen/53525464

Implement svg icons throughout the app

All the icons are here, now organized into relevant sub-folders. This may already be partially implemented, but I know the bottom nav is using some kind of custom/different nav set, so these need to be updated there.

(complete) Plog form activities
https://www.dropbox.com/sh/wrzsq7mntxsny87/AABYEpoKhlYafhidJ3mRvmqqa/plog-activities?dl=0

(complete) Plog form helpers:
https://www.dropbox.com/sh/wrzsq7mntxsny87/AAAWTrOHGlRSVFrNrZly3_KHa/plog-helpers?dl=0

Nav icons
https://www.dropbox.com/sh/wrzsq7mntxsny87/AAAW9XL4kVdP_Jf8HbTx-SOua/nav?dl=0

misc - used within screens (some of these have changed)
https://www.dropbox.com/sh/wrzsq7mntxsny87/AAADx6bxXBTFGFWh92UX_uNya/misc?dl=0

Plogging timer spec

Summary:
Plogging timer will allow users to track their 'plogging minutes.' Plogging minutes will replace the point system as a more intuitive/concrete measure.

UI:
https://marvelapp.com/96b0bd4/screen/53564903
https://marvelapp.com/96b0bd4/screen/61131926

Related Screen(s) and dependent screens
Leaderboard; anywhere points are displayed

Tasks (to complete this issue)

Spec/behavior (Eva - pending)
Timer is optional - users can log a plog without timing themselves if they wish.
Replace points with 'plogging minutes' throughout the UI (Eva)
TBD

Tests (acceptance requirements)

User can start timer
User can stop timer
Timer stops automatically when a plog is logged
'Plogging minutes are recorded when a plog is logged
Time out/stop/notification logic (TBD)

Related Issues
Updates from research:
#58

Relevant user perspective(s):
'Plog-as you go'
"I want to start a plogging session and take photos as I go."
'Gamer'
"Earning rewards and competing with others motivates me to keep going.'

Supporting User Research/Testing:

In initial testing through 9/23, we identified a subset of potential users who wanted to record their plogging session/take photos, as opposed to plogging first and then take pictures/log. Users of other tracking apps (e.g. Strava) expected some kind of tracking to be part of the app.
The timer button concept was intuitive to 2 users in sessions conducted on 9/23/19.

Plog Log Form - Change map location

https://marvelapp.com/96b0bd4/screen/53564903
Ideally, the user should be able to drag/drop the detected location.
For MVP, users MUST agree to share location to use the app. If user has chosen not to share location, pop up location sharing when they hit the plog page.

Re: privacy:
Share plog data/location 5 minutes after user submits their plog. User can choose not to share their plog in the local feed or facebook, therefore protecting their privacy.

Draft respondent project pitch

Log into respondent and see project draft

Plog History - All

This is the Plog Log on the Local screen.
By default, it should show the 5 most recent, closest plogs, then infinite scroll into 5 more, etc. Blank slate will show if there is no other plogs within 5 miles of the user's current location.
https://marvelapp.com/96b0bd4/screen/45305403

Give more priority to photos

- Move the photo area up, right below the map
- Reduce size of camera icons slightly, while keeping the green outline the same size (the icons are just a bit too large relative to the other icons on the page
- Increase the size of the thumbnails so that the width fits the horizontal viewport with a bit of padding in between. Right now the thumbnails are static and too small.
- Change behavior so that whichever 'camera icon' the user clicks, the photo is loaded into the next available box... If I load a first photo, it is always loaded into the first thumbnail, second photo into second, etc.

https://marvelapp.com/96b0bd4/screen/61131926

Investigate Unmoderated user research capabilities for mobile testing

In preparation for research with older users.

Solved: Lookback.io works

Implement SegmentedControl for Android

The SegmentedControl component is currently little more than a thin wrapper around SegmentedControlIOS. The Android implementation does not need to reproduce all of the iOS features, only the ones we're using.

At minimum, it should:

Accept the props: selectedIndex (an integer), values (an array of tab names to display), and onChange (a callback that expects an index integer)
Allow only one tab to be selected at a time
Use the standard colors from ./constants/Colors.js

Implement 'filmstrip' UI

Outstanding Tweak:

Hide the horizontal scroll bar that appears when user swipes across achievements.

A filmstrip is a row of photos or icons that are arranged horizontally and can be swiped through. There are two instances of film strip in the app:

on the plog form, the activities the user is doing while plogging don't fit within the horizontal viewport on smaller screens. If this happens, user should be able to swipe to the remaining icons.
https://marvelapp.com/96b0bd4/screen/53564903
https://marvelapp.com/96b0bd4/screen/61131926
On the History screen, as soon as the user has several achievements, they will no longer fit in viewport. https://marvelapp.com/96b0bd4/screen/45307708

important: to provide affordance (a hint that it's swipable), one icon/element should always show partially on the right side of the screen. Otherwise the user will not realize that they can interact with the film strip.

Add Android Device Directions to README.md

Figure out how to run the app via Expo on an actual Android device and record the process in the README.md

comment out 'Flag' nav

Comment out the flag nav on the plog form. It is being deferred to a future release.

https://marvelapp.com/96b0bd4/screen/53564903

Plog Log Form - pull current location

Display current weather on Plog Screen

Bottom tab bar - Selected/Unselected state

Use the following icons for the bottom nav strip.
https://www.dropbox.com/sh/d37df11myevi22z/AACzlJpQfKGknNaHEvfYtNola?dl=0

Set unselected to dark gray #666666
Set selected (current page) to purple #966dd0

Related issue: #50

Location marker

Add location marker above map

Options could be:
Street Name (e.g. Plogging a street)
Park or natural area name (e.g. Plogging a park, Plogging a beach, Plogging a golf course)

We will need to pull the name of this marker from maps, and store it with the plog data.
The marker name should be displayed on the history page and local feed instead of latitude

https://marvelapp.com/96b0bd4/screen/53564903
https://marvelapp.com/96b0bd4/screen/45307708

Plog data into Firebase

I generated some test content, plus tables of data for form elements that can be sorted by ID.
I included a toggle for each item so that it can be shown or hidden as needed).

https://www.dropbox.com/sh/msmb6vn8h8x4uqi/AACuGRYDQ1QODdxtsfPb9c8ja?dl=0

Stay tuned for more data re: achievements etc.

Google interest form into Airtable

Use Zapier to add people who complete interest form to Airtable automatically.

Plog Submission Notification Popup

Passwordless auth

Implement passwordless auth using https://auth0.com/passwordless

This is a nice to have for MVP, but would be amazing to have out of the gate.
It's free for up to 7000 users.

Plog Log Form

Short Description

Link to related wireframe page
https://marvelapp.com/96b0bd4/screen/53564903

Related Screen(s) and dependent screens

Tasks

Tests (acceptance requirements)

Related Issues

Comments

Issue Template (Copy when creating a new issue!)

Short Description

Link to related wireframe page
https://marvelapp.com/96b0bd4/screen/53564903

Related Screen(s) and dependent screens

Tasks (to complete this issue)

Logic/UI Behavior

Tests (acceptance requirements)

Related Issues

Related User Research/Usability Test Findings

Comments

Plog Badges

https://marvelapp.com/96b0bd4/screen/53618667
As user achieves badges, they turn from b&w to color.
Clicking on an achieved badge brings up the achievement unlocked modal - https://marvelapp.com/96b0bd4/screen/45978632
For MVP, grayed out badges are not clickable