# One Tap Go Marketing Tracking System

A lightweight PHP/MySQL marketing operations and link tracking system built for `https://tracker.onetapgo.my` and standard cPanel/Apache hosting.

## Server requirements

- Apache with `mod_rewrite`
- PHP 8.1+ with PDO MySQL, fileinfo, JSON and OpenSSL
- MySQL 5.7+ or MariaDB 10.4+
- HTTPS certificate for `tracker.onetapgo.my`

## Installation on cPanel

1. In cPanel, create the subdomain `tracker.onetapgo.my` and note its document root.
2. Create a MySQL database named `onetapgo_marketing_tracker` (cPanel may add an account prefix), create a database user, and grant it all privileges on that database.
3. Upload the ZIP contents to the subdomain document root and extract them. Ensure hidden files such as `.htaccess` are included.
4. Copy `config.example.php` to `config.php`. Enter the actual database name, username and password. Set `base_url` to `https://tracker.onetapgo.my` and replace `ip_hash_salt` with a long random value.
5. Make the `uploads` directory writable by PHP (normally permission `755`; use `775` only if required by the host).
6. Visit `https://tracker.onetapgo.my/install.php`, create the first administrator, and sign in.
7. **Immediately delete `install.php` from the server.**
8. In cPanel, force HTTPS and confirm that a test link such as `/t/test-code` is routed by Apache rather than returning a server-level 404.

Alternatively, import `database/schema.sql` in phpMyAdmin and create the first admin with `install.php` afterward. Do not import the schema twice.

## First-use checklist

1. Sign in as Admin and open **Settings**. Add or update platforms, content types, service types, statuses, custom fields, report settings and system settings.
2. Add a Client.
3. Add Staff and Client users. A client-role user must be assigned to a client; their portal is automatically restricted to that client's projects and data.
4. Add a Project/Campaign and its original destination URL.
5. Open the project and generate one or more tracking links. Each may have a source, medium, campaign and custom slug.
6. Use the QR Code button beside a tracking link. QR image rendering uses the public `api.qrserver.com` endpoint, while scan/click tracking remains on your server. If external QR generation is unsuitable, replace the QR route with a locally hosted QR library.
7. Add performance entries and insight images/PDFs. Re-entering the same project and date updates that day's figures.
8. Use Reports, choose a range/client, then click **Export / Save PDF** and select “Save as PDF” in the browser print window.

## Click tracking and privacy

The redirect endpoint records click time, a salted IP hash, a visitor hash, 24-hour unique status, device category, browser, referrer/source and available country/region headers before issuing an HTTP 302 redirect. It does not store raw IP addresses.

Country/region values are populated when the host or Cloudflare sends `CF-IPCountry` / region headers. Without such headers they remain blank; this deliberately avoids a paid geolocation dependency. Update your privacy notice and cookie/data policy for the jurisdictions where the system is used.

## Security and operations

- Keep `config.php` outside source control and never share it.
- Delete `install.php` after installation.
- Use HTTPS only and strong, unique passwords.
- Back up both files and database before upgrades.
- Set a conservative PHP upload limit and keep the allowed MIME list narrow.
- The included upload protection blocks executable extensions. Where possible, also disable script execution for the upload directory in cPanel.
- Click uniqueness is an operational estimate, not a person-level identity measure.

## API integrations

The `integrations` table is reserved for Meta, TikTok, Google and other providers. Version 1 intentionally uses manual performance entry. Provider credentials should be encrypted with an application secret before any connector is implemented; never save raw tokens directly.

## Main modules

- Admin / Staff / Client authentication and authorization
- Clients and user management
- Projects, campaigns, platform/content/service/status metadata
- Multiple redirect links per project and custom slugs
- Click and unique-click attribution
- QR delivery
- Manual reach, impressions, views, engagement, leads, sales and spend
- Insights screenshot/PDF uploads
- Dynamic settings and project custom fields
- Date/client/platform/content filters
- Client-scoped report and browser PDF export

## File map

- `index.php` — application routes and modules
- `lib/bootstrap.php` — database, auth, security and shared helpers
- `database/schema.sql` — database schema and starter settings
- `config.example.php` — safe configuration template
- `install.php` — one-time installer; delete after use
- `.htaccess` — clean tracking URL routing

