Nodus Works olarak Shopify'ın yeni müşteri hesapları (Customer Accounts) deneyimine sıfırdan tam sayfa bir UI extension eklerken edindiğimiz birinci elden tecrübeyi bu rehberde paylaşıyoruz. Kurulumdan canlıya almaya kadar olan yolu, yol boyunca karşılaştığımız gerçek hataları ve bu hataları nasıl çözdüğümüzü kod örnekleriyle anlatıyoruz. Bu rehber, üretim ortamında bir tam sayfa müşteri hesabı extension'ını sıfırdan canlıya alırken edindiğimiz doğrudan deneyime dayanıyor.
Neden Tam Sayfa Bir UI Extension Gerekir?
Shopify'ın yeni müşteri hesapları Siparişler, Profil ve Adresler gibi hazır sayfalarla gelir; sadakat programı, istek listesi, abonelik yönetimi veya kendi başına duran bir "etki paneli" gibi senaryolarda bu hazır bloklar yetmez. Shopify bu ihtiyacı, customer-account.page.render hedefini (target) kullanan tam sayfa UI extension'larıyla çözer.
UI Extension ve Target Kavramları Nedir?
UI Extension, müşteri hesabı arayüzünün belirli noktalarına kod enjekte eden modüldür; target ise bu kodun nereye yerleşeceğini belirler. Blok hedefler mevcut sayfalara eklenirken, tam sayfa hedefi tamamen yeni bir rota oluşturur. Aşağıdaki tablo iki target türü arasındaki farkı özetliyor.
Kritik Not: Bir tam sayfa hedefi, aynı extension içindeki başka hiçbir hedefle birlikte yaşayamaz. Tam sayfanız için ayrı bir extension oluşturmanız gerekir; mevcut bir blok extension'ın içine tam sayfa target'ı eklemeyi denemek yapılandırma hatasına yol açar.
Adım Adım Kurulum: Extension Nasıl Oluşturulur?
Extension oluşturmak iki dosyayı gerektirir: yapılandırma dosyası ve sayfa bileşeni. Tam sayfa hedefi tek başına bir extension içinde tanımlanmalıdır.
api_version = "2026-04"
[[extensions]]
name = "Impact Page"
handle = "impact-page"
type = "ui_extension"
[[extensions.targeting]]
module = "./src/FullPage.jsx"
target = "customer-account.page.render"
Ardından minimal bir sayfa bileşeni tanımlanır. Kritik nokta şudur: standart HTML değil, Shopify'ın sağladığı web bileşenlerini (s-page, s-section, s-grid gibi) kullanmak zorunludur. Host, izin verilmeyen bir düğüm gördüğünde tüm sayfayı reddeder.
import "@shopify/ui-extensions/preact";
import { render } from "preact";
export default () => {
render(<MyPage />, document.body);
};
function MyPage() {
return (
<s-page heading="Impact">
<s-section>
<s-text>Yükleniyor…</s-text>
</s-section>
</s-page>
);
}
Extension Nasıl Canlıya Alınır (Deploy)?
Extension kodu kendi sunucunuzda barınmaz; shopify app deploy komutunu çalıştırdığınızda Shopify kodu derler ve kendi altyapısında sunar.
shopify app deploy
Komut "yeni sürümü yayınla?" diye sorar; onayladığınızda extension yayına girer. Buraya kadar her şey dokümantasyona uygun ilerler; asıl öğretici kısım deploy sonrasında başlıyor.
Hesabım Sayfası Altında Yeni Sayfa Nasıl Oluşturulur? (Aktivasyon Adımları)
Tam sayfa extension'ı deploy etmek, sayfayı "Hesabım" (Customer Accounts) menüsünde görünür ve çalışır hale getirmez; sayfanın aktifleşmesi için onu müşteri hesapları editöründen ayrıca eklemeniz gerekir. Bu adım, deploy sürecinden tamamen bağımsız, ayrı bir işlemdir.
- Yönetim paneli → Settings (Ayarlar) → Customer accounts (Müşteri hesapları)'na gidin.
- Sağ üstte Customize'a tıklayın; tema editörüne benzer bir editör açılır.
- Editörde uygulama/extension ekleme bölümünden ilgili tam sayfa extension'ı ekleyin.
- Editör sizi otomatik olarak başlık menüsüne ekleme için yönlendirir; onaylayın.
- Save / Publish ile yayınlayın.
Uzak Durulması Gereken Risk: Extension'ı yalnızca deploy edip navigasyon menüsüne manuel link eklemek yeterli değildir. Sayfa, müşteri hesapları editöründen eklenip aktive edilmeden "There's a problem loading this page" hatası vermeye devam eder; bu iki adım (deploy ve aktivasyon) birbirinden bağımsızdır.
"There's a Problem Loading This Page" Hatası Neden Çıkar?
Bu hata, extension başarıyla deploy edilse ve navigasyon menüsüne link eklense bile, yukarıdaki aktivasyon adımı atlandığında ortaya çıkar; en çok vakit kaybettiren sorun budur. Tarayıcı konsolunda extension'a ait bir JavaScript hatası bulunmaz, yalnızca analytics ve CSP kaynaklı, konuyla ilgisiz uyarılar görülür. Bu durum, sorunun render aşamasında değil, sayfanın çözümlenmesinde (resolution) olduğunu gösterir.
Sık Karşılaşılan Diğer Hatalar ve Yanlış Teşhisler
Deploy ve aktivasyon dışında, teşhis sürecinde zaman kaybettiren dört durum daha var. Aşağıdaki tablo her durumun gerçek nedenini ve doğru teşhis yaklaşımını özetliyor.
Doğru teşhis için minimal bir "hello world" sayfaya inip sorunun kodda değil aktivasyonda olduğunu kanıtlamak, en hızlı yoldur.
Mağaza Sahibi İçin Self-Servis İçerik Yönetimi
Sayfa çalışmaya başladıktan sonraki doğal adım, metinleri geliştiriciye ihtiyaç duymadan mağaza sahibinin düzenleyebilmesi için extension ayarlarına taşımaktır. Alanlar yapılandırma dosyasında tanımlanır.
[extensions.settings]
[[extensions.settings.fields]]
key = "heading"
type = "single_line_text_field"
name = "Sayfa başlığı"
[[extensions.settings.fields]]
key = "intro"
type = "multi_line_text_field"
name = "Giriş metni"
Kod tarafında bu değerler bir signal üzerinden okunur ve gerçek zamanlı güncellenir; alan boşsa kodda tanımlı varsayılan devreye girer.
const settings = globalThis.shopify?.settings?.current ?? {};
const heading = settings.heading?.trim() || "Varsayılan başlık";
Bu yapı sayesinde günlük metin değişiklikleri editörden self-servis yapılabilir; yalnızca yapısal değişiklikler için yeni bir deploy gerekir.
Mimari: Ayrı Bir Backend Sunucusu Gerekir mi?
Hayır, tam sayfa UI extension'lar için ayrı bir backend veya hosting gerekmez. Deploy ettiğinizde Shopify kodu derler ve kendi CDN'inde sunar; sayfa müşteri hesabı deneyiminin içinde, mağazanın markasıyla uyumlu şekilde çalışır. Bakım maliyeti, geleneksel bir uygulama sunucusuna kıyasla belirgin şekilde düşüktür çünkü sunucu kapasitesi planlamaya, güncellemeye veya izlemeye ihtiyaç kalmaz.
Hızlı Kontrol Listesi
- Tam sayfa hedefi için ayrı bir extension oluşturun.
- Yalnızca resmi web bileşenlerini kullanın; standart HTML kullanmayın.
- shopify app deploy ile yeni sürümü yayınlayın.
- Sayfayı mutlaka müşteri hesapları editöründen ekleyip aktive edin; yalnızca menüye link koymak yetmez.
- Menü linkini elle yazmayın, editör/seçiciden uygulama sayfası olarak seçin.
- Konsoldaki analytics/CSP gürültüsünü gerçek hatadan ayırın.
- Metinleri settings alanlarına taşıyarak içerik yönetimini mağaza sahibine bırakın.
Bu tür özel UI extension geliştirmeleri, standart tema özelleştirmesinin ötesinde kod seviyesinde bir entegrasyon çalışmasıdır; Shopify entegrasyon çözümleri hizmetimiz müşteri hesapları gibi platform seviyesindeki özelleştirmeleri, deploy ve aktivasyon adımlarını da kapsayacak şekilde uçtan uca yönetir. Yayına aldıktan sonra "problem loading page" gibi hataların hızlı teşhisi için Shopify teknik destek ve bakım hizmetimiz saha deneyimiyle devreye girer.
Sıkça Sorulan Sorular
"There's a problem loading this page" hatası ne anlama gelir?
Extension başarıyla deploy edilmiş olsa bile, sayfa müşteri hesapları editöründen eklenip aktive edilmediyse bu hata çıkar. Deploy etmek ve aktive etmek birbirinden bağımsız iki adımdır; yalnızca ilkini yapmak yetmez.
Tam sayfa extension ile blok extension arasındaki fark nedir?
Blok extension mevcut bir sayfaya (Sipariş, Profil vb.) eklenen küçük bir bileşendir ve aynı extension içinde başka hedeflerle birlikte olabilir. Tam sayfa extension ise customer-account.page.render hedefiyle bağımsız yeni bir rota oluşturur ve ayrı bir extension gerektirir.
Tam sayfa extension için ayrı bir backend sunucusu kurmam gerekir mi?
Hayır. Shopify, deploy edilen kodu kendi CDN'inde derleyip sunar. Ayrı bir hosting veya sunucu yönetimi gerekmez, bakım yükü geleneksel bir uygulama sunucusuna göre belirgin şekilde azalır.
Menü linkini nasıl eklemeliyim?
Linki elle yazmayın; navigasyon menüsüne elle eklenen bir /pages/<id> adresi çözülemeyen bir bağlantıya işaret eder. Doğru adres, müşteri hesapları editöründeki uygulama sayfası seçicisi tarafından otomatik üretilir.
Sayfa metinlerini deploy etmeden değiştirebilir miyim?
Evet, metinler single_line_text_field ve multi_line_text_field gibi settings alanlarına taşındıysa mağaza sahibi bu metinleri editörden değiştirebilir. Yalnızca yapısal (bileşen, mantık) değişiklikler yeni bir deploy gerektirir.
Sonuç
Shopify'ın yeni müşteri hesaplarına tam sayfa bir deneyim eklemek teknik olarak basit görünse de, gerçek dünyada en çok zamanı "deploy ettim ama açılmıyor" sorunu alıyor. Kilit ders şudur: tam sayfa extension'ı yayınlamak ile onu müşteri hesapları editöründen aktive etmek iki ayrı adımdır. Bunu bir kez kavradığınızda, bileşen seçimi, deploy akışı ve metinleri düzenlenebilir yapma gibi geri kalan her şey net ve tekrarlanabilir bir sürece dönüşür. Shopify zaman zaman arayüz ve sürüm detaylarını güncelleyebilir; bu nedenle bu rehberi resmi dokümantasyonla birlikte değerlendirmenizi öneririz.
Kendi Shopify mağazanızda müşteri hesapları için özel bir sayfa geliştirmek veya mevcut bir extension'da benzer bir aktivasyon sorununu çözmek isterseniz, entegrasyon çözümleri hizmetimiz hakkında ekibimizle iletişime geçebilirsiniz.
