A minimal implementation of a Node.js tracking pixel API backed by a MongoDB database. This API is not production ready and is for learning purposes only.
Use correct Node version (see .nvmrc
) and install packages:
nvm use
# Check you have the node version specified in .nvmrc
node --version
npm install
Run with the in-memory database mongodb-memory-server:
MONGODB_MEMORY_SERVER=true npm run dev
If you have MongoDB installed you can use that instead (the env var MONGO_URL
defaults to mongodb://127.0.0.1:27017/tracking-pixel
):
MONGODB_MEMORY_SERVER=false npm run dev
For local development you can keep environment variables in .env
:
cp .env.example .env
There are unit tests (test:unit
) and integration tests (test:integration
) and npm test
will run both of them:
npm test
The integration tests will start the server with the mongodb-memory-server
and make various HTTP requests against the API.
The track endpoint will read the url
from the Referer
header and the userId
from the _track
cookie (if the cookie is not present then a Set-Cookie
response header is issued) and store the request in the MongoDB database.
# First visit without cookie:
curl -i -o - -H 'Referer: http://localhost:8080/test/contact.html' http://localhost:3000/track
# Set-Cookie: _track=ce3be6d4-cc1d-4375-89a6-7da37ae5646f; Max-Age=43200; Path=/; Expires=Sat, 25 Jun 2022 02:31:06 GMT; HttpOnly
# Repeat visit with cookie:
curl -i -o - -H 'Referer: http://localhost:8080/test/contact.html' --cookie "_track=ce3be6d4-cc1d-4375-89a6-7da37ae5646f" -o /dev/null http://localhost:3000/track
The /trackingReport
endpoint gives you number of pageViews
and visitors
by url
for a given time range. The result is sorted by pageViews
in descending order with a limit of a 100 items.
# Time range of one day
curl "http://localhost:3000/trackingReport?from=2022-06-24&to=2022-06-25" | jq .
# Time range of one minute
curl "http://localhost:3000/trackingReport?from=2022-06-24T20:16:00.000Z&to=2022-06-24T20:17:00.000Z" | jq .
There is a CLI script (built with the Commander
package) you can use to get a CSV report from the /trackingReport
endpoint (--baseUrl
defaults to http://localhost:3000
):
# Show usage
./cli trackingReport --help
# Get report from local server
./cli trackingReport --from 2022-06-26 --to 2022-06-27
# Get report from production server
./cli trackingReport --from 2022-06-26 --to 2022-06-27 --baseUrl https://url.of.production.tracking.api
Show listing of recent tracking events in the database (intended for development only):
curl http://localhost:3000/trackingEvents | jq .
There are two example HTML pages for local testing (requires having the server running with npm run dev
):
npm run dev-static
open http://localhost:8080/test/about.html
You can check tracking events directly in the database (requires installed MongoDB):
npm run dev-db
db.trackingEvents.find().sort({ timestamp: -1 }).pretty()