Shopify Metafields: Kurulum ve Görüntüleme Rehberi

Shopify metafield, bir mağaza kaynağına (ürün, koleksiyon, sipariş, müşteri, varyant vb.) bağladığınız ve Shopify'ın temel şemasının yerel olarak sağlamadığı verileri depolamak için kullandığınız özel bir anahtar-değer alanıdır. Veri türünü tanımlarsınız, doğrulamayı zorunlu kılarsınız ve ardından değeri her yerde gösterebilirsiniz: Liquid aracılığıyla vitrin, ShopifyQL aracılığıyla analitikler, Shopify Functions aracılığıyla ödeme veya GraphQL Admin API aracılığıyla harici sistemler. Bu üç adımlı döngü (tanımla, doldur, göster) ihtiyaç duyduğunuz bütün zihinsel modeldir.

Temel çıkarımlar

• Bir metafield üç şeyle tanımlanır: sahip kaynağı, ad alanı ve anahtar. Bu üçünden herhangi birini değiştirirseniz farklı bir alana başvurmuş olursunuz.
• Shopify'ın Spring '26 ve Summer '26 Sürümleri çeşitli metafield güncellemeleri getirmiştir: admin sayfalarında 50 adedine kadar alanı sabitleme, sepetten siparişlere taşınan metafields, envanter transferlerinde metafields ve ShopifyQL nokta-sözdizim filtreleme.
• Admin GraphQL API 2026-07 yayın adayı, ayrı bir metafieldsSet çağrısı olmadan envanter transferlerinde metafields'i doğrudan tanımlamanıza ve ayarlamanıza olanak sağlar.
• Bir tanım oluşturmak vitrinizde hiçbir şey görüntülemez. Yine de alanı tema editöründeki dinamik bir kaynakla bağlamanız veya Liquid'i kendiniz yazmanız gerekir.
• Standart tanımlar (bakım talimatları, malzemeler, beden, ISBN vb.) en hızlı yoldur çünkü bunlar önceden yapılandırılmış, tema uyumlu ve hazır olarak uygulama ile birlikte çalışabilir.

Shopify metafield tam olarak nedir?

Metafields, ürün veya koleksiyon gibi bir Shopify kaynağına ek bilgi eklemenizi sağlar. Veriler belirtimler, beden tabloları, indirilebilir belgeler, çıkış tarihleri, resimler veya parça numaraları olabilir. Her metafield, bir değeri türü bilgisiyle birlikte depolar ve sahip kaynağı, ad alanı ve anahtar tarafından tanımlanır.

Ad alanını klasör adı, anahtarı ise o klasörün içindeki dosya adı olarak düşünün. namespace: custom ve key: material ile bir ürün metafield'i, aynı ürün üzerinde yaşasalar bile namespace: specs ve key: material ile olanından tamamen farklıdır.

Üç sahiplik modeli

Sahipliği anlamak, istemediğiniz verilerin üzerine yanlışlıkla yazmanızı önler.

Tüccar tarafından sahip olunan metafields, ayrılmış olmayan herhangi bir ad alanı kullanır (örneğin custom, specs veya inventory). Yüklü tüm uygulamalar bunları okuyabilir ve yazabilir. Birden fazla uygulamanın tükettiği paylaşılan veriler için idealdir.

Uygulama tarafından sahip olunan metafields, ayrılmış $app ad alanı önekini kullanır. Sahip uygulama yapıyı ve değerleri kontrol eder, bunlar varsayılan olarak admin'de salt okunurdur. Bir uygulamanın bir veri parçasının yetkili kaynağı olduğu durumlarda kullanın.

Uygulama verileri metafields, belirli bir uygulama yüklemesine bağlıdır ve Shopify admin'den tamamen gizlidir. AppInstallation kaynağında yaşarlar ve yalnızca sahip uygulama tarafından GraphQL aracılığıyla veya Liquid'teki app nesnesi aracılığıyla erişilebilirler. Bunlar, hiçbir zaman tüccarların karşısına çıkmaması gereken iç uygulama durumu içindir.

