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

________________________________________
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

________________________________________
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

• 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