> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# التحقق من الموقع الجغرافي: السياج الجغرافي وبُعد IP

> تأكّد من مكان المستخدم أثناء التحقق مع Didit: موقع الجهاز، السياج الجغرافي، بُعد عنوان IP والمستند، وفحوصات الانتحال. بسعر $0.05 لكل فحص.

تؤكد خطوة التحقق من الموقع الجغرافي في Didit مكان وجود الشخص أثناء إجرائه للتحقق، وذلك من خلال قراءة موقع الجهاز لمرة واحدة (عبر المتصفح أو حزمة SDK الأصلية) أو تحديد موقع اتصال IP، ومطابقته مع المناطق المسموح بها والمحظورة، وموقع IP، والعنوان المذكور في مستنداته.
في سير العمل وواجهة برمجة التطبيقات API، تتمثل هذه الخطوة في ميزة `GEOLOCATION`، وإعداداتها هي مفاتيح `geolocation_*`، وتظهر نتيجتها ضمن `geolocation_checks[]` في قرار الجلسة.

## حالات الاستخدام

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

## آلية العمل

**1. الإشعار والإذن**

يرى الشخص سبب الحاجة إلى موقعه الجغرافي وأنه يُقرأ لمرة واحدة فقط لغرض هذا التحقق.
بعد ذلك يطلب متصفحه أو هاتفه الحصول على الإذن.
تسجل Didit الإشعار الذي وافق عليه (الإصدار واللغة والتوقيت) كقيمة `consent` في النتيجة.

**2. موقع جغرافي واحد لكل محاولة**

يحتفظ العميل بأفضل قراءة حتى تصبح دقيقة بما فيه الكفاية أو تنتهي مهلة المحاولة (المحددة افتراضياً بـ 20 ثانية).
تحمل كل محاولة رمز تحقق (تحدٍّ) للاستخدام لمرة واحدة ويكون صالحاً لمدة 5 دقائق ومرتبطاً بالجلسة، حتى لا يمكن إعادة استخدام الإرسال المعترض عليه.

**3. الفحوصات**

تقيّم Didit الدقة، وحداثة البيانات، وأذونات الموقع التقريبي، وإشارات الانتحال، والمناطق الجغرافية، والمسافة إلى موقع IP وإلى عنوان المستند، ونتائج رصد VPN والبروكسي وTor والمحاكيات، بالإضافة إلى الفحوصات السابقة للشخص.

**4. النتيجة**