Shopify ayrıca standart tanımlar gibi platform tarafından yönetilen alanlar için Shopify tarafından ayrılmış ad alanlarını (önek shopify--) tutar.

Metafield veri türleri: pratik harita

Shopify türleri kategorilere ayırır. Doğru türü seçmek önemlidir çünkü doğrulamayı zorunlu kılar, Liquid'in değeri nasıl oluşturduğunu kontrol eder ve hangi filtrelerin uygulanacağını belirler.

Metin

• single_line_text_field, ürün rozetleri, kısa etiketler, ISO kodları
• multi_line_text_field, malzeme listeleri, bakım talimatları (satır sonları korunur)
• rich_text, biçimlendirilen uzun form içerik (başlıklar, kalın, listeler); metafield_tag filtresi ile oluşturun

Sayılar ve ölçümler

• number_integer, number_decimal
• dimension, volume, weight, her biri bir sayısal değeri bir birimle eşleştirilmiş olarak depolar; ürün özellikleri ve nakliye kuralları için idealdir

Tarihler ve saatler

• date, date_time, başlatma tarihleri, son kullanma tarihleri, etkinlik zamanlamaları

Referanslar

• product_reference, collection_reference, page_reference, variant_reference, verileri çoğaltmadan bir kaynağı diğerine bağlayın
• metaobject_reference, bir metaobject girişine bağlantı kurun (aşağıya bakın)
• article_reference ve list.article_reference, 2025-10 API yayınında eklendi; ürünleri doğrudan blog yazılarına bağlamanıza olanak sağlayarak içerik odaklı ticaret ve SEO'yu etkinleştir

Diğer yararlı türler

• boolean, özellik bayrakları, "yeni geliş" geçişleri, satıştan gizle işaretçileri
• color, yerel örnekli destek ile hex tabanlı renk değerleri
• url, file_reference, indirilebilir PDF'ler, spesifikasyon sayfaları, videolar
• json, keyfi yapılandırılmış veriler; yararlı ama doğrulanması ve oluşturulması daha zordur

Liste türleri için herhangi bir skaler türün önüne list. ekleyin (örneğin, list.single_line_text_field). Bunlar Liquid'te diziler olarak oluşturulur ve bir alan birden fazla değeri tutabilir (malzeme listesi veya alma konumları seti) durumunda doğru seçimdir.

Bir önemli sınırlama: GraphQL Admin API kullanırken, metafield değeri her zaman beyan edilen türden bağımsız olarak dize olarak girilir ve depolanır. Shopify okumada tür zorlayıcılığını işler.

Metafield tanımları: neden önemlidir

API aracılığıyla ham bir metafield yazabilirsiniz (tanım yok) ancak tanımlar neredeyse her zaman doğru seçimdir. Bir metafield tanımı, o ad alanı-anahtar kombinasyonunun tüm değerlerinin takip etmesi gereken, veri türü ve doğrulama kısıtlamaları dahil olmak üzere bir şema oluşturur. Tanım ayrıca GraphQL Admin API, Storefront API ve Customer Account API'nin tamamında erişim izinlerini kontrol eder ve alanın admin filtreleme için veya koleksiyon koşulu olarak kullanılıp kullanılamayacağını belirler.

Tanımlarla oluşturmak şu anlama gelir:

• Admin UI desteği. Tanımlı alanlar, herhangi bir özel kod olmadan her ilgili kaynağın düzenleme sayfasında görünür.
• Doğrulama. Geçersiz değerler vitrinizi bozulmadan önce yakalanır.
• Filtreleme. Tanımlı bir alanı akıllı koleksiyon koşulu veya admin filtresi olarak kullanabilirsiniz.
• Tema editörü keşfi. Dinamik kaynak seçicileri yalnızca tanımlı alanları gösterir.

