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#

You install G9Push on your customer-facing website in one of three ways: a one-click WordPress plugin (recommended for WP), a copy-paste HTML snippet, or a theme-footer include for Shopify and others.

18a. WordPress plugin — recommended for WordPress sites

The plugin generated by your push admin is pre-configured for one specific site — the VAPID public key, site ID, embed snippet, bell-widget choice and other settings are baked in. You don't paste any keys or edit any files. Install, activate, done.

Where to download the plugin

1. Sign in to your push-server admin panel (e.g. https://push.yourdomain.com/admin/).
2. In the sidebar, click 🌐 Manage Sites.
3. Find the site you want the plugin for. Click the 📦 WP Plugin button on that row.
4. A file like g9push-yoursite-com.zip downloads to your computer (typically <100 KB).

Install the plugin in WordPress — Option A (admin upload, fastest)

1. Sign in to your WordPress admin: https://yoursite.com/wp-admin/.
2. In the WP sidebar, click Plugins → Add New Plugin → Upload Plugin (button at the top of the page).
3. Click Choose File → select the g9push-yoursite-com.zip you just downloaded.
4. Click Install Now. WordPress unzips and installs it.
5. Click Activate Plugin.
6. Visit your site in a fresh incognito tab. After a moment, you should see the bell-widget appear (or the "Allow notifications?" prompt, depending on your site's settings). Click Allow.
7. Back in your push admin → 📊 Overview → the row for that site should show 1 live subscriber within a minute. That's you.

Install the plugin in WordPress — Option B (FTP, if you can't upload via admin)

1. Unzip g9push-yoursite-com.zip on your computer. Inside is a folder named e.g. g9push-yoursite-com/.
2. FTP into your WordPress hosting and navigate to wp-content/plugins/.
3. Upload the entire g9push-yoursite-com/ folder there.
4. Go to WP admin → Plugins. You should see G9Push for yoursite.com in the list (deactivated).
5. Click Activate.
6. Verify as in steps 6-7 of Option A.

Service worker — critical to verify

Web Push requires a service worker file (sw.js) accessible at the root of your domain. The plugin handles this for you, but on some WordPress hosts (especially behind aggressive caches or with strict .htaccess) it can be blocked. After activating the plugin, open this URL in your browser:

https://yoursite.com/sw.js

You should see a JavaScript file (not a 404 page, not a redirect). If you see a 404:

• If using a caching plugin (WP Rocket, W3 Total Cache, LiteSpeed, etc.) — clear its cache and add sw.js to its exclusion list.
• If using a CDN (Cloudflare, KeyCDN) — purge cache for sw.js and configure the CDN to NOT cache that file.
• If .htaccess blocks unknown files — add an allow rule for /sw.js.

Updating the plugin later

The plugin is pre-configured per site, so it doesn't auto-update via the WordPress repository. To upgrade:

1. Download a fresh plugin ZIP from push admin → Manage Sites → 📦 WP Plugin.
2. In WordPress admin → Plugins, deactivate the existing one (don't delete — that wipes its options).
3. Upload the new ZIP (Option A) — WP will ask to replace; confirm.
4. Activate again.

Existing subscribers are NOT affected by a plugin update — only the JS files on disk change.

Removing the plugin

WP admin → Plugins → Deactivate, then Delete. Existing subscribers continue to receive your campaigns until they uninstall the browser-side subscription themselves. To stop sending to them entirely, you can also revoke the corresponding site in your push admin.

18b. Plain HTML site / static site

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

<script src="https://push.yourdomain.com/sdk.js" data-site-id="3" data-vapid-public="BL…"></script>
</body>

Also upload the service worker sw.js to the root of your domain (not in a subfolder — the browser strictly requires this).

18c. Shopify / other CMS

For Shopify, paste the JavaScript snippet into Online Store → Themes → Edit code → theme.liquid, just before </body>. For the service worker, upload sw.js as a theme asset and add a redirect rule that maps /sw.js to that asset URL — or use a third-party "service worker proxy" app from the Shopify app store.

For Wix, Squarespace and similar closed CMSes that don't let you serve sw.js from the root: web push will not work without root-level service worker access. Consider moving to a CMS that does (WordPress, Ghost, custom).

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. Cleaning up dead subscribers#

Dead subscribers (subscriptions a push service has rejected as 410 / 403 / 401-on-WNS) take up database space and pollute your "Live" count. G9Push gives you three different tools, in different places, for different situations.

21a. Where the controls live

21b. The three tools — when to use which

🔍 Validate (Overview → per-site row)

The most thorough option. When you click it on a site's row:

1. You're warned: "This will send a REAL push notification to N active subscriber(s)."
2. You're prompted for the notification title and body (pre-filled with a neutral "👋 [Site Name] — Thanks for staying subscribed. (Service validation)").
3. The system sends that notification to every active subscriber of the site.
4. Push services that respond with 410 / 403 / 401-on-WNS reveal which subscribers are dead.
5. The system marks those dead and then physically DELETES every dead row for that site (newly detected + any leftovers).
6. A summary alert tells you the final numbers: "Sent to 47, Delivered 30, Newly dead 17, Deleted 17. Now: 30 live, 0 dead."
7. The row updates in place; grand totals recompute.

🧹 Delete dead (Overview → per-site row, and Subscribers tab → Health card)

Just removes already-dead rows. Doesn't send anything. Use after a normal campaign already detected the dead subscribers — this physically removes them from the database.

• On the Overview tab: the 🧹 button on each row deletes dead rows for that one site.
• On the Subscribers tab: the Health card has two buttons — "Delete N dead — this site" and "Delete N dead — ALL sites".

🔄 Refresh all (Overview → top right of the All-Websites card)

Re-reads the database for every site and updates the counts in place. Does NOT send anything, does NOT detect new dead. Useful to confirm a refresh after a campaign, or when another admin made changes elsewhere.

21c. Recommended workflows

Routine (do this after every campaign)

1. Send your campaign normally.
2. The campaign result shows e.g. "30 delivered, 16 expired (auto-cleaned)" — those 16 are now status='expired'.
3. On the Overview tab, click 🧹 on that site's row (or on Subscribers → Health → Delete N dead — this site) to remove the 16 expired rows from the database.

Periodic full audit (monthly)

1. For each site you manage, click 🔍 Validate on its row.
2. Customise the notification text or accept the default.
3. The send fires, the dead are detected, the dead rows are deleted. Result alert tells you the new authoritative numbers.
4. Your Live count is now a definitive, real number.

Bulk reclaim disk space (after a long period of campaign sends)

1. On Subscribers tab → 💚 Subscriber Health → click Delete N dead — ALL sites.
2. Confirms across all sites in one click. Removes every dead row everywhere.

21d. Does the dashboard update automatically after a campaign?

Yes. After a campaign send:

• The page fully reloads on POST → all dashboard cards re-query the database → counts are fresh.
• Switching to the Subscribers tab triggers an extra AJAX refresh of the Health card (belt-and-braces).
• Switching back to the Overview tab triggers an AJAX refresh of every row in the All-Websites table.
• Manual 🔄 Refresh all is always available for instant re-pull.

No manual page reload is needed in the normal flow.

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. Playbook — license cache won't save on your hosting#

Why this happens

The push-server software needs to save a small license-cache file so it doesn't have to ask G9Push on every request. On many shared / managed hosts (AWS EC2, DigitalOcean default Apache, cPanel under suEXEC), the install directory and its children are owned by your deploy user (e.g. admin, root, ec2-user) but PHP runs as a different user (typically www-data). PHP can read but can't write into the install — so the cache write silently fails.

Fix

The auto-detect logic already tries several writable locations (above the docroot, inside the install, PHP's session save path, the system temp directory). If none work, give it an explicit path you know is writable:

1. SSH into your server.
2. Find PHP's session save path (almost always writable):

   php -r 'echo session_save_path(), "\n";'
   # common results: /var/lib/php/sessions, /tmp, or your home directory

3. Open api/config.php and add ONE line near the top, before the try block:

   define('G9PUSH_LICENSE_FILE', '/var/lib/php/sessions/g9push-license.php');
   // ↑ replace path with what session_save_path() returned

4. Save the file. Re-run /admin/setup.php with a fresh installation token (generate a new one from your G9Push.com dashboard — the old one was single-use).
5. Activation should now succeed and move to Step 3 (admin password).

How to prevent

The simplest long-term fix is to give PHP write access to the install directory (see §38 for the exact chown/chmod commands). With write access, no G9PUSH_LICENSE_FILE override is needed — the auto-detect picks the install's .storage/ automatically and updates work cleanly.

35. Playbook — "An admin already exists for this installation" after hosting migration#

Why this happens

This is actually good news — it means your database migration worked. The admin_users table you brought with you still has your original admin row. The wizard is protecting that row from being silently overwritten. Your subscribers, sites, and campaigns are all intact.

Fix — if you remember the old admin password

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

Fix — if you forgot the password

The setup wizard now doubles as a password recovery tool. After license activation, Step 3 turns into a "Reset admin password" form:

1. Re-open /admin/setup.php.
2. Step 3 form should now read: "An admin account already exists in this database — most likely because you brought your existing database with you to new hosting. Your subscribers and all other data are safe and will NOT be touched."
3. Enter your existing admin email (case-sensitive, must match exactly) + a new password.
4. Click Reset password & continue. You're auto-signed-in and dropped on the admin dashboard.

36. Playbook — update fails with "Could not open temp file for writing"#

Why this happens

The updater needs a writable scratch directory to download the new ZIP, extract it for staging, and back up your current install before applying. By default it uses <install>/storage/. On hosts where the install isn't writable by PHP (same root cause as §34), that's exactly the file that fails to open.

Fix

The fix has two layers — the updater needs a writable temp area and write access to the install root itself (because it has to overwrite the existing PHP files).

1. SSH into your server (or use FTP if SSH isn't available).
2. Grant PHP write access to the install. Replace admin with YOUR SSH/FTP username (find it in your shell prompt — e.g. admin@host:~$ means username is admin):

   sudo chown -R admin:www-data /var/www/your-install/
   sudo chmod -R 775 /var/www/your-install/

   This makes you the owner (so FTP works) and gives the www-data group write access (so PHP can update).
3. Go back to your push admin's Updates page and click Update Now again.

If the install root really cannot be made writable

Some hosts enforce read-only installs. In that case, the updater shows a detailed "Option 2 — Apply the update manually via FTP" panel with a 7-step procedure: download the ZIP from your G9Push.com dashboard, unzip locally, FTP the contents over your install, preserving api/config.php. That always works.

How to prevent

Set up your install with PHP-writable permissions from day one (per the chown command above). It's a one-time setup that makes every future update click-through.

37. Playbook — update completed but admin panel redirects to setup.php#

Why this happens

The release ZIP your push server downloaded contains an older copy of api/license.php — older than the customised version you had after fixing §34. The update overwrote your good api/license.php with that older copy. The older code doesn't know about the alternate license-storage paths (PHP session dir, system temp), so it looks in only one place, doesn't find the cache file, and concludes "no license configured" → redirect to setup.

Your license file is still on disk in its original location. The new code just doesn't know to look there.

Fix

1. FTP into your hosting and navigate to <install>/api/.
2. Upload the latest api/license.php from your developer machine (the version that knows about multiple candidate paths) over the one on the server. If you don't have a developer copy, contact support — they can email you the file.
3. Refresh /admin/. The patched code's Pass 1 looks for an already-existing license file across all candidate paths; it finds yours in /tmp (or wherever) and resumes. You should land on the dashboard.

How to prevent

The updater now adds api/license.php to its preservation list (alongside api/config.php). From this update forward, the updater won't overwrite api/license.php automatically — your customised storage logic survives. If a future release genuinely needs to ship a new api/license.php, the release notes will tell you to upload it manually.

38. Playbook — FileZilla can't upload files after fixing PHP permissions#

Why this happens

The previous chown transferred ownership entirely to www-data (the PHP user). Your FTP user (likely your SSH login) is no longer the owner, so it can't overwrite files via FTP.

Fix — give both you and PHP write access

1. SSH in. Note your username from the prompt — e.g. admin@ip-172-…:~$ means your username is admin.
2. Run these two commands, replacing admin with your actual username:

   sudo chown -R admin:www-data /var/www/your-install/
   sudo chmod -R 775 /var/www/your-install/

3. Verify:

   ls -la /var/www/your-install/api/license.php
   # should show: -rwxrwxr-x  1 admin www-data ... license.php
   #                  ↑ admin owns, www-data is group, both have write

4. Test a write as your user:

   touch /var/www/your-install/api/test.txt && rm /var/www/your-install/api/test.txt && echo OK

   If that prints OK, FileZilla uploads will work.
5. Reconnect FileZilla and retry the upload.

How to prevent

Never use chown -R www-data:www-data on the whole install — that takes ownership away from you. The admin:www-data + 775 combination above is the right baseline going forward.

39. Playbook — campaign send fails or stays silent#

This one has multiple flavours. Match the exact message you see:

39a. "Campaign created but sending may be incomplete. Error: admin login required"

Why: The admin panel calls its own /api/send-campaign.php over loopback. That endpoint enforces admin auth — but the loopback call carries no browser session cookie, so it gets rejected.

Fix: Update to the latest software (use the in-admin updater per §36). The loopback path now signs a short-lived internal token that send-campaign.php recognises.

39b. "Campaign created but sending may be incomplete. Error: Unknown error"

Why: send-campaign.php returned an empty body or non-JSON output. Almost always a PHP fatal during a long send — default max_execution_time kills the script halfway through.

Fix: Update to the latest software. The updated send-campaign.php calls set_time_limit(0) and ignore_user_abort(true) after the auth + license gates, so big sends complete even if your browser tab times out.

39c. "send_exception: Call to a member function prepare() on null"

Why: A scoping bug in older versions where $pdo was created in a function scope and never made global.

Fix: Update to the latest software. The fix is in api/_guard.php — it now promotes $pdo into $GLOBALS when needed.

39d. "X delivered, Y expired (auto-cleaned)" — where Y is most of your audience

Why: The Y subscribers were either (a) imported from a different domain (permanent — see §28), or (b) created before a VAPID key change (see §17). Either way the push services say their mailboxes are gone (HTTP 410/403).

Fix: Nothing to recover. The Y subscribers can never receive notifications again unless they revisit your site and click Allow. Your real audience is now the X "delivered" number, which grows from here as people subscribe organically. See also §21 for the cleanup button to remove those dead DB rows.

40. Playbook — MSG91 "Authentication Failure (HTTP 400)" during OTP verify#

Why this happens (admin-side issue, but users see the symptom)

MSG91 has three different secret values in three different places on their dashboard, and they are very easy to mix up:

• Widget ID — short hex (~24 chars), from the OTP widget config page
• Widget tokenAuth — a long JWT (with dots), same widget config page
• Server Auth Key — short alphanumeric (~24 chars, NO dots), found in the MSG91 profile menu (top-right corner), labelled "Auth Key"

Pasting the long Widget tokenAuth into the "Server Auth Key" field is the #1 cause of this exact error.

Fix (if you administer the G9Push install)

1. Go to admin → Settings → MSG91 OTP widget card.
2. Look at the "Saved values" panel. The Server authkey row should show a short string (~24 chars). If it shows ⚠ "Looks like a JWT" or the length is 100+ chars, the wrong value is pasted.
3. In MSG91 → click your profile icon (top-right) → click Auth Key. It's a short alphanumeric string, NO dots.
4. Use the COPY button next to it (don't double-click + Ctrl-C — that often grabs trailing whitespace).
5. Paste into the Server authkey field, save settings.
6. Click the 🔑 Test MSG91 authkey button at the bottom of the page. A green ✓ confirms the key is valid.
7. Retry the OTP flow.

If Test authkey is green but verifies still fail

Your authkey is valid, but the OTP widget was created in a different MSG91 account than this authkey. Either copy the Auth Key from the same account that owns the widget, or create a new widget in the account whose Auth Key you have.

How to prevent

The settings page now shows a fingerprint preview of each saved key (length + first/last chars) and a red warning if the Server Auth Key field looks like a JWT. Glance at the preview after saving — that catches 90% of mistakes before users hit them.

41. Frequently asked questions#

42. 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 September 23, 2026. Spotted something out of date or unclear? Email support@g9push.com.