تُطلق كل نتيجة يتم رصدها [تحذيراً](https://docs.didit.me/ar/core-technology/location-verification/warnings-location-verification.md) يحدد الإجراء المضبوط له (`NO_ACTION` أو `REVIEW` أو `DECLINE`) حالة الخطوة.
ويعتمد الإجراء الأشد صرامة.

## مصادر الموقع الجغرافي

يمكنك اختيار مصدر تحديد الموقع عبر `geolocation_position_source`.

| القيمة | ما يحدث |
| - | - |
| `device_and_ip` | تتم مطابقة موقع الجهاز مع موقع IP الخاص بالاتصال الذي أُرسل منه. |
| `device_only` | يعتمد موقع الجهاز فقط، ولا تتم مقارنته بموقع IP على الإطلاق. |
| `ip_only` | لا يُطلب من الشخص أي إذن، ويتم تقييم موقع IP للاتصال بدلاً من ذلك (على مستوى المدينة، بنطاق 50 كم)، دون تطبيق قواعد الدقة أو الحداثة أو منح الموقع التقريبي. |
| غير محدد | يُطلب الموقع من الجهاز، وتتم مقارنته بموقع IP الذي رصدته خطوة تحليل الجهاز وعنوان IP في الجلسة. وأي عقدة تتخذ إجراءً بناءً على اكتشاف VPN أو بروكسي أو Tor تقوم بفحص الاتصال وتعمل تماماً مثل `device_and_ip`. |

في العقدة التي تطلب الموقع من الجهاز، تُقيّم أي محاولة بدون موقع على أنها رفض أو فشل فعلي، ولا يحل موقع IP أبداً محل الموقع المفقود.

## الإعدادات الافتراضية والحدود

جميع المفاتيح اختيارية.
تتوفر القائمة الكاملة في [مرجع تكوينات ميزات سير العمل](https://docs.didit.me/ar/management-api/workflows/feature-configs.md#التحقق-من-الموقع).

| الإعداد | القيمة الافتراضية | الحدود |
| - | - | - |
| `geolocation_max_accuracy_radius_m` | 250 m | من 10 إلى 50,000 m |
| `geolocation_max_age_seconds` | 120 s | من 5 إلى 3,600 s |
| `geolocation_timeout_seconds` | 20 s | من 5 إلى 120 s |
| `geolocation_max_attempts` | 3 | من 1 إلى 5 |
| `geolocation_accuracy_mode` | `precise` | `precise` أو `approximate_allowed` |
| `geolocation_low_accuracy_behavior` | `ask_again` | `ask_again` أو `fail` |
| `geolocation_allow_qr_handoff` | مفعّل | مفعّل أو معطّل |
| `geolocation_allow_skip` | معطّل | مفعّل أو معطّل |
| `geolocation_refusal_path` | `retry_then_handoff` | `retry_then_handoff` أو `continue_without_location` أو `end_session` |
| `is_geolocation_geofencing_enabled` | معطّل | مفعّل أو معطّل |
| `geolocation_ip_distance_km` | 200 km | 0 أو أكثر، وتعطّل القيمة `null` المقارنة |
| `geolocation_document_distance_km` | معطّل | 0 أو أكثر |
| `geolocation_travel_tolerance_enabled` | معطّل | المنطقة المعتادة من 10 إلى 500 km (الافتراضي 100)، ومن 1 إلى 90 يوماً (الافتراضي 14) |
| `geolocation_consecutive_mismatch_count` | معطّل | من 2 إلى 10 |

### الإعدادات المسبقة

يحدد `geolocation_preset` الإجراء الافتراضي لكل إجراء تتركه دون تعيين صريح.
يقوم الإعداد `licensing` برفض الموقع إذا كان خارج المناطق المسموح بها، أو داخل منطقة محظورة، أو خلف VPN أو Tor، أو على محاكي، ويحيل البروكسي إلى المراجعة.
أما `fraud_screening` فيطبق نفس الفحوصات ولكنه يحيل كل ما كان سيرفضه `licensing` إلى المراجعة.
أي إجراء تحدده صراحةً يكون له الأولوية دائماً.

## السياج الجغرافي

قم بتفعيل `is_geolocation_geofencing_enabled` وحدد قائمة `geolocation_areas`.
يمكن أن تكون المنطقة دولة بأكملها، أو أقاليم تابعة لدولة واحدة (ISO 3166-2)، أو دائرة جغرافية (من 1 إلى 500 كم)، أو مضلعاً (من 3 إلى 200 نقطة).
لا تنجح الخطوة إلا إذا كان الموقع داخل منطقة مسموح بها، ودائماً ما تسود المنطقة المحظورة على المنطقة المسموح بها.
تتسع القائمة لما يصل إلى 50 منطقة، وتتطلب منطقة مسموحاً بها واحدة على الأقل.

تقيّم Didit دائرة الدقة الكاملة للموقع، وليس مجرد نقطة المنتصف:

* الدائرة التي تقع بالكامل خارج كل المناطق المسموح بها تُصنف كـ `LOCATION_OUTSIDE_GEOFENCE`.
* الدائرة التي تتقاطع مع حد جغرافي يفصل في القرار تُصنف كـ `LOCATION_GEOFENCE_UNDETERMINED`، ولا تُعتبر "خارج النطاق" مطلقاً.
* الدائرة التي تقع بالكامل داخل منطقة محظورة تُصنف كـ `LOCATION_IN_BLOCKED_AREA`، وتصدر بالإضافة إلى نتيجة المنطقة المسموح بها.

تنتهي حدود الدولة أو الإقليم عند بداية حدود يابسة أخرى، وليس عند شريطها الساحلي.
تظهر للشخص الأماكن التي تتوفر فيها الخدمة، ولكن لا يُعرض له أبداً أيٌّ من المناطق المحظورة.
تعمل قواعد المناطق أيضاً في الخطوات التي تعتمد `ip_only`، ويتم تقييمها بناءً على موقع IP.
لا يزال إعداد `geolocation_geofencing_by_country` القديم يعمل، ولكنه لا يتوافق مع `geolocation_areas`.

## عمليات التحقق من المسافة

| التحقق | يُقاس بين | الإعداد |
| - | - | - |
| مسافة IP | موقع الجهاز وموقع عنوان IP، بعد طرح نصفي قطري عدم اليقين لكليهما (0 تعني أنهما متداخلان). | `geolocation_ip_distance_km`, `geolocation_ip_distance_action` |
| مسافة المستند | الموقع وعنوان ما، محدد جغرافياً بصورة تقريبية، لذا فهي إشارة ضعيفة. | `geolocation_document_distance_km`, `geolocation_document_distance_basis`, `geolocation_document_distance_action` |
| التتابع | عمليات التحقق السابقة للشخص (نفس `vendor_data`) التي كانت خارج المنطقة المسموح بها، أو في منطقة محظورة، أو بعيدة جداً عن العنوان. | `geolocation_consecutive_mismatch_count` |

يحدد `geolocation_document_distance_basis` العنوان: `document` (مستند الهوية، ثم إثبات العنوان)، أو `proof_of_address`، أو `declared` (`expected_details.address` من إنشاء الجلسة).
مع تفعيل `geolocation_travel_tolerance_enabled`، لن يُوضَع على الشخص تنبيه إذا شوهد بالقرب من عنوانه خلال آخر `geolocation_travel_max_days` يوماً بسبب بعده عنه الآن.
لا يعفي التسامح مع السفر أبداً من وجود VPN، أو انتحال الموقع، أو التواجد في منطقة محظورة، أو في موقع خارج المناطق المسموح بها.

## إشارات الانتحال والسلامة

* **موفرو المواقع الوهمية**: يبلّغ نظاما Android وiOS عندما يكون الموقع محاكياً بدلاً من قياسه فعلياً.
* **إقرار الجهاز**: يمكن لحزم SDK الأصلية إرفاق إقرار الجهاز. يؤدي الإقرار الفاشل دائماً إلى الرفض. ويتم تسجيل الإقرار المفقود ويكون الإجراء الافتراضي هو عدم اتخاذ أي إجراء. لا يمكن للمتصفحات تقديم إقرار ويتم تسجيلها كـ `unsupported`، وليس كفشل.
* **VPN والبروكسي وTor**: يتم اكتشافها على الاتصال الذي شارك الموقع. عندما لا يكون الإجراء المحدد لأي منها `NO_ACTION`، يُطلب من الشخص إيقاف تشغيله وإعادة المحاولة طالما بقيت محاولات متاحة.
* **المحاكيات**: يتم الإبلاغ عنها بواسطة التطبيقات الأصلية فقط. تنتهي الخطوة بسبب المحاكي في تلك المحاولة نظراً لأن إعادة المحاولة لن تغير الجهاز.
* **إعادة استخدام التحدي**: يؤدي التحدي المقدم في جلسة أخرى دائماً إلى الرفض.

## النتائج

تحتوي المحاولة المقبولة للخطوة على `outcome` واحد:

| النتيجة | المعنى |
| - | - |
| `verified` | موقع استوفى كل قاعدة. |
| `low_accuracy` / `accuracy_undetermined` | كان نصف القطر أوسع من الحد المسموح، أو لم يبلّغ الجهاز عن أي نصف قطر. |
| `stale` | كان الموقع أقدم من `geolocation_max_age_seconds`. |
| `approximate` | تم منح موقع تقريبي فقط بينما كان الموقع الدقيق مطلوباً. |
| `denied` / `restricted` | رفض الشخص، أو أن النظام يحظر الموقع. |
| `unavailable` / `timeout` | لم يعثر الجهاز على أي موقع، أو لم يعثر عليه في الوقت المحدد. |
| `mock_detected` | أبلغ النظام أن الموقع محاكى. |
| `outside_geofence` / `in_blocked_area` | الموقع خارج كل منطقة مسموح بها، أو داخل منطقة محظورة. |
| `anonymizer_detected` | تم العثور على VPN أو بروكسي أو عقدة خروج Tor أو محاكٍ، ويتخذ سير العمل إجراءً بشأنه. |
| `skipped` | تابع الشخص دون مشاركة الموقع. |
| `replay_rejected` | كان التحدي تابعاً لجلسة أخرى. |
| `unsupported_client` | التطبيق أو SDK قديم جداً بحيث لا يمكنه عرض الخطوة. |

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

## تجربة المستخدم

### الموافقة والإذن

لا تتم قراءة أي شيء قبل أن يقبل الشخص الإشعار ويستجيب لمطالبة النظام.
يوضح الإشعار أنه تتم قراءة الموقع مرة واحدة فقط لعملية التحقق هذه، وأنه ليس سجلاً لتحركاته.
يتم التعامل مع الشخص الذي يرفض وفقاً لـ `geolocation_refusal_path`:

* `retry_then_handoff` يطلب المحاولة مرة أخرى طالما بقيت محاولات متاحة ثم يعرض المتابعة على هاتف محمول.
* `continue_without_location` يعرض المتابعة بدون موقع، ويسجل الرفض كالنتيجة.
* `end_session` يُنهي الخطوة والجلسة عند أول رفض. يتطلب أن يكون `geolocation_permission_denied_action` مضبوطاً على `REVIEW` أو `DECLINE`، ولا يتم قبول الجلسة أبداً.

عند تفعيل `geolocation_allow_skip`، يمكن للشخص المتابعة بدون موقع في أي وقت، ويتم تقييم الخطوة بواسطة `geolocation_unavailable_action`.

### المتصفح

يطلب المسار المستضاف الموقع من المتصفح ويعرض مساعدة خطوة بخطوة لمتصفحي Chrome وSafari عندما يكون الموقع الجغرافي معطلاً للموقع الإلكتروني.
لا يمكن للمتصفح التمييز بين منح إذن دقيق ومنح إذن تقريبي، لذا لا تؤدي نتائج الويب أبداً إلى إثارة `LOCATION_APPROXIMATE_ONLY`، ولا يُبلّغ المتصفح أبداً عن موفر موقع وهمي أو محاكٍ أو إقرار الجهاز.
لا يمكن لجهاز الكمبيوتر مشاركة موقع دقيق، لذا يقدم المسار رمز QR يتيح متابعة عملية التحقق نفسها على هاتف الشخص (`geolocation_allow_qr_handoff`، مفعل افتراضياً)، وينتقل الكمبيوتر للمتابعة تلقائياً بمجرد انتهاء الهاتف.
عند تضمين المسار في iframe، قم بتضمين `geolocation` في السمة `allow`، راجع [iframe في السياق](https://docs.didit.me/ar/integration/web-sdks/incontext-iframe.md).
تُعامل الصفحة التي تحظر سياسة إذن تحديد الموقع الجغرافي على أنها قرار من الموقع، وليس رفضاً من الشخص.

### حزم SDK الأصلية

تطلب حزم SDK لنظامي iOS وAndroid الإذن من نظام التشغيل ويمكنها إرفاق إقرار الجهاز وعلامات الموقع الوهمي.
في نظام iOS، أضف `NSLocationWhenInUseUsageDescription` إلى `Info.plist`، وفي نظام Android تعلن حزمة SDK عن `ACCESS_FINE_LOCATION` و`ACCESS_COARSE_LOCATION` وتطلب الإذن أثناء وقت التشغيل فقط عندما يتضمن سير العمل هذه الخطوة.
راجع [حزم SDK الأصلية](https://docs.didit.me/ar/integration/native-sdks/overview.md).
يؤدي منح إذن تقريبي على iOS أو Android إلى إثارة `LOCATION_APPROXIMATE_ONLY` ما لم يكن `geolocation_accuracy_mode` مضبوطاً على `approximate_allowed`.
تُنهى الخطوة بالحالة `unsupported_client` عند استخدام إصدار من التطبيق أو حزمة SDK أقدم من هذه الخطوة، بدلاً من ترك الجلسة معلقة.

## ما يعيده القرار

يتضمن [قرار الجلسة](https://docs.didit.me/ar/sessions-api/retrieve-session.md) وwebhook الخاص بـ `status.updated` قائمتين:

* `geolocation_checks[]`: عنصر واحد لكل خطوة Location، ويحتوي على المحاولة المقبولة لتلك الخطوة، مع `warnings` الخاصة بها.
* `geolocation_attempts[]`: كل محاولة لكل خطوة Location، بدءاً من الأقدم.

راجع [تقرير التحقق من الموقع](https://docs.didit.me/ar/core-technology/location-verification/report-location-verification.md) للاطلاع على كل حقل.
تُعد الإحداثيات والدقة والمدينة والدولة بيانات شخصية للمستخدم النهائي، لذا يمكن لسمات الاستجابة في سير العمل تقييد حقول `geolocation_checks` التي يعيدها قرارك.

## الأسعار

تبلغ تكلفة التحقق من الموقع **\$0.05 لكل فحص**، وهو ليس جزءاً من المستوى المجاني.
تفرض Didit الرسوم مرة واحدة لكل خطوة Location في الجلسة، أياً كانت نتيجتها، نظراً لتشغيل الفحص وإرجاع نتيجة.
تكون عمليات إعادة المحاولة ضمن الخطوة نفسها مجانية.
تُفرض الرسوم مجدداً على كل عملية إعادة إرسال تُكمل الخطوة مرة أخرى.

## البيئة التجريبية

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

## مواضيع ذات صلة

* [تقرير التحقق من الموقع](https://docs.didit.me/ar/core-technology/location-verification/report-location-verification.md) - كل حقل في `geolocation_checks[]` و`geolocation_attempts[]`.
* [تحذيرات التحقق من الموقع](https://docs.didit.me/ar/core-technology/location-verification/warnings-location-verification.md) - كل رمز `LOCATION_*` والإجراء الخاص به.
* [تكوينات ميزات سير العمل](https://docs.didit.me/ar/management-api/workflows/feature-configs.md#التحقق-من-الموقع) - كل مفتاح `geolocation_*`.
* [تحليل الجهاز وعنوان IP](https://docs.didit.me/ar/core-technology/ip-analysis/overview.md) - التحديد الجغرافي لعنوان IP وفحوصات VPN للجلسة.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.