Web Sitenize Canlı Altın Fiyatı Widget'ı Nasıl Eklenir

Neyi gömüyorsunuz

MetalAPI widget'ı, MetalAPI'nin sizin için barındırdığı küçük bir fiyat panosudur. Panelde bir kez yapılandırır, sayfanıza iki satırlık bir kod parçacığı yapıştırırsınız ve ziyaretçiler altın, gümüş, platin, paladyum, endüstriyel metaller, enerji, döviz veya kripto için güncel fiyatları görür. Widget, metalapi.com adresinden sunulan bir iframe içinde görüntülenir. Yazmanız gereken backend kodu yoktur, HTML'inizde API anahtarı bulunmaz ve fiyatlar değiştiğinde sizin tarafınızda güncellenecek hiçbir şey yoktur.

Bu da widget'ı, güncel fiyatı kendi içeriğinin yanında göstermek isteyen içerik siteleri, kuyumcu ve külçe altın mağazaları, haber sayfaları ve bloglar için en hızlı seçenek yapar. Fiyata kendi HTML yapınızın içinde veya bir hesaplamada ihtiyacınız varsa REST API daha uygundur. Bu yazının son bölümü bu durumu ele alıyor.

Widget trafiği API anahtarınız üzerinden değil, MetalAPI'nin widget endpoint'i tarafından sunulur; bu nedenle sayfa görüntülemeleri aylık istek kotanızı kullanmaz. Kaç widget kaydedebileceğinizi ve fiyatlarının ne kadar güncel olacağını planınız belirler; her ikisi de aşağıda ele alınıyor.

Widget'ı panelde oluşturun

Widget'lar, Free dahil her plana dahildir. Bir hesap oluşturun, paneldeki Widgets bölümünü açın ve New widget düğmesine tıklayın. Oluşturucu, formun yanında canlı bir önizleme gösterir; böylece kaydetmeden önce seçenekleri deneyebilirsiniz:

İki ayrıntı kolayca gözden kaçabilir. Birimi troy ons olarak bırakırsanız endüstriyel metaller bunun yerine olağan piyasa birimleriyle gösterilir; yani altın troy ons başına kalırken bakır libre başına görünür. Ayrıca gram veya kilogram birimi yalnızca metalleri dönüştürür: döviz, enerji ve kripto kendi birimlerini korur. Ziyaretçilerinizin hangi ağırlık birimini beklediğinden emin değilseniz birim dönüştürme rehberi farkları açıklıyor.

Kaydettiğinizde widget'a w_abc123 gibi herkese açık bir kimlik verilir. Gömme kodu yalnızca bu kimliğe başvurur; yapılandırma MetalAPI'nin sunucularında kalır. Daha sonra sembolleri, renkleri veya düzeni değiştirdiğinizde, widget'ı gömen her sayfa bir sonraki yüklemede yeni sürümü gösterir; sitenizdeki kod parçacığını değiştirmeniz gerekmez. Widget listesinde ayrıca bir widget'ı silmeden yayından kaldırmak için bir Live anahtarı ve her widget için bir görüntülenme sayacı bulunur.

Satır satır gömme kodu

Kaydettikten sonra oluşturucu gömme kodunu gösterir:

<div id="metalapi-widget-w_abc123"></div>
<script src="https://metalapi.com/js/widget.js" data-widget="w_abc123" async></script>

Script, sıkıştırma öncesinde yaklaşık 4 KB boyutunda küçük bir yükleyicidir. data-widget özniteliğini okur, metalapi-widget-<id> kimliğine sahip öğeyi arar ve onu https://metalapi.com/embed/<id> adresini yükleyen bir iframe ile doldurur. Kapsayıcı yoksa yükleyici, script etiketinin hemen önünde bir tane oluşturur. Çerçevenin içindeki widget yüksekliğini postMessage ile bildirir ve yükleyici iframe'i buna göre yeniden boyutlandırır; böylece üç satırdan altı satıra büyüyen bir tabloda hiçbir zaman kaydırma çubuğu görünmez.

Script etiketi birden fazla kez yer alsa bile yükleyici sayfa başına yalnızca bir kez çalışır. Tek bir sayfada birden fazla widget göstermek için script'i yalnızca bir kez ekleyin ve her kapsayıcıyı id yerine bir data-metalapi-widget özniteliğiyle işaretleyin:

<div data-metalapi-widget="w_abc123"></div>
<div data-metalapi-widget="w_def456"></div>

<script src="https://metalapi.com/js/widget.js" async></script>

