Refer to unicef/projectconnect-app for an overview.
This webapp is built using Next.js as a React Framework and deployed using Vercel.
pages/_app.js
is the application entry point:- Imports the default Bootstrap stylesheet, and additional styles found in
styles/global.css
- Wraps the application in a
<CookieProvider>
to make available react-cookie throughout the code.
- Imports the default Bootstrap stylesheet, and additional styles found in
pages/index.js
is the first page to load, which importscomponents/intro.js
:- Landing page includes static content
- links to
pages/start-test.js
andpages/tips.js
- Includes FAQ as a Bootstrap accordion.
pages/tips.js
is primarily static content, pulling images frompublic/tips/
pages/start-test.js
is also mostly static content that directs users topages/test.js
orpages/mapping.js
pages/mapping.js
contains most of the logic for the application:- Fetches dataset of schools to validate from API endpoint:
pages/api/getLocations/[uuid].js
- Sets cookie, and adds user to Database (
pages/api/addUser.js
), if cookie is not set - Presents data through frontend, by calling `components/quiz.js
- Stores user response through API endpoint:
pages/api/validateLocation.js
- Upon completion, redirects user to
components/result.js
- Fetches dataset of schools to validate from API endpoint:
pages/test.js
is a simplified version ofpages/mapping.js
that instead of pulling data from the database, it pulls local data frompages/api/quizQuestions.js
and does not store any of the user answers. It callscomponents/quizTest.js
, analogous tocomponents/quiz.js
components/quiz.js
iterates through the dataset prompting the user to respond to each location. It calls thecomponent/mapComponent.js
to render the actual map using Mapbox as the provider through react-mapbox-gl as bindings for mapbox-gl
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 campaignusers
: The targeted number of users to register and participate throughout the campaigntaggings
: The targeted number of location taggings that the campaign aims to reach
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:
- 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 itcountryCodes.json
. - From the root directory, run
node scripts/createCountryCodesJson.js
to run the script that creates the JSON file the game requires and places it indata/
. - Verify that the JSON file
countries.json
exists insidedata/
and it is in the format:
{
"Country code": "Country name",
...
}
Setup your development environment as follows:
- Clone this repo:
- SSL:
git clone [email protected]:lacabra/proco-map-app.git
- HTTPS:
git clone https://github.com/lacabra/proco-map-app.git
- Install project dependencies:
cd proco-map-app npm install
- Set up your local Postgres Database and configure the following environment variables in
.env.local
:NEXTAUTH_URL=http://localhost:3000 PGUSER= PGHOST= PGPASSWORD= PGDATABASE=
- 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"
- 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
- Homepage URL:
- RECOMENDED FOR EASIER SETUP: GitHub: Follow these instructions.
- 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.
- Run the developmnet server with fast refresh:
npm run dev
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.
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/>.