/proco-map-app

Crowdsource and gamify the validation of geolocation data for schools around the world.

Primary LanguageJavaScriptGNU General Public License v3.0GPL-3.0

License: GPL v3 Contributor Covenant

ProjectConnect App

Refer to unicef/projectconnect-app for an overview.

🛠 Architecture

This webapp is built using Next.js as a React Framework and deployed using Vercel.

  • pages/_app.js is the application entry point:
    1. Imports the default Bootstrap stylesheet, and additional styles found in styles/global.css
    2. Wraps the application in a <CookieProvider> to make available react-cookie throughout the code.
  • pages/index.js is the first page to load, which imports components/intro.js:
    1. Landing page includes static content
    2. links to pages/start-test.js and pages/tips.js
    3. Includes FAQ as a Bootstrap accordion.
  • pages/tips.js is primarily static content, pulling images from public/tips/
  • pages/start-test.js is also mostly static content that directs users to pages/test.js or pages/mapping.js
  • pages/mapping.js contains most of the logic for the application:
    1. Fetches dataset of schools to validate from API endpoint: pages/api/getLocations/[uuid].js
    2. Sets cookie, and adds user to Database (pages/api/addUser.js), if cookie is not set
    3. Presents data through frontend, by calling `components/quiz.js
    4. Stores user response through API endpoint: pages/api/validateLocation.js
    5. Upon completion, redirects user to components/result.js
  • pages/test.js is a simplified version of pages/mapping.js that instead of pulling data from the database, it pulls local data from pages/api/quizQuestions.js and does not store any of the user answers. It calls components/quizTest.js, analogous to components/quiz.js
  • components/quiz.js iterates through the dataset prompting the user to respond to each location. It calls the component/mapComponent.js to render the actual map using Mapbox as the provider through react-mapbox-gl as bindings for mapbox-gl

👊 Launching a New Campaign

When adding a new campaign for a partner, edit constants/index.js and add a new entry in the dictionary, specifying all three fields, namely:

  • name: The name of the partner or campaign
  • users: The targeted number of users to register and participate throughout the campaign
  • taggings: The targeted number of location taggings that the campaign aims to reach

✏️ Configuration

In order to run this application, you need to set up a Postgres Database and open an account with Mapbox to obtain an Access Token. The following environment variables need to be set in .env or .env.local:

NEXT_PUBLIC_ACCESS_TOKEN="MAPBOX_ACCESS_TOKEN"
PGUSER="POSTGRES_USER"
PGHOST="POSTGRES_HOST"
PGPASSWORD="POSTGRES_PASSWORD"
PGDATABASE="POSTGRES_DATABASE"

To work with the authentication functionalities, you need to add the following entries to the .env or .env.local:

SECRET="A secret to use for key generation"
NEXTAUTH_URL="HOST_URL"
FACEBOOK_ID="YOUR_FACEBOOK_ID"
FACEBOOK_SECRET="YOUR_FACEBOOK_SECRET"
TWITTER_CLIENT_ID="YOUR_TWITTER_CLIENT_ID"
TWITTER_CLIENT_SECRET="YOUR_TWITTER_CLIENT_SECRET"
GOOGLE_CLIENT_ID="YOUR_GOOGLE_CLIENT_ID"
GOOGLE_CLIENT_SECRET="YOUR_GOOGLE_CLIENT_SECRET"
NEXT_PUBLIC_AUTH_CALLBACK="HOST_URL"

To obtain the secrets, contact one of the contributors.

The countries.json is included in this repository to associate country codes with country names. If this file needs to be updated or replaced, follow these instructions:

  1. Download the JSON file of country names and ISO-3166 alpha-2 codes here from Data Hub. Place the JSON file in scripts/ of this repository and call it countryCodes.json.
  2. From the root directory, run node scripts/createCountryCodesJson.js to run the script that creates the JSON file the game requires and places it in data/.
  3. Verify that the JSON file countries.json exists inside data/ and it is in the format:
{
    "Country code": "Country name",
    ...
}

💻 Development Environment

Setup your development environment as follows:

  1. Clone this repo:
    • SSL:
    git clone git@github.com:lacabra/proco-map-app.git
    • HTTPS:
    git clone https://github.com/lacabra/proco-map-app.git
  2. Install project dependencies: 
    cd proco-map-app
npm install
  3. Set up your local Postgres Database and configure the following environment variables in .env.local: 
    NEXTAUTH_URL=http://localhost:3000
PGUSER=
PGHOST=
PGPASSWORD=
PGDATABASE=
  4. Open an account with Mapbox to obtain an Access Token. Add your access token to .env.local: 
    NEXT_PUBLIC_ACCESS_TOKEN="YOUR_MAPBOX_ACCESS_TOKEN"
  5. Optional: If you need to test the user authentication, you will need to set up your own credentials with either one of the OAuth providers:
    • RECOMENDED FOR EASIER SETUP: GitHub: Follow these instructions.
      • Homepage URL: http://localhost:3000
      • Authorization Callback URL: http://localhost:3000/api/auth/callback/github
  6. Optional: you may get a jwt_auto_generated_signing_key warning that you can resolve by following the instructions on that link, or these instructions.
  7. Run the developmnet server with fast refresh: 
    npm run dev

🗄 Data Ingestion

This application expects a CSV file containing the following data about each school:

  • lat
  • lon
  • id
  • country

where the id field must be unique, and the country must be specified with ISO 3166-1 alpha country codes.

Name the file schools.csv and copy it into the scripts/ folder. In that folder run:

node csvToJson.js

The above script will generate a file schools.json that will be ingested by db/dbOps.js.

Note: For testing purposes a sample scripts/schools.json is included in the code repository, which has the same data as the locations used in the practice test, yet in production a different dataset will be used.

📝 License

This software is licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

    ProjectConnect App
    Copyright (C) 2020 UNICEF

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.