STEPS ZOTE ZA KUINSTALL APP
1) PWA ni nini kwa kifupi
PWA ni website ambayo inaweza:
• kuonekana kama app
• kuinstalliwa kwenye simu au desktop
• kufunguka hata offline kwa baadhi ya pages
• kuwa na icon kwenye home screen
• kufungua bila browser tabs nyingi kama website ya kawaida
Ili system yako iwe PWA unahitaji vitu vikuu 3:
• manifest.json
• sw.js (service worker)
• icons za app
Halafu page yako kuu lazima:
• iwe na link ya manifest
• i-register service worker
• iwe na theme-color
• iwe HTTPS
________________________________________
2) Folder structure ya kutumia
Tengeneza structure hii kwenye project yako:
/project-folder
│
├── index.php
├── manifest.json
├── sw.js
├── offline.html
├── logo-header.png
│
└── icons
├── icon-72x72.png
├── icon-96x96.png
├── icon-128x128.png
├── icon-144x144.png
├── icon-152x152.png
├── icon-192x192.png
├── icon-384x384.png
└── icon-512x512.png
Kama system yako si index.php, bado unaweza kutumia page nyingine kama:
• home.php
• dashboard.php
• app.php
Lakini kwa guide hii nitabaki na index.php.
________________________________________
3) STEP 1: Andaa logo na icons
Kwa PWA, logo ya app haitumii PDF moja kwa moja. Inahitaji PNG images.
Wewe tayari una logo file kwenye PDF.
Tumia zile files nilizokutengenezea tayari:
• Pakua PWA icons zip
• Pakua logo ya kawaida PNG
• Pakua logo ya header
Cha kufanya
• unzip star_quality_pwa_icons.zip
• copy folder la icons liingie ndani ya project yako
• copy logo-header.png liingie root ya project
________________________________________
4) STEP 2: Tengeneza manifest.json
Hii ndiyo file inayoiambia browser jina la app, icon zake, na namna ya kufunguka.
File: manifest.json
{
"name": "STAR QUALITY MICROFINANCE",
"short_name": "SQM App",
"description": "Professional microfinance platform for loans, repayments, borrowers, reports, and daily operations.",
"start_url": "/index.php",
"scope": "/",
"display": "standalone",
"orientation": "portrait",
"background_color": "#f8fbff",
"theme_color": "#0d6efd",
"lang": "en",
"dir": "ltr",
"icons": [
{
"src": "icons/icon-72x72.png",
"sizes": "72x72",
"type": "image/png"
},
{
"src": "icons/icon-96x96.png",
"sizes": "96x96",
"type": "image/png"
},
{
"src": "icons/icon-128x128.png",
"sizes": "128x128",
"type": "image/png"
},
{
"src": "icons/icon-144x144.png",
"sizes": "144x144",
"type": "image/png"
},
{
"src": "icons/icon-152x152.png",
"sizes": "152x152",
"type": "image/png"
},
{
"src": "icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "icons/icon-384x384.png",
"sizes": "384x384",
"type": "image/png"
},
{
"src": "icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any maskable"
}
],
"shortcuts": [
{
"name": "Login",
"short_name": "Login",
"description": "Open login page",
"url": "/mikopologin.php",
"icons": [
{
"src": "icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
}
]
},
{
"name": "Dashboard",
"short_name": "Dashboard",
"description": "Open dashboard",
"url": "/mikopodashboard.php",
"icons": [
{
"src": "icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
}
]
}
]
}
________________________________________
5) STEP 3: Tengeneza offline.html
Hii ndiyo page ya kuonyesha internet ikiwa haipo.
File: offline.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Offline | STAR QUALITY MICROFINANCE</title>
<meta name="theme-color" content="#0d6efd">
<style>
body{
margin:0;
font-family:Arial, sans-serif;
background:#f8fbff;
display:flex;
align-items:center;
justify-content:center;
min-height:100vh;
color:#0f172a;
}
.box{
max-width:420px;
background:#fff;
padding:30px;
border-radius:20px;
box-shadow:0 15px 40px rgba(0,0,0,.08);
text-align:center;
}
.icon{
font-size:60px;
margin-bottom:15px;
}
h1{
margin:0 0 10px;
font-size:28px;
}
p{
color:#64748b;
line-height:1.7;
}
a{
display:inline-block;
margin-top:15px;
text-decoration:none;
background:#0d6efd;
color:#fff;
padding:12px 20px;
border-radius:999px;
font-weight:bold;
}
</style>
</head>
<body>
<div class="box">
<div class="icon">📡</div>
<h1>You are offline</h1>
<p>Internet connection is not available right now. Please reconnect and try again.</p>
<a href="index.php">Retry</a>
</div>
</body>
</html>
________________________________________
6) STEP 4: Tengeneza sw.js
Hii ndiyo service worker. Kazi yake ni:
• ku-cache files
• kusaidia pages kufunguka hata internet ikiwa imekatika
• kufanya website ionekane kama app
File: sw.js
const CACHE_NAME = 'sqm-pwa-v1';
const FILES_TO_CACHE = [
'/',
'/index.php',
'/manifest.json',
'/offline.html',
'/logo-header.png',
'/icons/icon-72x72.png',
'/icons/icon-96x96.png',
'/icons/icon-128x128.png',
'/icons/icon-144x144.png',
'/icons/icon-152x152.png',
'/icons/icon-192x192.png',
'/icons/icon-384x384.png',
'/icons/icon-512x512.png',
'/mikopologin.php',
'/mikopodashboard.php',
'https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css',
'https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js',
'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css',
'https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700;800&display=swap'
];
self.addEventListener('install', (event) => {
event.waitUntil(
caches.open(CACHE_NAME)
.then((cache) => {
return cache.addAll(FILES_TO_CACHE);
})
.then(() => self.skipWaiting())
);
});
self.addEventListener('activate', (event) => {
event.waitUntil(
caches.keys().then((cacheNames) => {
return Promise.all(
cacheNames.map((cache) => {
if (cache !== CACHE_NAME) {
return caches.delete(cache);
}
})
);
}).then(() => self.clients.claim())
);
});
self.addEventListener('fetch', (event) => {
if (event.request.method !== 'GET') return;
event.respondWith(
fetch(event.request)
.then((response) => {
const responseClone = response.clone();
caches.open(CACHE_NAME).then((cache) => {
cache.put(event.request, responseClone);
});
return response;
})
.catch(() => {
return caches.match(event.request).then((cachedResponse) => {
if (cachedResponse) {
return cachedResponse;
}
if (event.request.mode === 'navigate') {
return caches.match('/offline.html');
}
});
})
);
});
________________________________________
7) STEP 5: Tengeneza au badilisha index.php
Hii ndiyo page kuu ya app yako. Nimeweka version safi, yenye:
• logo yako kwenye navbar
• manifest
• install button
• service worker registration
• online/offline status
• PWA support
File: index.php
<?php
session_start();
/*
|--------------------------------------------------------------------------
| BASIC SETTINGS
|--------------------------------------------------------------------------
*/
$company_name = "STAR MICROFINANCE";
$dashboard_url = "mikopodashboard.php";
$login_url = "mikopologin.php";
$logout_url = "mikopologout.php";
$home_url = "faulink_logout.php";
$phone_number = "444444444444";
$phone_clean = "255746293637";
/*
|--------------------------------------------------------------------------
| SAFE URLS FOR META TAGS
|--------------------------------------------------------------------------
*/
$current_url = (
(isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off') ? 'https://' : 'http://'
) . ($_SERVER['HTTP_HOST'] ?? 'localhost') . ($_SERVER['REQUEST_URI'] ?? '');
$site_logo = "icons/icon-512x512.png";
/*
|--------------------------------------------------------------------------
| OPTIONAL REDIRECT IF LOGGED IN
|--------------------------------------------------------------------------
*/
if (isset($_SESSION['user_id']) && !isset($_GET['stay'])) {
header("Location: " . $dashboard_url);
exit;
}
?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title><?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?> | Trusted Microfinance Services</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
<!-- SEO -->
<meta name="description" content="<?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?> offers fast, secure, and reliable microfinance services.">
<meta name="keywords" content="microfinance, loans, Tanzania loans, repayment management, <?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?>">
<meta name="author" content="<?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?>">
<meta name="robots" content="index, follow">
<!-- PWA -->
<meta name="theme-color" content="#0d6efd">
<meta name="mobile-web-app-capable" content="yes">
<meta name="application-name" content="<?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?>">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-title" content="<?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?>">
<meta name="apple-mobile-web-app-status-bar-style" content="default">
<link rel="manifest" href="manifest.json">
<link rel="apple-touch-icon" href="icons/icon-192x192.png">
<link rel="icon" type="image/png" sizes="192x192" href="icons/icon-192x192.png">
<link rel="icon" type="image/png" sizes="512x512" href="icons/icon-512x512.png">
<!-- Open Graph -->
<meta property="og:title" content="<?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?> | Trusted Microfinance Services">
<meta property="og:description" content="Fast approval, secure lending, and simple loan management for individuals and businesses.">
<meta property="og:type" content="website">
<meta property="og:url" content="<?php echo htmlspecialchars($current_url, ENT_QUOTES, 'UTF-8'); ?>">
<meta property="og:image" content="<?php echo htmlspecialchars($site_logo, ENT_QUOTES, 'UTF-8'); ?>">
<!-- CSS -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css" rel="stylesheet">
<style>
:root{
--primary:#0d6efd;
--primary-dark:#0a4fb3;
--accent:#00c2a8;
--dark:#0f172a;
--muted:#64748b;
--shadow:0 15px 45px rgba(15, 23, 42, 0.12);
}
body{
font-family:Arial, sans-serif;
background:linear-gradient(180deg,#f8fbff 0%,#eef5ff 100%);
color:var(--dark);
margin:0;
padding:0;
}
.navbar{
background:#fff;
box-shadow:0 10px 30px rgba(0,0,0,0.05);
}
.navbar-brand{
font-weight:800;
font-size:1.2rem;
color:var(--dark)!important;
text-decoration:none;
}
.nav-btn{
border-radius:999px;
padding:10px 20px;
font-weight:600;
}
.btn-main{
background:linear-gradient(135deg,var(--primary),var(--primary-dark));
color:#fff;
border:none;
}
.btn-main:hover{
color:#fff;
}
.btn-soft{
border:1px solid rgba(13,110,253,.15);
background:#fff;
color:var(--primary);
}
.hero{
padding:90px 0 70px;
}
.hero-card{
background:#fff;
border-radius:28px;
box-shadow:var(--shadow);
padding:45px;
}
.section{
padding:70px 0;
}
footer{
background:#0b1220;
color:#fff;
padding:35px 0 20px;
margin-top:50px;
}
.install-btn-wrap{
position:fixed;
right:18px;
bottom:18px;
z-index:9999;
}
#installAppBtn{
display:none;
border:none;
border-radius:999px;
padding:14px 18px;
font-weight:700;
box-shadow:0 10px 35px rgba(13,110,253,.30);
}
.offline-badge{
position:fixed;
left:18px;
bottom:18px;
z-index:9999;
display:none;
background:#dc3545;
color:#fff;
padding:10px 16px;
border-radius:999px;
font-weight:700;
}
</style>
</head>
<body>
<nav class="navbar navbar-expand-lg sticky-top">
<div class="container py-2 d-flex justify-content-between align-items-center">
<a class="navbar-brand d-flex align-items-center gap-3" href="#">
<img src="logo-header.png" alt="<?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?>" style="height:56px; width:auto; border-radius:10px;">
<div>
<div><?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?></div>
<small class="text-muted fw-semibold">Trusted Financial Growth Partner</small>
</div>
</a>
<div class="d-flex gap-2">
<a href="<?php echo htmlspecialchars($login_url, ENT_QUOTES, 'UTF-8'); ?>" class="btn btn-main nav-btn">
Login
</a>
<a href="#contact" class="btn btn-soft nav-btn">
Contact
</a>
</div>
</div>
</nav>
<section class="hero">
<div class="container">
<div class="hero-card">
<h1>Welcome to <?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?></h1>
<p>
We provide simple, fast, and professional microfinance services for individuals,
entrepreneurs, and growing businesses.
</p>
<div class="d-flex flex-wrap gap-3 mt-4">
<a href="<?php echo htmlspecialchars($login_url, ENT_QUOTES, 'UTF-8'); ?>" class="btn btn-main">Login Now</a>
<a href="<?php echo htmlspecialchars($dashboard_url, ENT_QUOTES, 'UTF-8'); ?>" class="btn btn-soft">Open Dashboard</a>
</div>
</div>
</div>
</section>
<section class="section" id="contact">
<div class="container">
<h2>Contact & Support</h2>
<p>Reach out quickly for inquiries, loan guidance, and customer support.</p>
<a href="tel:<?php echo htmlspecialchars($phone_number, ENT_QUOTES, 'UTF-8'); ?>" class="btn btn-soft">
<?php echo htmlspecialchars($phone_number, ENT_QUOTES, 'UTF-8'); ?>
</a>
<a href="https://wa.me/<?php echo htmlspecialchars($phone_clean, ENT_QUOTES, 'UTF-8'); ?>" class="btn btn-success" target="_blank" rel="noopener">
WhatsApp
</a>
</div>
</section>
<footer>
<div class="container text-center">
© <?php echo date("Y"); ?> <?php echo htmlspecialchars($company_name, ENT_QUOTES, 'UTF-8'); ?>. All Rights Reserved.
</div>
</footer>
<div class="install-btn-wrap">
<button id="installAppBtn" class="btn btn-main">
Install App
</button>
</div>
<div id="offlineBadge" class="offline-badge">
You are offline
</div>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
<script>
let deferredPrompt;
const installBtn = document.getElementById('installAppBtn');
const offlineBadge = document.getElementById('offlineBadge');
window.addEventListener('beforeinstallprompt', (e) => {
e.preventDefault();
deferredPrompt = e;
installBtn.style.display = 'inline-block';
});
installBtn.addEventListener('click', async () => {
if (!deferredPrompt) {
alert('Install option not available yet.');
return;
}
deferredPrompt.prompt();
const { outcome } = await deferredPrompt.userChoice;
if (outcome === 'accepted') {
console.log('User accepted install');
} else {
console.log('User dismissed install');
}
deferredPrompt = null;
installBtn.style.display = 'none';
});
window.addEventListener('appinstalled', () => {
console.log('PWA installed');
installBtn.style.display = 'none';
});
function updateOnlineStatus() {
if (navigator.onLine) {
offlineBadge.style.display = 'none';
} else {
offlineBadge.style.display = 'block';
}
}
window.addEventListener('online', updateOnlineStatus);
window.addEventListener('offline', updateOnlineStatus);
updateOnlineStatus();
if ('serviceWorker' in navigator) {
window.addEventListener('load', () => {
navigator.serviceWorker.register('sw.js')
.then((reg) => {
console.log('Service worker registered:', reg.scope);
})
.catch((err) => {
console.error('Service worker failed:', err);
});
});
}
</script>
</body>
</html>
________________________________________
8) STEP 6: Upload files zote kwenye hosting
Baada ya kutengeneza mafaili hayo, upload kwenye hosting au localhost.
Upload hizi:
• index.php
• manifest.json
• sw.js
• offline.html
• logo-header.png
• folder icons
________________________________________
9) STEP 7: Hakikisha website ni HTTPS
PWA nyingi hazifanyi kazi vizuri bila HTTPS.
Inatakiwa iwe hivi:
https://yourdomain.com/
Si vizuri kuwa:
http://yourdomain.com/
Kama uko localhost kwa majaribio:
http://localhost/project/
inaweza kufanya kazi kwa testing.
Lakini production ni lazima karibu iwe HTTPS.
________________________________________
10) STEP 8: Test kama PWA imekubali
Fungua website yako kwenye Chrome.
Bonyeza:
• F12
• nenda Application
• angalia sehemu ya:
o Manifest
o Service Workers
Angalia vitu hivi:
• manifest inasoma vizuri
• icons zinaonekana
• service worker registered
• hakuna error nyekundu
Halafu refresh page.
Ukiona browser imekubali, utaona:
• button ya Install App
au
• menu ya browser itasema Install app
________________________________________
11) STEP 9: Jinsi ya kuinstall kwenye simu
Android
• fungua site kwenye Chrome
• utaona Install App au Add to Home Screen
• bonyeza install
Desktop
• fungua site kwenye Chrome au Edge
• upande wa address bar kuna install icon
• bonyeza install
________________________________________
12) STEP 10: Ukiwa na system nyingine utabadili nini tu
Hii guide unaweza kuitumia tena kwa system nyingine yoyote. Unachobadilisha ni vitu hivi tu:
A. Jina la kampuni
Ndani ya index.php:
$company_name = "JINA LA COMPANY YAKO";
Na ndani ya manifest.json:
"name": "JINA LA COMPANY YAKO",
"short_name": "APP NAME"
B. Start URL
Kama system yako si index.php, badilisha:
"start_url": "/dashboard.php"
au
"start_url": "/school/index.php"
C. Scope
Kama system ipo ndani ya folder, mfano /school/, badilisha:
"scope": "/school/"
D. Pages za cache
Ndani ya sw.js, badilisha:
'/mikopologin.php',
'/mikopodashboard.php',
ziwe pages zako halisi, mfano:
'/login.php',
'/dashboard.php',
'/students.php',
'/reports.php'
E. Logo
Badilisha:
• logo-header.png
• icons kwenye folder icons
________________________________________
13) Mfano kama system ipo subfolder
Mfano project yako ipo hapa:
https://example.com/mikopo/
Basi manifest.json iwe hivi:
{
"name": "STAR QUALITY MICROFINANCE",
"short_name": "SQM App",
"start_url": "/mikopo/index.php",
"scope": "/mikopo/",
"display": "standalone",
"background_color": "#f8fbff",
"theme_color": "#0d6efd",
"icons": [
{
"src": "icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}
Na sw.js badilisha paths ziwe:
const FILES_TO_CACHE = [
'/mikopo/',
'/mikopo/index.php',
'/mikopo/manifest.json',
'/mikopo/offline.html',
'/mikopo/logo-header.png',
'/mikopo/icons/icon-192x192.png',
'/mikopo/icons/icon-512x512.png',
'/mikopo/mikopologin.php',
'/mikopo/mikopodashboard.php'
];
Na kwenye index.php service worker registration iwe:
navigator.serviceWorker.register('/mikopo/sw.js')
________________________________________
14) Jinsi ya kufanya system yoyote ya PHP iwe PWA kwa formula rahisi
Kila system yoyote ukitaka kuigeuza PWA, fanya checklist hii:
Checklist
• tengeneza manifest.json
• tengeneza sw.js
• tengeneza offline.html
• weka icons
• weka <link rel="manifest">
• weka theme-color
• register service worker
• tumia HTTPS
• test kwenye Chrome Application tab
________________________________________
15) Makosa ya kawaida na solution zake
Tatizo 1: Install button haitokei
Sababu:
• hakuna HTTPS
• manifest haipo sawa
• icon moja au zaidi haipo
• service worker hajaregister
• browser bado haijakubali installability
Solution:
• angalia DevTools → Application
• angalia Console errors
• hakikisha manifest.json na sw.js vinafunguka moja kwa moja kwenye browser
________________________________________
Tatizo 2: Inaonyesha icon ya zamani
Sababu:
• browser cache
Solution:
• hard refresh
• clear site data
• badilisha cache name kwenye sw.js
Mfano:
const CACHE_NAME = 'sqm-pwa-v2';
________________________________________
Tatizo 3: Offline page haifunguki
Sababu:
• offline.html haiko kwenye cache
• path si sahihi
Solution:
• hakikisha ipo ndani ya FILES_TO_CACHE
________________________________________
Tatizo 4: Manifest haifunguki
Jaribu kufungua browser:
https://yourdomain.com/manifest.json
Ikiwa haifunguki, basi file path ni mbaya au haijauploadiwa.
________________________________________
Tatizo 5: Service worker error
Jaribu kufungua:
https://yourdomain.com/sw.js
Ikiwa haifunguki, browser hawezi ku-register.
________________________________________
16) Version fupi ya files muhimu kwa system nyingine yoyote
Minimum files unazohitaji
• index.php
• manifest.json
• sw.js
• offline.html
• icons/
Hizi tano tu zinatosha kuanza.
________________________________________
17) Mpangilio wa kutumia kwenye mifumo yote ya baadaye
Ukitaka kutumia hii guide kwa project nyingine:
• copy manifest.json
• copy sw.js
• copy offline.html
• copy folder icons
• paste kwenye project mpya
• badilisha jina la company
• badilisha start_url
• badilisha pages zinazocache
• badilisha logo
Basi system mpya nayo inakuwa PWA.
________________________________________
18) Files zako za kuanzia zipo tayari
Tumia hizi nilizokwishaandaa:
• Pakua PWA icons zip
• Pakua logo ya kawaida PNG
• Pakua logo ya header
Logo imetokana na file yako ya PDF yenye maandishi ya Star Quality Microfinance CO. Limited na muonekano wa nyekundu na nyeusi.
________________________________________
19) Hatua ya haraka kabisa ukitaka leo ifanye kazi
Fanya hizi tu:
1. pakua icons zip
2. weka folder icons
3. weka logo-header.png
4. tengeneza manifest.json
5. tengeneza sw.js
6. tengeneza offline.html
7. replace index.php na code niliyokupa
8. upload kwenye HTTPS
9. open site kwa Chrome
🚀 Unahitaji mfumo au website ya biashara?
Chagua huduma hapa chini kisha mteja bofya moja kwa moja kwenda kwenye ukurasa wa huduma au kuwasiliana nasi kwa WhatsApp.