Yükleyici bu kapsayıcıları sayfa yüklendiğinde bir kez arar. İstemci tarafı JavaScript'in daha sonra eklediği kapsayıcıları, örneğin tek sayfalı bir uygulamada (SPA) rota değişikliğinden sonra eklenenleri görmez. Bu durumda ya da hiç script ekleyemediğiniz yerlerde çerçeveyi doğrudan gömün:

<iframe
  src="https://metalapi.com/embed/w_abc123"
  title="Live gold price"
  loading="lazy"
  style="border:0;width:100%;height:220px"
></iframe>

Yükleyici olmadan iframe kendini yeniden boyutlandıramaz; bu nedenle ona seçtiğiniz düzene uyan bir yükseklik verin. Önceki widget oluşturucusunun eski new MetalAPIWidget({...}) kod parçacığını kullanan sayfalar çalışmaya devam eder: kaydedilmiş widget'lar kimlikleriyle görüntülenir ve eski bir kod parçacığında kalmış API anahtarları yok sayılır.

Düz HTML, WordPress ve Shopify

Düz HTML. Kod parçacığını widget'ın görünmesini istediğiniz yere yapıştırın; örneğin bir kenar çubuğuna veya bir fiyat sayfasının en üstüne. async özniteliği sayesinde yükleyici, indirilirken sayfanın geri kalanını hiçbir zaman engellemez.

WordPress. Blok düzenleyicide bir Custom HTML (Özel HTML) bloğu ekleyin ve kod parçacığını yapıştırın. Widget'ı her sayfada göstermek için onu bir kenar çubuğu veya alt bilgi widget alanındaki bir Custom HTML widget'ına ya da temanızın şablon dosyalarına yerleştirin. Multisite ağları veya kısıtlı hosting paketleri gibi bazı kurulumlar, içerikteki <script> etiketlerini temizler. Yayımladıktan sonra widget görünmüyorsa sayfa kaynağını görüntüleyin. Script etiketi eksikse script gerektirmeyen iframe sürümünü kullanın.

Shopify. Tema düzenleyicide (Online Store → Themes → Customize), widget'ın yer alacağı şablona bir Custom Liquid bölümü veya bloğu ekleyin ve kod parçacığını yapıştırın. Widget'ı yalnızca ürün sayfalarında göstermek için bloğu ürün şablonuna ekleyin. Tema kodunu düzenlerken kod parçacığını doğrudan bir section dosyasına da yerleştirebilirsiniz.

Diğer site oluşturucular. HTML veya gömme öğesi sunan oluşturucular da aynı şekilde çalışır; örneğin Webflow'un kod gömme öğesi veya Squarespace'in kod bloğu. Bazı oluşturucular özel HTML'i kendi iframe'leri içine sarar ve otomatik yeniden boyutlandırma bu çerçeveye ulaşamaz. Bu durumda gömme öğesine sabit bir yükseklik verin.

Plan limitleri, güncellik ve marka ibaresi

Kaydedilmiş bir widget, fiyatları sahibinin planının izin verdiği güncellikte gösterir ve yeni verileri kendi başına sorgular. Sorgulama aralığı planın güncelleme aralığını izler, ancak hiçbir zaman 30 saniyeden kısa ve 15 dakikadan uzun olmaz:

Free ve Lite planlarda widget, yeni verileri fiyatların değiştiğinden daha sık kontrol eder; böylece her güncellemeyi sayfa yenilenmeden yakalar. Her widget, verisinin zamanını altta UTC olarak gösterir; böylece ziyaretçiler fiyatların ne kadar güncel olduğunu görebilir. Plan başına tam özellik listesi fiyatlandırma sayfasında yer alır.

Performans ve düzen kayması

Bir widget sayfaya çok az yük ekler:

• Engellemeyen script. Yükleyici async ile yüklenir ve bir saatlik tarayıcı önbelleğiyle sunulur; bu nedenle geri dönen ziyaretçiler onu genellikle yeniden indirmez.
• Gecikmeli yüklenen çerçeveler. Yükleyici iframe'i loading="lazy" ile oluşturur; böylece sayfanın aşağılarındaki bir widget yalnızca ziyaretçi ona yaklaştığında yüklenir.
• Yalıtım. Widget kendi çerçevesi içinde çalışır. Stil dosyalarınız onu bozamaz, onun kodu da sayfanıza dokunamaz.
• Sayfa önbelleğe alma güvenlidir. Kod parçacığı hiç değişmez ve fiyatlar çerçevenin içinde yüklenir. WordPress önbellek eklentileri, Shopify'ın CDN'i veya başka herhangi bir tam sayfa önbelleği, fiyatı dondurmadan HTML'inizi istediği kadar saklayabilir.

