Shields.IO Visitor Counter

Warning

This project has been archived (September 2023), as its CountAPI dependency no longer works. See pinned issue #17 for further details.

A simple visitor counter displayed as a Shields.IO static badge.

How it works

This application is deployed on Heroku, and creates a Shields.IO static badge that you can embed on your page. Every time your page loads, it reloads the badge, which pings CountAPI to increase the counter!

Creating your own visitor counter

If you've used Shields.IO before, it's really straightforward! Let's use the octocat/Spoon-Knife GitHub repository as an example.

To create a counter with all default options, add the page argument with your username.repo to the application URL:

https://shields-io-visitor-counter.herokuapp.com/badge?page=octocat.Spoon-Knife

to get this:

And to embed this in Markdown, just use:

![Visitor count](https://shields-io-visitor-counter.herokuapp.com/badge?page=octocat.Spoon-Knife)

Options

The only mandatory argument is page, but you can use almost all options available on Shields.IO — the only unavailable one is message, as this is the count! To add option, just add it to URL query component.

Let's take our previous example, and modify it! Say we want the following:

Label (left-hand side) to say My First Counter on a black background, with a white GitHub logo;
Message (right-hand side) to have a blue background; and
Style it with the Shields.IO for-the-badge style

From the Shields.IO documentation, we can:

Change the label text using the label parameter;
Change the label background colour using the labelColor parameter;
Add a logo to the label, and change its colour using the logo, and logoColor parameters, respectively;
Change the message background colour with the color parameter; and
Change the badge style use the style parameter.

All in all, the previous URL becomes:

https://shields-io-visitor-counter.herokuapp.com/badge?page=octocat.Spoon-Knife&label=My First Counter&labelColor=000000&logo=GitHub&logoColor=FFFFFF&color=1D70B8&style=for-the-badge

which gives us:

Note we used hex colours in the URL, but Shields.IO also supports (some) colours by name!

Caveats

It's not smart enough to track users by IP address, for example. So if you reload the page, the counter will also increase!
It runs on Heroku Free Tier as part of my 1,000 free dyno hours per month — if this runs out, the application will be down!
Applications on Heroku Free Tier should timeout after 30 minutes, but I'm using cron-job.org to wake it up every 15 minutes, so it should always be on!

If the application is down, and doesn't wake up, raise an issue, and I'll look at it as soon as possible!

Contributing

If you'd like to contribute to this work, take a look at CONTRIBUTING.md to get started!

Attribution

This work is based on Visitor Badge by Jiang Wenjian, and their excellent blog post on its development.