# SFCC Kartuş Geliştirme: Geliştiriciler İçin Kapsamlı Rehber

URL: https://www.ozanaltinbas.com/tr/makale/sfcc-cartridge-development
Author: Ozan Altinbas (Ozan Altınbaş), SFCC Technical Architect
Published: 2026-02-20 | Updated: 2026-04-17
Category: Geliştirici Rehberi | Tags: SFCC cartridge development, SFRA, SFCC developer, Commerce Cloud cartridge, ISML

---

Salesforce Commerce Cloud üzerinde geliştirme yapıyorsanız, **kartuşları** anlamanız gerekir. Kartuşlar, SFCC geliştirmenin temel modüler birimidir — diğer çerçevelerdeki paketler veya modüllerin eşdeğeri. SFCC'deki her özel kod parçası, her üçüncü taraf entegrasyon ve her vitrin şablonu bir kartuşta yer alır.

Bu rehber, bir geliştiricinin SFCC kartuşlarıyla etkin biçimde çalışması için bilmesi gereken her şeyi kapsamaktadır.

---

## SFCC Kartuşu Nedir?

Kartuş, belirli bir dosya yapısını takip eden ve bir veya daha fazla SFCC sitesinde etkinleştirilebilen kendi kendine yeten bir dizindir. Kartuşlar şunları içerir:

- **Denetleyiciler** — rota mantığını yöneten sunucu tarafı JavaScript
- **Şablonlar (ISML)** — SFCC'nin ISML şablonlama dili kullanan sunucu tarafı HTML şablonları
- **İstemci tarafı varlıklar** — webpack ile paketlenmiş JavaScript, CSS ve görseller
- **Betikler** — yeniden kullanılabilir sunucu tarafı yardımcı betikler
- **Statik** — yazı tipleri, görseller ve diğer statik varlıklar
- **Meta veriler** — sistem nesnesi uzantıları ve özel nesne tanımları

---

## Kartuş Yolu

**Kartuş yolu**, bir sitede etkin olan kartuşların sıralı listesidir. SFCC bir kaynak (denetleyici, şablon veya betik) çözümlemesi gerektiğinde, kartuş yolu boyunca soldan sağa kartuşları arar ve bulduğu ilk eşleşmeyi kullanır.

Bu, SFCC'nin **geçersiz kılma desenini** nasıl uyguladığıdır:

```
app_custom_storefront:app_storefront_base
```

Bu örnekte, bir istek geldiğinde SFCC önce `app_custom_storefront`'u kontrol eder. Denetleyici orada mevcutsa kullanılır. Değilse SFCC `app_storefront_base`'e geri döner.

Bu desen SFCC geliştirmenin temelidir. Temel kartuşları (örn. `app_storefront_base`) **asla değiştirmezsiniz**. Bunun yerine, yalnızca değiştirmeniz gereken dosyaları geçersiz kılan özel bir kartuş oluşturursunuz.

---

## Storefront Reference Architecture (SFRA)

SFRA, Salesforce'un 2018'de eski Site Genesis çerçevesinin yerini alarak önerdiği vitrin mimarisidir. SFRA kendisi bir kartuş seti olarak sunulur:

- **app_storefront_base** — tüm denetleyiciler, şablonlar ve istemci tarafı kodla temel SFRA kartuşu
- **modules** — paylaşılan SFRA yardımcıları
- **bm_app_storefront_base** — SFRA için Business Manager uzantıları

Herhangi bir SFRA projesinde, özelleştirmeniz gereken belirli denetleyicileri, şablonları ve betikleri geçersiz kılan özel bir kartuş (örn. `app_custom_myproject`) oluşturursunuz.

---

## SFCC'deki Denetleyiciler

SFCC denetleyicileri, vitrin için rota işleyicilerini tanımlayan sunucu tarafı JavaScript dosyalarıdır. SFRA'da denetleyiciler `server` modülünü kullanır:

```javascript
'use strict';

var server = require('server');
var page = module.superModule;
server.extend(page);

server.append('Show', function (req, res, next) {
    var viewData = res.getViewData();
    viewData.customData = 'merhaba dünya';
    res.setViewData(viewData);
    next();
});

module.exports = server.exports();
```

Temel kavramlar:

