Web App Manifest (manifest.json) Nedir? Yapılandırma ve PWA Entegrasyon Rehberi

Web platformu gün geçtikçe yerel (native) mobil ve masaüstü uygulamalarının sunduğu deneyime daha fazla yakınlaşıyor. Bu dönüşümün merkezinde ise tarayıcılara web sitenizin tıpkı yerel bir uygulama gibi davranması gerektiğini söyleyen JSON tabanlı yapılandırma dosyaları yer alıyor. İşte bu noktada Web App Manifest devreye girer. Bir web sitesini Progressive Web App (PWA) haline getiren en kritik bileşenlerden biri olan manifest.json dosyası, uygulamanızın cihaza nasıl yükleneceğini, ana ekranda nasıl görüneceğini, hangi açılış ekranına sahip olacağını ve kullanıcıya nasıl bir pencere düzeni sunacağını belirler.

Eğer daha önce Progressive Web App (PWA) Nedir? Web Siteleri İçin PWA Kurulum Rehberi başlıklı rehberimize göz attıysanız, PWA ekosisteminin üç temel sacayağı olduğunu bilirsiniz: Service Worker, HTTPS altyapısı ve Web App Manifest. Bu rehberde, manifest.json dosyasını sıfırdan oluşturmayı, gelişmiş yapılandırma parametrelerini, ikon yönetimini ve 2026 web standartlarında en çok karşılaşılan entegrasyon hatalarının nasıl çözüleceğini detaylıca inceleyeceğiz.

Web App Manifest (manifest.json) Nedir ve Neden Kritik Önem Taşır?

Web App Manifest, web uygulamanızın metadatasını içeren, JSON formatında yazılmış deklaratif bir yapılandırma dosyasıdır. W3C tarafından standartlaştırılan bu spesifikasyon, tarayıcılara web uygulamasının mobil ve masaüstü işletim sistemleriyle doğrudan etkileşim kurması için gerekli bilgileri sağlar.

PWA manifest dosyası bulunmayan bir web sitesi, mobil tarayıcıda kullanıcı tarafından yalnızca sıradan bir "yer imi" (bookmark) olarak eklenebilir. Ancak doğru yapılandırılmış bir manifest.json dosyası sayesinde kullanıcınız sitenizi cihazına yüklediğinde:

• Uygulama simgesi cihazın ana ekranında, uygulama çekmecesine veya masaüstü görev çubuğuna tıpkı yerel bir uygulama gibi yerleşir.
• Uygulama, adres çubuğu veya sekme yapısı olmadan bağımsız bir pencerede (standalone) çalışır.
• Cihazın açılış ekranı (splash screen) otomatik olarak marka renklerinizle oluşturulur.
• Ekran yönelimi (dikey/yatay) ve tema renkleri işletim sistemi seviyesinde kontrol edilebilir.

Günümüzde Chromium tabanlı tarayıcılar (Chrome, Edge, Brave), Safari ve Firefox gibi modern tarayıcılar Web App Manifest standartlarını geniş ölçüde desteklemektedir. Responsive Web Tasarım Rehberi: Mobil Öncelikli Yaklaşım ilkelerini uyguladığınız projelerde manifest dosyası kullanmak, kullanıcı tutundurma (retention) oranlarını gözle görülür şekilde artırır.

manifest.json İçerisindeki Temel Parametreler ve Anlamları

Bir manifest dosyasının tarayıcılar tarafından eksiksiz tanınması ve "Yüklenebilir" (Installable) statüsü kazanması için belirli anahtar-değer çiftlerine ihtiyacı vardır. Gelin bu parametreleri kategori kategori inceleyelim:

1. Kimlik ve Ad Tanımlamaları (id, name, short_name)

• name: Uygulamanızın tam adıdır. Yükleme isteminde (install prompt), uygulama mağazası benzeri dizinlerde ve cihaz ayarlarındaki uygulama bilgisi alanında görünür.
• short_name: Kullanıcının ana ekranında veya kısıtlı alana sahip simge altlarında görünecek kısa addır. Alan taşmalarını önlemek için 12 karakteri geçmemesi tavsiye edilir.
• id: Modern PWA standartlarında uygulamanın benzersiz kimliğidir. Genellikle / veya uygulamanın kök URL'si verilir. id belirtilmediğinde tarayıcı start_url değerini ID kabul eder; ancak start_url gelecekte değişirse tarayıcı uygulamayı tamamen yeni bir uygulama gibi algılayabilir.

2. Başlatma ve Kapsam Ayarları (start_url, scope, display)

• start_url: Uygulama ana ekrandan başlatıldığında kullanıcının karşılaştığı ilk URL'dir. Analytics araçlarında PWA trafiğini ayırt edebilmek için /?utm_source=pwa şeklinde parametre eklemek yaygın bir pratiktir.
• scope: Manifest'in geçerli olduğu URL alanını sınırlar. Örneğin scope değeri /app/ olarak ayarlanırsa, kullanıcı /app/dashboard sayfasındayken PWA sınırları içerisindedir; ancak /blog adresine gittiğinde uygulama tarayıcı görünümüne geçebilir.
• display: Uygulamanın pencere düzenini belirler. Dört farklı mod desteklenir:
- fullscreen: Tüm ekranı kaplar, durum çubuğu (status bar) dahil tüm işletim sistemi arayüzü gizlenir (oyunlar için idealdir). - standalone: Yerel bir uygulama hissi verir. Tarayıcı adres çubuğu gizlenir ancak cihazın pil/saat çubuğu görünür kalır. - minimal-ui: Tarayıcı kontrol düğmeleri (geri, yenile) kısıtlı bir üst barda sunulur. - browser: Standart tarayıcı sekmesi görünümüdür.

