G9Push Documentation

1. What is G9Push?#

G9Push is a complete web-push notification platform you can self-host. You buy a license from G9Push.com, download the push-server software, install it on your own hosting, and use it to collect browser subscribers and send them notifications. Your subscribers and analytics stay on your server — G9Push.com only validates your license.

2. The two parts you'll run#

3. Quick start checklist#

1. Create an account on @/register.php and verify your email.
2. Pick the 7-day trial or the paid package.
3. Open your dashboard → Installations → Add Installation. Enter the domain your push server will live on. Copy the license key shown.
4. From the same page, click Download Software. Upload the ZIP contents to your hosting.
5. Open https://your-domain.com/admin/setup.php. Paste the license key. Create the admin account.
6. Inside the push admin: Add Website, copy the embed snippet, paste it into your customer-facing site.
7. People who click "Allow" become subscribers. Send your first campaign from the admin panel.

4. Create an account#

1. Go to https://g9push.com/register.php (also accessible via the Sign Up button in the top right).
2. Fill in your name, email, phone (optional unless phone verification is required by the admin), and password (8+ characters).
3. Submit. You'll land on a "Check your inbox" page.

5. Verify your email#

1. Open your inbox. Look for an email from G9Push.
2. Click "Confirm my email". The link is valid for 24 hours.
3. You'll be taken to a confirmation page. Click Sign in.

6. Sign in#

1. Go to https://g9push.com/dashboard/login.php.
2. Enter your email and password.
3. If you have a pending plan choice and haven't activated it yet, you'll land on the Plan confirmation screen. Click Activate.
4. If phone verification is required (admin setting), you'll be sent to /verify-phone.php next.
5. Otherwise you land on the Installations dashboard.

7. Phone (SMS) verification#

If the G9Push.com admin has turned on Require phone verification, the first time you sign in after verifying your email you'll be sent to /verify-phone.php. Two paths exist depending on what SMS provider the admin configured:

7a. MSG91 widget (preferred)

1. The page shows "Sending code to <your phone>…"
2. An SMS arrives with a 6-digit code.
3. Type it in the input field. Click Verify.
4. On success the page jumps to plan-confirm (if you have a pending plan) or to Installations.

7b. Server-side OTP (fallback)

If MSG91's widget isn't configured, the system generates its own 6-digit code and texts it via the configured SMS provider (Twilio / MSG91 sendhttp / etc.). Same UX, same outcome.

8. Plans & pricing#

9. Coupons#

If you have a coupon code, paste it on the Checkout screen for the paid package. Two coupon types:

• Percent off (e.g. 20% off the package price)
• Fixed amount off (e.g. $5 off)

Coupons can be tied to affiliates for revenue sharing — that's handled on the admin side.

10. Download the software#

1. Sign in to your G9Push.com dashboard.
2. Go to Installations.
3. Click Add Installation. Enter the domain your push server will live on (e.g. push.yoursite.com). Give it a friendly name.
4. The page shows your license key — copy it now and store it somewhere safe (it's shown once).
5. Click Download Software. You'll get a ZIP file (typically ~250 KB).

11. Upload to your hosting#

1. Unzip g9push-software-YYYYMMDD.zip on your computer.
2. Inside is a folder g9push-software/. Upload the contents (not the folder itself) to your hosting's web root for the push subdomain.
   For example, if your push domain is push.yoursite.com mapped to /var/www/push/, upload there so that /var/www/push/admin/setup.php exists.
3. Make sure your hosting has PHP 7.4+ (PHP 8.x recommended), MySQL/MariaDB, and the OpenSSL + cURL + GMP/BCMath PHP extensions enabled (all standard).

12. Database configuration#

1. Create a new MySQL database via your hosting control panel (cPanel / Plesk / shell). Note the host, database name, user, password.
2. Import sql/push_notifications_schema.sql into the new database (phpMyAdmin → Import).
3. Rename api/config.example.php to api/config.php and fill in your credentials:

<?php
define('DB_HOST', 'localhost');
define('DB_NAME', 'your_database_here');
define('DB_USER', 'your_db_user');
define('DB_PASS', 'your_db_password');

// Optional Redis cache (leave host empty to disable).
define('REDIS_HOST', '');
define('REDIS_PORT', 6379);
define('REDIS_PASS', null);

try {
    $pdo = new PDO("mysql:host=" . DB_HOST . ";dbname=" . DB_NAME . ";charset=utf8mb4", DB_USER, DB_PASS);
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $pdo->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);
} catch (PDOException $e) {
    die(json_encode(['error' => 'Database connection failed']));
}

13. Run the setup wizard#