- **server.extend(page)** — üst kartuşun denetleyicisindeki tüm rotaları devralır
- **server.append** — üst rotayı değiştirmeden sonrasında çalışan mantık ekler
- **server.replace** — bir üst rotayı tamamen değiştirir
- **server.prepend** — üst rotadan önce çalışan mantık ekler

---

## ISML Şablonları

ISML (Internet Store Markup Language), SFCC'nin sunucu tarafı şablonlama dilidir. HTML'yi SFCC'ye özgü etiketlerle genişletir:

```html
<isscript>
    var product = pdict.product;
</isscript>

<div class="product-name">
    <isprint value="${product.name}" encoding="html" />
</div>

<isif condition="${product.available}">
    <button class="add-to-cart">Sepete Ekle</button>
<iselse/>
    <p>Stokta Yok</p>
</isif>
```

---

## Kartuş Geliştirme En İyi Uygulamaları

**Temel kartuşları asla değiştirmeyin.** Her zaman yalnızca ihtiyacınız olanı geçersiz kılmak için özel bir kartuş oluşturun. Bu, yükseltmeleri yönetilebilir tutar.

**Geçersiz kılma desenini tutarlı biçimde uygulayın.** Rotalara eklemek için `server.append`, davranışı tamamen değiştirmeniz gerektiğinde `server.replace` kullanın.

**Kartuşları odaklı tutun.** Entegrasyon başına bir kartuş (ödeme ağ geçidi, sadakat programı vb.) ve bir özel vitrin kartuşu. Endişeleri karıştıran monolitik kartuşlardan kaçının.

**Üretimde asla test etmeyin.** SFCC'nin çok ortamlı mimarisi (sandbox → hazırlık → üretim) bir nedenden dolayı vardır. Kod değişikliklerini doğrudan üretimde test etmeyin.

---

## SFCC Kartuşlarında Hata Ayıklama

SFCC çeşitli hata ayıklama araçları sağlar:

- **Business Manager'daki Log Center** — özel `dw.system.Logger` çıktısına ve sistem hata günlüklerine erişim
- **Prophet Debugger** (VS Code uzantısı) — kod yükleme, adım adım hata ayıklama ve log akışı için standart SFCC geliştirme aracı
- **Hizmet Yapılandırması** — harici servis kimlik bilgilerini ve uç noktaları yönetme

Modern SFRA geliştirme için Prophet Debugger vazgeçilmez araçtır. Gerçek zamanlı kod senkronizasyonu ve kesme noktası hata ayıklamasını etkinleştirmek için SFCC sandbox kimlik bilgilerinizle yapılandırın. Proje kökündeki `dw.json` dosyası sandbox hostname'ini, kod sürümünü ve kimlik bilgilerini tutar:

```json
{
  "hostname": "sandbox-adiniz.demandware.net",
  "username": "kullanici-adiniz",
  "password": "sifreniz",
  "code-version": "version1"
}
```

Windows'ta dikkat edilmesi gereken bir nokta: Prophet'ı Git Bash üzerinden çalıştırıyorsanız, staging/production sandbox'larına karşı SSL sertifika doğrulaması sessizce başarısız olabilir. Uzantı belirgin bir hata vermeden yüklemeyi durduruyor. Sandbox ortamları için `dw.json`'a `"self-signed": true` ekleyerek veya VS Code'un sistem sertifika deposunu kullandığından emin olarak çözebilirsiniz.

---

## SFCC Geliştirmede Sertifika Edinme

SFCC'yi kariyer olarak ciddiye alıyorsanız, resmi Salesforce sertifikalarını düşünün:

- **B2C Commerce Developer** — SFCC geliştiricileri için temel sertifika
- **B2C Commerce Architect** — çözüm tasarımı ve mimariyi kapsayan üst düzey sertifika

Her iki sertifika da Trailhead aracılığıyla mevcuttur ve kartuş geliştirme, Business Manager yapılandırması ve SFCC'nin API katmanı hakkında pratik bilgi gerektirir. Her iki sınavda da Business Manager'ın kartuş kodunuzu çalışma zamanında nasıl etkilediği test edilir — [Business Manager rehberi](/tr/makale/sfcc-business-manager-guide) operasyonel tarafı ayrıntılı biçimde ele almaktadır. Sınavların neleri kapsadığına dair tam döküm için [SFCC sertifikasyon rehberine](/tr/makale/sfcc-certification-guide) bakabilirsiniz.