Standart tanımlar, ISBN numaraları, ürün malzemeleri ve bakım talimatları gibi yaygın kullanım durumları için önceden oluşturulmuş şemalardır. Bunları kullanmak, bu standart ad alanlarına başvuran uygulamalar ve temalar zaten bunları ek yapılandırma olmadan nasıl okuyacağını bilmesi anlamına gelir.

Adım adım: tanım oluşturun ve doldurun

Shopify admin'de (kod yok)

1. Ayarlar > Özel veriler'e gidin.
2. Kaynak türünü seçin (Ürünler, Müşteriler, Siparişler vb.).
3. Tanım ekle'yi tıklayın. Adını verin, içerik türünü seçin ve kaydedin.
4. Shopify'ın Spring '26 Sürümü itibarıyla, Ayarlar'da ilk olarak gezinmeden müşteriler, siparişler ve koleksiyon sayfalarından doğrudan metafields oluşturabilirsiniz.
5. Herhangi bir ürün (veya başka bir kaynak) açın ve değerleri doldurmak için Metafields bölümüne kaydırın.

Spring '26 ayrıca ürün, müşteri ve sipariş bölümlerinde 50'ye kadar metafield sabitleme yeteneğini tanıttı, böylece ekibiniz ayrı bir sayfaya tıklamadan en önemli alanları görebilir ve düzenleyebilir.

GraphQL Admin API aracılığıyla

Toplu işlemler veya otomatikleştirilmiş boru hatları için metafieldDefinitionCreate (şemayı oluşturmak için) ve ardından metafieldsSet (değerleri yazmak için) kullanın. metafieldsSet mutasyonu, çağrı başına maksimum 25 metafield ile, maksimum toplam istek yükü boyutu 10 MB ile izin verir ve işlem atomiktir: bir hata oluşursa hiçbir değişiklik devam etmez.

Minimal bir tanım mutasyonu şuna benzer:

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      namespace
    }
    userErrors {
      field
      message
    }
  }
}

Değişkenler ile:

{
  "definition": {
    "name": "Material",
    "namespace": "custom",
    "key": "material",
    "type": "list.single_line_text_field",
    "ownerType": "PRODUCT",
    "useAsCollectionCondition": true
  }
}

useAsCollectionCondition: true ayarı, bu alanı akıllı koleksiyon kurallarını güçlendirmek için hemen kullanabileceğiniz anlamına gelir, ek bir adım gerekmez.

Toplu katalog güncellemeleri için Matrixify gibi araçlar, herhangi bir API kodu yazmadan CSV'den metafield değerlerini içeri aktarmanıza olanak sağlar.

Metafields'i vitrinizde görüntüleyin

Burası çoğu tüccarın sıkışıp kaldığı yerdir. Tanım oluşturmak, alanı vitrinizde görüntülenmesini sağlamaz. Bağlantı kurmanız gerekir.

Seçenek 1: Tema editöründe dinamik kaynaklar (kod yok)

Online Store 2.0 uyumlu bir temada (Dawn, Horizon veya herhangi bir JSON şablonu temada) iseniz, tema editörünü açın, dinamik kaynakları destekleyen bir bölüm veya blok ekleyin veya tıklayın ve dinamik kaynağı bağla simgesini tıklayın. Bu şekilde tek bir şablona 20'ye kadar metafield ekleyebilirsiniz.

Seçenek 2: Liquid (tam kontrol)

Liquid sözdizimi:

{{ product.metafields.namespace.key }}

Zengin metin metafield'i için, HTML biçimlendirmesini doğru şekilde oluşturmak için metafield_tag filtresini kullanın:

{{ product.metafields.custom.care_instructions | metafield_tag }}

Görüntü dosyası referansı için:

{{ product.metafields.custom.hero_image.value | image_url: width: 800 | image_tag }}

Bir dikkat noktası: metafield anahtarınız size, first veya last ise, nokta gösterimi yerine köşeli parantez gösterimini kullanın: product.metafields.namespace["size"]. Bu sözcükler ayrıca yerleşik Liquid filtreleridir ve nokta gösterimi, anahtar eksik olduğunda metafield yerine filtreyi uygulayacaktır.