Planlamanız gereken tek şey düzen kaymasıdır (layout shift). Çerçeve 120 pikselle başlar, ardından widget'ın gerçek yüksekliğine büyür; bu da altındaki içeriği aşağı itebilir. Oluşturucu önizlemesinde gördüğünüz yüksekliği kullanarak kapsayıcıya bir minimum yükseklik verin ve alanı önceden ayırın:

<div id="metalapi-widget-w_abc123" style="min-height:240px"></div>
<script src="https://metalapi.com/js/widget.js" data-widget="w_abc123" async></script>

Bir ticker, sekiz metallik bir tablodan çok daha az alana ihtiyaç duyar; bu nedenle site genelinde tek bir varsayılan değer yerine her widget için ayrı bir değer kullanın.

Ne zaman bunun yerine API'yi kullanmalı

Widget, hazır bir bileşendir. Widget'ın yapmadığı bir şeye ihtiyacınız olduğunda API'yi kullanın:

• Kendi HTML'inizde fiyatlar. Bir iframe içindeki metin başka bir belgeye aittir; bu nedenle arama motorları onu sayfanızın bir parçası olarak değerlendirmeyebilir. Fiyatın sayfa içeriğinizin bir parçası olması gerekiyorsa onu sunucuda oluşturun.
• Kendi tasarımınız. Widget'lar dört düzen, bir tema ve bir vurgu rengi sunar. Bunun ötesindeki her şey için kendi HTML yapınızı yazın.
• Hesaplamalar. Ağırlığa ve saflığa dayalı ürün fiyatları, geri alım teklifleri ve dönüştürmeler sunucunuzda yapılmalıdır. Kuyum fiyat hesaplayıcısı eğitimi bunlardan birini adım adım anlatıyor.
• Uygulamanızdaki veriler. Grafikler, geçmiş veriler ve saklanan fiyatlar için API dokümantasyonunda açıklanan historical ve timeframe endpoint'leri gerekir.

API'yi sunucunuzdan çağırın ve her yanıtı planınızın güncelleme aralığı boyunca önbelleğe alın. WordPress'te transient önbellek kullanan bir shortcode, ikisini de birkaç satırda yapar:

<?php
// wp-config.php içinde: define('METALAPI_KEY', 'mk_live_...');
add_shortcode('gold_price', function ($atts) {
    $a = shortcode_atts(['currency' => 'USD', 'unit' => 'troy_oz'], $atts);
    $currency = strtoupper(preg_replace('/[^A-Za-z]/', '', $a['currency']));
    $unit = sanitize_key($a['unit']);
    $cache_key = "metalapi_xau_{$currency}_{$unit}";

    $data = get_transient($cache_key);
    if ($data === false) {
        $url = add_query_arg(
            ['base' => $currency, 'currencies' => 'XAU', 'unit' => $unit],
            'https://metalapi.com/api/v1/latest'
        );
        $res = wp_remote_get($url, ['headers' => ['X-API-Key' => METALAPI_KEY], 'timeout' => 10]);
        if (is_wp_error($res)) return '';
        $data = json_decode(wp_remote_retrieve_body($res), true);
        if (empty($data['success'])) return '';
        set_transient($cache_key, $data, 10 * MINUTE_IN_SECONDS); // planınızın güncelleme aralığı
    }

    $price = $data['rates'][$currency . 'XAU'] ?? null;
    if ($price === null) return '';
    return sprintf(
        '<span class="gold-price">%s %s / %s</span>',
        esc_html(number_format_i18n($price, 2)),
        esc_html($currency),
        esc_html(str_replace('_', ' ', $unit))
    );
});

Herhangi bir yazıda veya sayfada [gold_price currency="EUR" unit="gram"] olarak kullanın. Yanıt anahtarı, baz para birimi ile sembolün birleşiminden oluşur; yani rates.EURXAU, bir gram altının euro cinsinden fiyatıdır. Önbellekte bulunamayan her istek bir istek harcar; bu nedenle 10 dakikalık bir transient, gösterdiğiniz her para birimi ve birim için ayda en fazla yaklaşık 4.500 istek kullanır ve bu da Standard plana sığar.

API'yi bunun yerine tarayıcıdan çağırmanız gerekiyorsa önce anahtarı kimlik doğrulama rehberinde anlatıldığı gibi kendi alan adlarınızla sınırlandırın. Yine de düz bir fiyat gösterimi için widget daha basit seçenek olmaya devam eder: anahtar yok, yönetilecek önbellek yok ve daha sonra sembolleri değiştirdiğinizde bakımı gereken hiçbir şey yok.