3. Görsel ve Tema Özellikleri (background_color, theme_color, icons)

• background_color: Uygulama açılırken gösterilen varsayılan splash screen arka plan rengidir.
• theme_color: İşletim sisteminin durum çubuğunun veya pencere başlığının alacağı renktir.
• icons: Farklı ekran çözünürlükleri için hazırlanmış simge dizisidir.

Örnek bir temel manifest.json yapılandırması:

{
  "id": "/?pwa_app",
  "name": "WebTeknoloji Yazılım Rehberi",
  "short_name": "WebTeknoloji",
  "description": "Güncel yazılım, hosting ve web teknolojileri rehberi.",
  "start_url": "/?utm_source=pwa",
  "scope": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0055ff",
  "orientation": "portrait-primary",
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-maskable-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

Web App Manifest Entegrasyonu ve İkon Yönetimi

Manifest dosyanızı projenizin kök dizinine ekledikten sonra, tarayıcının bu dosyayı algılayabilmesi için web sitenizin <head> bölümüne aşağıdaki bağlama etiketini eklemelisiniz:

<link rel="manifest" href="/manifest.json">

iOS (Safari) cihazlarda tam uyumluluk sağlamak adına ek meta etiketlerinin kullanımı halen büyük önem taşır:

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<meta name="apple-mobile-web-app-title" content="WebTeknoloji">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">
<meta name="theme-color" content="#0055ff">

İkon Türleri ve Maskable Icons Mantığı

PWA simgelerinde purpose parametresi kritik bir rol oynar. Android ve diğer işletim sistemleri ikonları daire, yuvarlatılmış kare veya damla şeklinde kırpabilir. Bu kırpma işlemi sırasında logonuzun bozulmaması veya kenarlarının kesilmemesi için Maskable Icon standardı geliştirilmiştir.

• purpose: "any": İkonun arka planı şeffaf olabilir. Standart uygulama simgesi olarak kullanılır.
• purpose: "maskable": İkonun etrafında güvenli alan (safe zone) bırakılmıştır. İşletim sistemi ikonu hangi şekilde kırparsa kırpsın logonuz tam ortalanmış görünür.

Gelişmiş Web App Manifest Özellikleri

Modern Web App Manifest spesifikasyonu artık sadece temel bilgiler sunmanın ötesine geçmiştir. Masaüstü ve mobil platformlarda derin entegrasyon sağlayan ileri seviye özellikler şunlardır:

1. Uygulama Kısayolları (Shortcuts API)

Kullanıcı uygulama simgesine uzun bastığında (mobil) veya sağ tıkladığında (masaüstü) açılan hızlı erişim menüsünü tanımlamanızı sağlar:

"shortcuts": [
  {
    "name": "Son Yazılar",
    "short_name": "Yazılar",
    "description": "En güncel yazılım makalelerine göz atın",
    "url": "/blog?utm_source=pwa_shortcut",
    "icons": [{ "src": "/icons/shortcut-blog.png", "sizes": "192x192" }]
  },
  {
    "name": "Arama Yap",
    "short_name": "Arama",
    "url": "/search",
    "icons": [{ "src": "/icons/shortcut-search.png", "sizes": "192x192" }]
  }
]

2. Uygulama Önizleme Görselleri (Screenshots)

Chrome ve Edge gibi tarayıcıların zengin yükleme arayüzlerinde (rich install prompt) uygulamanızın ekran görüntülerini sergilemesini sağlar:

"screenshots": [
  {
    "src": "/screenshots/desktop-1.png",
    "sizes": "1280x720",
    "type": "image/png",
    "form_factor": "wide",
    "label": "Masaüstü Ana Sayfası"
  },
  {
    "src": "/screenshots/mobile-1.png",
    "sizes": "750x1334",
    "type": "image/png",
    "form_factor": "narrow",
    "label": "Mobil Uygulama Görünümü"
  }
]

3. Dosya Yöneticisi Entegrasyonu (File Handlers)

Web uygulamanızın işletim sistemi üzerinde belirli dosya uzantılarını (örneğin .json, .txt, .pdf) doğrudan açabilmesine imkan tanır:

"file_handlers": [
  {
    "action": "/open-file",
    "accept": {
      "text/plain": [".txt"],
      "application/json": [".json"]
    }
  }
]

manifest.json Hata Ayıklama (Debugging) ve Sık Yapılan Hatalar

Manifest dosyanızın düzgün çalışıp çalışmadığını anlamak için tarayıcıların geliştirici araçlarından yararlanabilirsiniz.

Chrome DevTools ile Test Etme

En Sık Yapılan 5 Manifest Hatası

Sonuç ve Sonraki Adımlar

Web App Manifest (manifest.json), modern web projelerinizi masaüstü ve mobil platformlarda birinci sınıf bir uygulama deneyimine dönüştürmenin en temel adımıdır. Doğru ikon boyutlandırmaları, id ve scope yapılandırması ve gelişmiş yetenekler (Shortcuts, Screenshots) sayesinde kullanıcılarınıza uygulama mağazalarına bağımlı kalmadan hızlı ve kesintisiz bir deneyim sunabilirsiniz.

Sonraki Adım: Sitenize manifest.json dosyasını ekledikten sonra, uygulamanızın tam anlamıyla çevrimdışı çalışabilmesi ve önbellekleme yapabilmesi için Progressive Web App (PWA) Nedir? Web Siteleri İçin PWA Kurulum Rehberi rehberimizden faydalanarak Service Worker mimarinizi tamamlayın.