Watch-IP

طلب موقع الزائر من JavaScript في المتصفح

يضيف هذا الدليل استدعاءً كاملاً لـ GET /v1/geo إلى صفحة ويب: حالة تحميل، ونتيجة ناجحة، وحالة احتياطية لوقت فشل الطلب أو غياب أحد الحقول.

قبل أن تبدأ

  • حساب Watch-IP ومفتاح API قابل للنشر خاص بالزوار.
  • نطاقات المصدر المسموح بها للمفتاح مُهيَّأة لتشمل الصفحة التي تختبر منها.
  • صفحة تُقدَّم عبر HTTP(S) — لا يمكن إضافة نطاقات file:// إلى قائمة السماح.

1. استدعاء نقطة النهاية

أرسِل الطلب مع مفتاحك القابل للنشر في ترويسة X-Api-Key. ولأن المفتاح مصمَّم ليكون قابلًا للنشر، فرؤيته في تبويب الشبكة في المتصفح أمر متوقَّع — فالنطاق المدرج في قائمة السماح هو ما يحدّ من استخدامه، لا السرية.

JavaScript

async function loadVisitorLocation() {
  const response = await fetch('https://api.watch-ip.com/v1/geo', {
    headers: { 'X-Api-Key': 'YOUR_PUBLISHABLE_KEY' },
  });

  if (!response.ok) {
    throw new Error(`Visitor geolocation failed (${response.status})`);
  }

  return response.json();
}

2. عرض حالة التحميل، ثم النتيجة

أبقِ واجهة المستخدم الافتراضية ظاهرة إلى أن يُستكمَل الطلب، وتعامل مع كل حقل على أنه قد يكون null. الدولة والمدينة والمنطقة الزمنية هي الحقول التي تبدأ بها معظم عمليات التكامل.

JavaScript

const statusEl = document.querySelector('#location-status');
statusEl.textContent = 'جارٍ تحديد منطقتك…';

try {
  const geo = await loadVisitorLocation();
  statusEl.textContent = geo.city && geo.country
    ? `عرض المحتوى الخاص بـ ${geo.city}، ${geo.country}`
    : 'استخدام المنطقة الافتراضية';
} catch {
  statusEl.textContent = 'استخدام المنطقة الافتراضية';
}

3. الحفاظ على اختيار صريح من الزائر

تحقق من وجود تفضيل مخزَّن قبل تطبيق الدولة أو العملة المقترحة، ولا ترجع إلى نتيجة الواجهة البرمجية إلا في حال عدم وجود تفضيل بعد.

JavaScript

const preferred = localStorage.getItem('preferredCountry');
const country = preferred ?? geo.country ?? 'US';

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

يفشل النطاق غير المسموح به في فحص CORS الخاص بالمتصفح قبل أن يرى الكود الخاص بك أي استجابة — وعادةً ما يظهر ذلك كخطأ شبكة عام، لا كنص JSON قابل للقراءة، لذا تحقق أولاً من إعداد النطاقات المسموح بها عندما يفشل الطلب بصمت. الحقل المفقود ليس خطأ: تعامل مع قيمة null للدولة أو المدينة أو المنطقة الزمنية على أنها 'غير متاحة'، لا باعتبارها خللاً.

الخطوة التالية

بمجرد أن يعمل الطلب الأساسي، حدِّد كيف ينبغي أن يتفاعل تطبيقك مع النتيجة — راجع صفحة منتج تحديد الموقع الجغرافي للزائر للاطلاع على نمط التوطين، وصفحة المرجع لمعرفة كل حقل يمكن أن تحتويه الاستجابة.

صفحات ذات صلة