En yüksek etkili beş ürün sayfası kullanım durumu (özel içerik sekmeler, ürün rozetleri, spesifikasyon tabloları, indirilebilir PDF'ler ve ilgili ürün listeleri) için her birinin tema'nızın sections/main-product.liquid içinde kendi tanımına ve eşleşen Liquid bloğuna ihtiyacı vardır.

2026'da ne değişti: önemli güncellemeler

Spring '26 (2026'nın ortasında duyuruldu):

• Sepet metafields siparişlere taşınır. Bir sipariş metafield tanımında cartToOrderCopyable'ı etkinleştirin ve ödeme sırasındaki herhangi bir sepet metafield değeri otomatik olarak ortaya çıkan siparişe kopyalanır. Bu, Shopify Flow'daki satış sonrası mantığı için büyük bir açılımdır.
• Kaynak sayfasından ayrılmadan metafields oluşturun. Artık yeni bir tanım eklemek için Ayarlar > Özel veriler'e gitmeniz gerekmez; bunu herhangi bir müşteri, sipariş veya koleksiyon kaydından satır içi yapabilirsiniz.
• 50'ye kadar metafield sabitleyin ürün, müşteri ve sipariş admin sayfalarında.
• ShopifyQL nokta-sözdizimi filtreleme. Metafields artık ShopifyQL'de nokta-sözdizimi ile boyut ve filtre olarak desteklenir ve Analytics API ve çevrimiçi editör aracılığıyla kullanılabilir. Bu, analitikler raporlarınızı tanımladığınız herhangi bir özel alan ile bölümlemeniz mümkün olması anlamına gelir.
• Basitleştirilmiş GraphQL API. Spring '26 sürümü, metafields ve metaobjects için basitleştirilmiş bir okuma/yazma arayüzü göndermiş, uygulama kodundaki standart dışı kodu azaltmıştır.
• Alışveriş Kullanıcısı metafields ödeme sırasında okunabilir Shopify Functions aracılığıyla, saklı müşteri verilerine karşı alıcıya özel ödeme özelleştirmeleri oluşturmanıza olanak sağlayan.

Admin GraphQL API 2026-07 (Temmuz 2026 itibarıyla yayın adayı):

• Envanter transferlerinde metafields. Artık ayrı bir metafieldsSet çağrısı olmadan envanter transferlerinde metafields'i doğrudan tanımlayabilir ve ayarlayabilirsiniz.

Winter '26:

• Metafields ve metaobjects vitrinde daha hızlı oluşturulur, daha zengin sorgu filtrelemesini destekler ve önceki API sürümlerinden daha yüksek giriş sınırlarına izin verir.

Ekim 2025 (API 2025-10):

• article_reference ve list.article_reference türleri eklendi, tüccarların içerik odaklı SEO ve editoryal ticaret akışları için resmi ürün-makale bağlantıları oluşturmasını sağlıyor.

Metafields ve metaobjects: hangileri ne zaman kullanacağınız

Bir metafield, var olan bir kaynakta tek bir veri parçasını depolar. Bir metaobject, kendi şemasına, birden fazla alana ve kendi admin UI'ine sahip bir yeniden kullanılabilir, bağımsız içerik girişidir. Veriler belirli bir ürüne (veya siparişe veya müşteriye) ait olduğu ve yalnızca orada mantıklı olduğu zaman metafield kullanın. İçerik, paylaşılan bir beden kılavuzu, marka hikayesi veya tedarikçi profili gibi birden fazla ürün arasında yeniden kullanıldığı zaman metaobject kullanın.

İkisini bir metaobject_reference metafield ile bağlarsınız: ürün üzerindeki alan metaobject girişine işaret eder ve girişi güncellemek, bunu başvuran her ürünü otomatik olarak günceller.

Metafields ve yapay zeka alışveriş katmanı

