User points and leaderboard

## The problem it solves

A visitor comes, reads one page, and leaves. They have no reason to browse the site, no reason to come back tomorrow, no reason to register.

This plugin gives them all three reasons.

## How it works

Every visitor — whether a member or a guest — earns points for **each minute of active presence**. “Active” means the tab is really open and visible and the user makes some movement; a tab abandoned in the background earns not a single point.

But here is the key point: **there are no points beyond 10 minutes on one page.** When the cap is reached, instead of a dry message, the plugin puts three fresh pages of your site in front of the user. The direct result: to earn points, the user has to browse your site, and exactly what every site wants happens — more pages, more time, more depth.

## A slide-out panel on the side of your site

A small handle beside the page that shows the user's rank. It opens with one click and tells them:

- What your rank is, out of how many people
- If you are not in the top 50, which **decile** you stand in — “rank 843” is discouraging, “third decile” is understandable and improvable
- Exactly how many points to the next rank and to first place
- Top-50 table, with two modes: “Total score” and “This month”
- Time spent on this very page, live

It is fully right-to-left, you set its main color yourself, it understands light and dark themes, and it sits properly on mobile too.

## Rewards — the reason users come back

A table with no prize at the top dies after two weeks. **You set the prize**, not the plugin: you place a prize on each rank or range of ranks — a product from the site, a service, a discount code, cash or bonus points — and it sits in front of everyone right at the top of the slide-out widget.

At the end of each month, winners are recorded automatically and a list with a “delivered / pending” status appears in front of you so no prize is forgotten. If you have WooCommerce, a “discount code” prize turns itself into a single-use code tied to the winner's email.

## Guests earn points too — and that’s what turns them into members

A guest's points are kept with a cookie. The moment they sign in, **all the points they have collected are transferred to their account**. A user near the top of the table who sees that the prize goes only to members has a real reason to register — not a decorative button.

## Seasonal competitions

The table has two modes: “Total score,” which never resets to zero, and “This month,” which starts over at the beginning of every **Jalali** month. Each season's table is archived with the names of the top three, and the champions receive a badge. A newcomer has a chance at the top, and a veteran's points are never lost.

## What earns points

- Each minute of active presence
- Every new page opened during the day
- First visit of each day
- Streak of consecutive days — each day more than the one before
- Approved comment
- Badges: Explorer, Marathon, Loyal, Veteran, Top Ten
- “Golden hour”: a window of the day with a multiplied score, to fill the quiet hours of the site
- A dedicated multiplier per user role, and a weekend multiplier

## For the site owner

- **Online panel**: who is on the site right now, how long they have stayed, and on which device
- **User login notifications**: a live counter in the WordPress admin bar, a webhook for a Telegram / Bale / Eitaa bot or any other service, and instant email alerts or a daily digest
- **Dashboard** with a 14-day chart, the pages that took the most time, and recent events
- Manually adjust points, block, or exempt any player
- Shortcode to show the table on any page, CSV export, and REST API

## Anti-cheat — without it, a leaderboard lasts a week

The server never takes the browser's word for it. The validated time is never more than the time that has really passed on the server clock, so sending back-to-back heartbeats earns no points. In addition:

- Daily score cap per person
- Time cap per page
- Single-tab lock: opening ten tabs of the site does not earn ten times the points
- Time in a hidden tab or while the user is idle is not counted at all
- Rate limiting on the endpoint, and excluding bots

## It doesn’t slow your site down

Each heartbeat runs only three simple primary-key queries. Summarizing, cleanup and closing the season all run in cron, not on the visitor's path. The leaderboard is cached and a personal rank is computed with a single indexed count, not by numbering the entire table.

It also works properly on a site with full-page caching: neither the visitor's identity nor the table's content ends up in the page HTML.

## Privacy

IP anonymization is on by default. No data about your visitors is sent to any server; the plugin's only outside connection is the license check with di9, which sends only the key and domain name. Data retention is adjustable and automatic cleanup runs.

## Built for RTL from the ground up

All dates are Jalali, the numbers are Persian, and the entire interface — panel and slide-out widget — is written right-to-left from the ground up, not a left-to-right template that has been flipped.