كيف تضيف ودجة لأسعار الذهب المباشرة إلى موقعك الإلكتروني

ما الذي تضمّنه

ودجة MetalAPI لوحة أسعار صغيرة يستضيفها MetalAPI نيابةً عنك. تضبطها مرة واحدة في لوحة التحكم، وتلصق مقتطفًا من سطرين في صفحتك، فيرى الزوار الأسعار الحالية للذهب أو الفضة أو البلاتين أو البلاديوم أو المعادن الصناعية أو الطاقة أو العملات أو العملات المشفرة. تُعرض الودجة داخل إطار iframe يُقدَّم من metalapi.com. فلا شيفرة للواجهة الخلفية تكتبها، ولا مفتاح API في HTML لديك، ولا شيء تحدّثه من جهتك عندما تتحرك الأسعار.

وهذا يجعل الودجة الخيار الأسرع لمواقع المحتوى ومتاجر المجوهرات والسبائك وصفحات الأخبار والمدونات التي تريد عرض السعر الحالي إلى جانب محتواها. أما إذا كنت تحتاج إلى السعر داخل شيفرة HTML الخاصة بك أو في عملية حسابية، فإن REST API هو الأنسب. ويتناول القسم الأخير من هذه المقالة هذه الحالة.

تُخدَم حركة الودجات عبر نقطة نهاية الودجات في MetalAPI، لا عبر مفتاح API الخاص بك، لذا لا تستهلك مشاهدات الصفحات حصتك الشهرية من الطلبات. وتحدد خطتك عدد الودجات التي يمكنك حفظها ومدى حداثة أسعارها؛ ونتناول الأمرين أدناه.

أنشئ الودجة في لوحة التحكم

الودجات مضمّنة في كل الخطط، بما فيها Free. أنشئ حسابًا، وافتح Widgets في لوحة التحكم وانقر New widget. تعرض أداة الإنشاء معاينة مباشرة بجوار النموذج، لذا يمكنك تجربة الخيارات قبل الحفظ:

ثمة تفصيلان يسهل إغفالهما. إذا تركت الوحدة على أونصة التروي، فستُعرض المعادن الصناعية بوحدتها المعتادة في السوق بدلًا من ذلك، فيظهر النحاس لكل رطل بينما يبقى الذهب لكل أونصة تروي. كما أن وحدة الغرام أو الكيلوغرام لا تحوّل إلا المعادن: فالعملات والطاقة والعملات المشفرة تحتفظ بوحداتها الخاصة. وإذا لم تكن متأكدًا من وحدة الوزن التي يتوقعها زوارك، فإن دليل تحويل الوحدات يشرح الفروق.

يمنح الحفظُ الودجةَ معرّفًا عامًا مثل w_abc123. ولا تشير شيفرة التضمين إلا إلى هذا المعرّف؛ أما الإعدادات فتبقى على خوادم MetalAPI. وعندما تغيّر لاحقًا الرموز أو الألوان أو التخطيط، تعرض كل صفحة تضمّن الودجة النسخة الجديدة عند تحميلها التالي، دون أي تغيير في المقتطف على موقعك. وتتضمن قائمة الودجات أيضًا مفتاح Live لإيقاف ودجة عن العمل دون حذفها، وعدّادًا للمشاهدات لكل ودجة.

شيفرة التضمين سطرًا بسطر

بعد الحفظ، تعرض أداة الإنشاء شيفرة التضمين:

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

السكربت أداة تحميل صغيرة، حجمها نحو 4 كيلوبايت قبل الضغط. تقرأ data-widget، وتبحث عن العنصر ذي المعرّف metalapi-widget-<id> وتملؤه بإطار iframe يحمّل https://metalapi.com/embed/<id>. وإذا لم تجد الحاوية، تنشئ أداة التحميل حاوية مباشرةً قبل وسم السكربت. وتُبلغ الودجة داخل الإطار عن ارتفاعها عبر postMessage، فتغيّر أداة التحميل حجم iframe ليطابقه، لذا لا يظهر شريط تمرير أبدًا في جدول يتوسع من ثلاثة صفوف إلى ستة.