Bu, 2026'da çoğu tüccarın kaçırdığı açıdır. Shopify'ın Summer '26 "Everywhere Edition" sürümü Evrensel Ticaret Protokolünü (UCP) her mağazada varsayılan olarak etkin hale getirerek yapay zeka alışveriş ajanlarına kataloğunuz okumasına izin vermiştir. Metafields içindeki yapılandırılmış veriler (spesifikasyonlar, malzemeler, sertifikalar, malzemeler) tam olarak yapay zeka ajanlarının ve Google'ın zengin sonuç ayrıştırıcılarının ürününüzü yüzeyde bulup bulmayacağına karar verirken tükettiği şeydir.

Kategori metafields burada özel dikkat hak etmektedir. Bunlar, belirli bir ürün kategorisine eşlenen ve ürünleri sitenizde, pazarlarda ve arama motorlarında daha keşfedilebilir hale getirmeye yardımcı olan ürün öznitelikleridir. Shopify'da doğru ürün kategorisini atadığınızda, standart tanım girişleri önceden doldurulmuş olarak alırsınız (örneğin, Shirts kategorisi beden, boyun çizgisi, kol boyu, kumaş, cinsiyet ve renk alanları verir). Bunları tutarlı bir şekilde doldurun ve her aşağı akış kanalına eşzamanlı olarak yapılandırılmış veriler besliyor olursunuz.

Ürün açıklamalarınızı okunabilirlik için ayrı metafields'e ayırdıysanız, şu anda birden fazla Shopify alanını tek bir Shopify Kataloğu açıklama alanına eşleyemeyeceğinizi unutmayın. Geçici çözüm, açıklamanız ve anahtar metafield verilerinizi birleştiren bir birleştirilmiş metafield oluşturmak ve ardından bu tek alanı kataloga eşlemektir.

Yönetişim: çoğu takımın atladığı kısım

Metafields oluşturması kolay ve çok kolayca yayılması kolay olur. Daha sonra pahalı temizleme yapmanızı önleyen birkaç kural:

• Şemanızı belgeleyin. Her ad alanını, anahtarı, türü, sahibi kaynağı ve tanımı hangi uygulamanın veya takımın sahip olduğunu kaydeden bir referans sayfası (basit bir elektronik tablo işe yarar) tutun.
• Varsa standart tanımları kullanın. Bunlar birlikte çalışabilir, otomatik olarak doğrulanır ve adlandırma çarpışmalarına karşı bağışıktırlar.
• Canlı verileriniz olduğunda türü asla değiştirmeyin. Örneğin date_time'dan money'ye geçiş yapmak tüm mevcut değerleri geçersiz kılar. Türleri baştan itibaren doğru planlayın.
• Ad alanı disiplini. Uygulama veya takım başına farklı ad alanları kullanın (logistics, marketing, compliance), böylece ad alanı tarafından denetleyip temizleyebilirsiniz ve ilgisiz alanları etkilemeyebilirsiniz.
• Yazmaları atomik işlemler olarak test edin. metafieldsSet mutasyonu atomiktir: tek bir çağrıda 25 değerin tümü başarılı olur ya da hiçbiri başarılı olmaz. Toplu içeri aktarmalarınızı bu garanti etrafında yapılandırın.

Karmaşık bir katalog için metafield şeması mimarisi veya özel bir vitrin'e metafields entegrasyonu konusunda yardıma ihtiyacınız varsa, Shopify geliştirici hizmetleri sayfasına veya tüccarlarla yaptığım Shopify tema geliştirici çalışmasına bakın.

Hızlı başvuru: Liquid sözdizimi crib sayfası

Metafields, iki saat içinde temel işleri öğrenmenin haftalar sonra geçici çözümleri kurtardığı özelliklerden biridir. Şemanızı dikkatli bir şekilde tanımlayın, standart tanımları mevcut olduğu yerlerde kullanın ve alanlarınızı hem vitrinize hem de analitikler katmanınıza bağlayın. 2026 güncellemeleri, özellikle sepetden siparişe kopyalama ve ShopifyQL filtreleme, metafield verilerinizin her zamankinden daha çalışan olması anlamına gelir.