1. Open https://your-domain.com/admin/setup.php in a browser.
2. Step 1: Database check. Should pass instantly if api/config.php is correct. If it fails, fix the credentials and reload.
3. Step 2: License. Two modes:
   • License key: paste the long key from your dashboard.
   • Installation token: paste a 30-minute one-shot token (better — it can't be replayed). Generate one on the Installations page.
   Click Activate Installation. The server validates with G9Push.com and saves a local cache file.
4. Step 3: Admin account. Enter an admin email + password (8+ chars). Click Create admin & sign in.
5. You're now auto-signed-in to /admin/index.php — the push admin panel.

14. Where the license is stored#

The license cache is a small PHP file that the server checks on every request. It picks the first writable location from:

1. An explicit override via G9PUSH_LICENSE_FILE constant (set in api/config.php).
2. <parent-of-webroot>/.g9push-license/license.php (most secure)
3. <install-root>/.storage/license.php
4. <install-root>/api/.g9push-cache/license.php
5. PHP's session_save_path() directory (universally writable)
6. System temp directory (last resort)

The file is auto-created. On most hosting one of the first three works; PHP's session path is the bulletproof fallback because if sessions don't work, nothing on your site works.

15. Sign in to your push admin#

1. Open https://your-domain.com/admin/login.php.
2. Enter the admin email + password you set in step 13.
3. You land on the dashboard.

16. Add a website#

Each "website" inside your push admin is a separate place where you'll collect subscribers (e.g. one site for your blog, another for your shop). One installation can host as many sites as you want.

1. In the push admin sidebar, click Manage Sites.
2. Click Create Website. Enter:
   • Name: e.g. "Main blog"
   • Domain: the customer-facing domain where you'll embed the snippet (e.g. yourblog.com)
   • Bell widget + Soft-ask: optional opt-in styles
   • Initial / retry delay: when to first show the prompt
3. Click Create Website. The new site appears in the sidebar.

17. VAPID keys explained#

A VAPID keypair is the cryptographic identity your push server uses to sign every notification. The browser stores the public half against each subscription when it's created; the push service (Google FCM / Mozilla / Apple) verifies the signature against that stored key before delivering. If the keys don't match, the push is rejected with HTTP 403 (or 410 once the subscription is invalidated).

What the panel shows

Each site has three columns in the database: vapid_public, vapid_private_enc, vapid_private_pem. All three are filled automatically when you create a site.

Are all my sites on the same key?

Push admin → Import/Export tab → VAPID key alignment table. Each row shows a site + its key fingerprint + ✓/✗. If everything is ✓, all sites share one key, and cross-site transfer works.

18. Embed snippet / WordPress plugin#

Plain HTML site

Push admin → click a site → Integration → copy the snippet. Paste it just before </body> on every page of the customer-facing site. Done.

WordPress

Same screen has a WP Plugin button that downloads a one-click plugin pre-configured for that site. Install it on WordPress like any other plugin and activate. No copy-paste needed.

Shopify / other

Paste the snippet into the theme's footer / global include.

19. How a subscription works (the mailbox analogy)#

The cleanest way to think about a push subscription:

1. A person visits your site and clicks Allow. Their browser asks the push service (Google for Chrome, Mozilla for Firefox) to create a mailbox for them.
2. The push service creates the mailbox and gives the browser an address (a URL like https://fcm.googleapis.com/fcm/send/...). The browser hands this address to your server.
3. Your server writes the address down in the subscriptions table.
4. To send a notification, your server drops a message at that address. The push service receives it and delivers it to the person's browser.

20. Live vs dead subscribers#

A subscription becomes dead when the mailbox is destroyed: the user unsubscribed, cleared their browser data, their browser auto-expired the subscription, or the VAPID key changed so the push service no longer trusts your sender. When you try to send to a dead mailbox, the push service replies with an HTTP error and the subscription is auto-marked as expired in your database.

21. Health panel & cleanup#

Push admin → Subscribers tab → at the top is a 💚 Subscriber Health panel showing three boxes per site:

• ✅ Live — subscriptions currently status='active'. Will receive your next campaign.
• ❌ Dead — subscriptions a push service told us are gone (410/403). Will NOT be sent to.
• % still live — what share of all-time subscribers are still reachable.

Cleaning up dead rows

If dead rows are present, a 🧹 Clean up database section appears with two buttons:

• Delete N dead — this site — purges dead rows for the currently-selected site.
• Delete N dead — ALL sites — purges across every site you manage in one click.

Recommended workflow

1. Send a campaign first — this forces the system to detect any newly-dead subscriptions and mark them expired.
2. Then hit Delete N dead — ALL sites to physically reclaim the space.

22. Pagination & country filter#

The Subscribers list paginates 100 rows per page (large totals get a sliding window pager: ‹ Prev 1 … 2 3 4 … 12 Next ›). All filters (country, search) survive page navigation; reloading directly to ?page=2 stays on the Subscribers tab automatically.

The Country dropdown uses a timezone-first detection that matches the table column's country, so a subscriber with locale=en-GB and tz=Asia/Kolkata appears under "India" in both the table and the filter.

23. Send a campaign#

1. Push admin → Campaigns → Send Campaign.
2. Fill in Title, Body, optional Icon URL / Image URL / Click URL.
3. Choose target audience: All subscribers, a saved Segment, or specific countries.
4. Click Send Now. The page reloads with a result summary.

24. Reading campaign results#

After sending, the result line looks like:

Campaign sent! 124 delivered, 18 expired (auto-cleaned), 2 failed.

• delivered — the push service accepted the push. The user will see the notification (if their browser is online; otherwise on next wake).
• expired (auto-cleaned) — 410 / 403 responses. These mailboxes were marked dead in the same operation; they won't be tried again.
• failed — temporary errors (e.g. 5xx). They stay active and can be retried.

Click View failure details to see the breakdown by HTTP status, by push provider (FCM / Mozilla / WNS), and a sample response body per code. See the table in §20 for what each status means.

25. A/B testing#

The A/B test sends Variant A to a random 50% of the selected audience and Variant B to the other 50%. Set both titles + bodies, click Run A/B Test. Results show side by side so you can compare delivered + clicks.

26. Managing 2+ sites on one license#

One installation, one license, many websites. When you create a new site, the admin copies the same master VAPID keypair from your oldest site. Whether you add a site on day 1, day 30, or day 365 makes no difference — it always inherits the master key.

1. Sign in to the push admin.
2. Use the Site dropdown in the top bar to switch between websites.
3. The Subscribers, Campaigns, and Settings tabs are per-site. Each site has its own subscriber list and analytics.
4. The Import/Export tab's VAPID key alignment table shows that every site is on the same key (✓ aligned). This is what makes cross-site transfer safe.

27. Transfer subscribers between sites#

The supported, safe way to move subscribers between your own sites:

1. Push admin → Import/Export tab → 🔄 Transfer subscribers between your own sites card.
2. The status table at the top confirms all sites share the same VAPID key (green banner = good to go).
3. Pick From site (source) → To site (destination).
4. Choose Move (recommended — no duplicates) or Copy (subscriber receives campaigns from both sites).
5. Click 🔄 Transfer subscribers now.
6. The result confirms "✓ Both sites share the same VAPID key, so these subscribers WILL receive campaigns from the destination site."

28. Why cross-domain imports don't work#

A push subscription is cryptographically locked to (a) the browser's view of which domain created it and (b) the VAPID key in use at that moment. Pasting endpoint URLs into the Import tab from someone else's domain just creates dead database rows: the next campaign hits 410/403, the rows get auto-cleaned, your real subscriber count is unchanged.

This is a Web Push security rule (otherwise anyone could steal a website's audience by exporting endpoints). No setting and no code change can override it.

29. Moving the push server to new hosting#

You can move the push server to a different host without losing subscribers, as long as you bring three things with you:

30. Step-by-step migration#

1. On the OLD host: run mysqldump -u USER -p DB_NAME > backup.sql. Download backup.sql.
2. On the NEW host: create a new MySQL database. Import backup.sql into it.
3. Upload the push-server PHP files to the new web root.
4. Edit api/config.php on the new host with the new DB credentials.
5. On G9Push.com → Installations → click your install → click Generate install token. Copy the token.
6. Open https://new-domain.com/admin/setup.php. Step 2 → paste the install token → Activate Installation.
7. Step 3 — see §31 for what happens here.
8. Update the DNS for your push subdomain to point at the new host.
9. Test sending a campaign. The result should match what the old host had.

31. "An admin already exists for this installation"#

This message appears in Step 3 of the setup wizard on the new hosting after a migration, because the admin_users table you brought with you already contains your original admin row. The wizard refuses to silently overwrite it. Two paths from here:

If you remember the old password

1. Go to /admin/login.php.
2. Sign in with your existing admin email + password. Done.

If you forgot the old password

The setup wizard now lets you reset it directly (Step 3 changes to Reset your admin password):

1. Re-open /admin/setup.php on the new host.
2. Step 3 form says "An admin account already exists in this database… If you forgot the password, enter the same email plus a new password."
3. Enter your existing admin email (must match exactly, case-sensitive) + a new password.
4. Click Reset password & continue. You're auto-signed-in and dropped on the admin dashboard.

32. License-file troubleshooting#

If activation reports "License accepted by G9Push, but this server could not save the license cache", the file-system on your new hosting is blocking writes to all auto-detected paths. Force a specific writable path:

1. SSH or FTP into the new hosting.
2. Pick a directory you know is writable by PHP. The safest universal choice is the directory PHP uses for sessions; you can find it by visiting /api/?path=phpinfo or by running echo session_save_path(); in any small PHP file. Common values: /tmp, /var/lib/php/sessions, your user's home directory.
3. Open api/config.php and add one line near the top:

define('G9PUSH_LICENSE_FILE', '/absolute/path/to/g9push-license.php');

4. Save the file. Re-run /admin/setup.php and paste a new installation token.
5. The wizard now writes to your chosen path and proceeds to Step 3.

33. Common errors & fixes#

34. Frequently asked questions#

35. Get help & report issues#

• Email support: support@g9push.com
• When asking for help, please include:
  • The URL of the page where the issue appeared
  • The exact error text (screenshot is fine)
  • Whether this is on the G9Push.com side or your own push server
  • Browser + OS for client-side issues
• For VAPID / OTP / license issues, the diagnostic panels in the relevant admin tab usually print exactly what's wrong (e.g. MSG91 code 418, the candidate path that failed to write). Paste that text into your support email.

Documentation version: rolling. Last updated June 23, 2026. Spotted something out of date or unclear? Email support@g9push.com.