لا تعمل أداة التحميل إلا مرة واحدة في كل صفحة، حتى لو ظهر وسم السكربت عدة مرات. ولعرض عدة ودجات في صفحة واحدة، ضمّن السكربت مرة واحدة فقط وميّز كل حاوية بالسمة data-metalapi-widget بدلًا من المعرّف:

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

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

تبحث أداة التحميل عن هذه الحاويات مرة واحدة عند اكتمال تحميل الصفحة. فلا ترى الحاويات التي تضيفها JavaScript في جانب العميل لاحقًا، مثلًا بعد تغيير المسار في تطبيق أحادي الصفحة. في هذه الحالة، أو حيث لا يمكنك إضافة سكربتات أصلًا، ضمّن الإطار مباشرةً:

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

دون أداة التحميل لا يستطيع iframe تغيير حجمه بنفسه، لذا امنحه ارتفاعًا يناسب التخطيط الذي اخترته. وتستمر الصفحات التي لا تزال تستخدم المقتطف الأقدم new MetalAPIWidget({...}) من مولّد الودجات السابق في العمل: إذ تُعرض الودجات المحفوظة بمعرّفها، ويُتجاهل أي مفتاح API متبقٍّ في مقتطف قديم.

HTML عادي وWordPress وShopify

HTML عادي. الصق المقتطف حيث يجب أن تظهر الودجة، مثلًا في شريط جانبي أو أعلى صفحة الأسعار. وبفضل السمة async، لا تعطّل أداة التحميل بقية الصفحة أبدًا أثناء تنزيلها.

WordPress. في محرر المكوّنات، أضف مكوّن Custom HTML والصق المقتطف. ولعرض الودجة في كل صفحة، ضعها في ودجة Custom HTML ضمن منطقة ودجات الشريط الجانبي أو التذييل، أو في ملفات قوالب السمة. بعض الإعدادات، مثل شبكات المواقع المتعددة أو خطط الاستضافة المقيّدة، تحذف وسوم <script> من المحتوى. وإذا لم تظهر الودجة بعد النشر، فاعرض الشيفرة المصدرية للصفحة. فإذا كان وسم السكربت مفقودًا، فاستخدم نسخة iframe التي لا تحتاج إلى سكربت.

Shopify. في محرر السمة (Online Store → Themes → Customize)، أضف قسمًا أو مكوّنًا من نوع Custom Liquid إلى القالب الذي تنتمي إليه الودجة والصق المقتطف. ولعرضها في صفحات المنتجات فقط، أضف المكوّن إلى قالب المنتج. ويمكنك أيضًا وضع المقتطف مباشرةً في ملف قسم عند تعديل شيفرة السمة.

أدوات بناء المواقع الأخرى. تعمل الأدوات التي توفر عنصر HTML أو عنصر تضمين بالطريقة نفسها، مثل عنصر تضمين الشيفرة في Webflow أو مكوّن الشيفرة في Squarespace. وتغلّف بعض هذه الأدوات شيفرة HTML المخصصة بإطار iframe خاص بها، فلا يصل تغيير الحجم التلقائي عبره. في هذه الحالة، امنح عنصر التضمين ارتفاعًا ثابتًا.

حدود الخطط وحداثة البيانات والعلامة التجارية

تعرض الودجة المحفوظة أسعارًا حديثة بقدر ما تسمح به خطة مالكها، وتستطلع البيانات الجديدة بنفسها. وتتبع فترة الاستطلاع فترة التحديث في الخطة، لكنها لا تقل أبدًا عن 30 ثانية ولا تزيد على 15 دقيقة:

في خطتي Free وLite، تتحقق الودجة من البيانات الجديدة بوتيرة أعلى من وتيرة تغيّر الأسعار، لذا تلتقط كل تحديث دون إعادة تحميل الصفحة. وتعرض كل ودجة وقت بياناتها بتوقيت UTC في أسفلها، حتى يرى الزوار مدى حداثة الأسعار. وتجد قائمة الميزات الكاملة لكل خطة في صفحة الأسعار.

الأداء وإزاحة التخطيط

لا تضيف الودجة إلى الصفحة إلا القليل جدًا:

• سكربت غير معطّل. تُحمَّل أداة التحميل مع async وتُقدَّم مع تخزين مؤقت في المتصفح لمدة ساعة، لذا لا يعيد الزوار العائدون تنزيلها عادةً.
• إطارات بتحميل كسول. تنشئ أداة التحميل إطار iframe مع loading="lazy"، لذا لا تُجلب الودجة الموجودة في أسفل الصفحة إلا عندما يقترب الزائر منها أثناء التمرير.
• العزل. تعمل الودجة داخل إطارها الخاص. فلا تستطيع أوراق الأنماط لديك إفسادها، ولا تستطيع شيفرتها المساس بصفحتك.
• التخزين المؤقت للصفحات آمن. لا يتغير المقتطف أبدًا، وتُحمَّل الأسعار داخل الإطار. لذا يمكن لإضافات التخزين المؤقت في WordPress أو لشبكة CDN في Shopify أو لأي ذاكرة تخزين مؤقت للصفحات الكاملة الاحتفاظ بـ HTML لديك المدة التي تشاء دون تجميد السعر.

الأمر الوحيد الذي يجب التخطيط له هو إزاحة التخطيط. يبدأ الإطار بارتفاع 120 بكسل ثم يتمدد إلى الارتفاع الفعلي للودجة، ما قد يدفع المحتوى الموجود أسفله إلى الأسفل. احجز المساحة مسبقًا بتحديد حد أدنى لارتفاع الحاوية، مستخدمًا الارتفاع الذي تراه في معاينة أداة الإنشاء:

<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>

يحتاج الشريط إلى مساحة أقل بكثير من جدول يضم ثمانية معادن، لذا استخدم قيمة خاصة بكل ودجة بدلًا من قيمة افتراضية واحدة للموقع كله.

متى تستخدم API بدلًا من الودجة

الودجة مكوّن جاهز. استخدم API عندما تحتاج إلى شيء لا تفعله الودجة:

• الأسعار داخل HTML الخاص بك. النص الموجود داخل iframe ينتمي إلى مستند آخر، لذا قد لا تعدّه محركات البحث جزءًا من صفحتك. وإذا كان ينبغي أن يكون السعر جزءًا من محتوى صفحتك، فاعرضه من جانب الخادم.
• تصميمك الخاص. توفر الودجات أربعة تخطيطات وسمة ولونًا مميزًا. ولأي شيء يتجاوز ذلك، اكتب شيفرة HTML الخاصة بك.
• العمليات الحسابية. مكان أسعار المنتجات المبنية على الوزن والنقاوة، وعروض أسعار إعادة الشراء، والتحويلات هو خادمك. ويشرح درس حاسبة أسعار المجوهرات مثالًا على ذلك خطوة بخطوة.
• البيانات داخل تطبيقك. تحتاج الرسوم البيانية والسجل التاريخي والأسعار المخزّنة إلى نقطتي النهاية historical وtimeframe الموصوفتين في توثيق API.

استدعِ الواجهة من خادمك وخزّن كل استجابة مؤقتًا طوال فترة التحديث في خطتك. وفي WordPress، يؤدي رمز قصير (shortcode) مع تخزين مؤقت عبر transient المهمتين في بضعة أسطر:

<?php
// In wp-config.php: 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); // your plan's update interval
    }

    $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))
    );
});

استخدمه في أي مقالة أو صفحة على الشكل [gold_price currency="EUR" unit="gram"]. ومفتاح الاستجابة هو عملة الأساس متبوعةً بالرمز، لذا فإن rates.EURXAU هو سعر غرام واحد من الذهب باليورو. وكل إخفاق في ذاكرة التخزين المؤقت يكلّف طلبًا واحدًا، لذا يستهلك transient مدته 10 دقائق نحو 4,500 طلب شهريًا كحد أقصى لكل عملة ووحدة تعرضها، وهذا يناسب خطة Standard.

وإذا كان لا بد من استدعاء الواجهة من المتصفح، فقيّد المفتاح بنطاقاتك أولًا، كما هو موضح في دليل المصادقة. ومع ذلك، تبقى الودجة الخيار الأبسط لعرض الأسعار ببساطة: لا مفتاح، ولا ذاكرة تخزين مؤقت تديرها، ولا شيء تصونه عندما تغيّر الرموز لاحقًا.