واجهة برمجة تطبيقات المناطق الجغرافية (Geozones API)

getNearestZone

تُستدعى داخليًا من SDK. تسترجع معلمات أقرب منطقة جغرافية والمسافة إليها. كما تسجل موقع الجهاز لإشعارات الدفع الجغرافية.

POST https://api.pushwoosh.com/json/1.3/getNearestZone

معلمات جسم الطلب

المعلمة	النوع	مطلوب	الوصف
application	string	نعم	رمز تطبيق Pushwoosh
hwid	string	نعم	معرف جهاز الهاردوير المستخدم في طلب /registerDevice.
lat	string	نعم	خط عرض الجهاز.
lng	string	نعم	خط طول الجهاز.

مثال على الطلب

{
  "request": {
    "application": "APPLICATION_CODE",
    "hwid": "HWID",
    "lat": 10.12345,
    "lng": 28.12345
  }
}

مثال PHP

// انظر http://gomoob.github.io/php-pushwoosh/get-nearest-zone.html

use Gomoob\Pushwoosh\Model\Request\GetNearestZoneRequest;

// إنشاء نسخة الطلب
$request = GetNearestZoneRequest::create()
    ->setHwid('HWID')
    ->setLat(10.12345)
    ->setLng(28.12345);

// استدعاء خدمة الويب '/getNearestZone'
$response = $pushwoosh->getNearestZone($request);

if ($response->isOk()) {
    print 'اسم المنطقة : ' . $response->getResponse()->getName();
    print 'خط العرض : ' . $response->getResponse()->getLat();
    print 'خط الطول : ' . $response->getResponse()->getLng();
    print 'النطاق : ' . $response->getResponse()->getRange();
    print 'المسافة : ' . $response->getResponse()->getDistance();
} else {
    print 'عفوًا، فشلت العملية :-(';
    print 'رمز الحالة : ' . $response->getStatusCode();
    print 'رسالة الحالة : ' . $response->getStatusMessage();
}

addGeoZone

تضيف منطقة جغرافية (Geozone) إلى تطبيق معين.

POST https://api.pushwoosh.com/json/1.3/addGeoZone

معلمات جسم الطلب

المعلمة	النوع	مطلوب	الوصف
auth	string	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
application	string	نعم	رمز تطبيق Pushwoosh
geozones	array	نعم	معلمات المنطقة الجغرافية كمصفوفة JSON.
geozones.name	string	نعم	اسم المنطقة الجغرافية.
geozones.lat	string	مطلوب للدائرة.	خط عرض المنطقة الجغرافية. يُحذف عند تعيين polygon — تستمد المنطقة الجغرافية المضلعة مركزها الخاص.
geozones.lng	string	مطلوب للدائرة.	خط طول المنطقة الجغرافية. يُحذف عند تعيين polygon — تستمد المنطقة الجغرافية المضلعة مركزها الخاص.
geozones.cooldown	integer	نعم	فترة الصمت بعد إرسال إشعار (بالثواني).
geozones.range	integer	مطلوب للدائرة.	نطاق المنطقة الجغرافية بالأمتار. الحد الأدنى 50. يُحذف عند تعيين polygon — تستمد المنطقة الجغرافية المضلعة نطاقها الخاص.
geozones.polygon	object	لا	يجعل المنطقة الجغرافية مضلعًا بدلاً من دائرة. لا يمكن دمجه مع lat/lng/range — سيتم رفض إرسال كليهما. انظر المناطق الجغرافية المضلعة.
geozones.content	string or object	مطلوب إذا كان presetCode فارغًا.	محتوى رسالة المنطقة الجغرافية.
geozones.presetCode	string	مطلوب إذا كان content فارغًا.	إعداد مسبق للدفع (Push preset) لاستخدامه بدلاً من content.
geozones.cluster	string	لا	حدد null لإلغاء ربط مجموعة (cluster) من المنطقة الجغرافية.
geozones.campaign	string	لا	حدد null لإلغاء ربط حملة (campaign) من المنطقة الجغرافية. إذا تم حذفه، ستبقى قيمة الحملة دون تغيير. ملاحظة: له أولوية أعلى من الحملة في الإعداد المسبق.
geozones.timetable	object	لا	يضبط فترات الجدول الزمني.

مثال على الطلب

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX",            // رمز تطبيق Pushwoosh
    "geozones": [{
      "name": "Statue of George",            // مطلوب. اسم المنطقة الجغرافية.
      "lat": "40.70087797",                   // مطلوب. خط عرض المنطقة الجغرافية.
      "lng": "-73.931851387",                 // مطلوب. خط طول المنطقة الجغرافية.
      "cooldown": 60,                         // بالثواني، مطلوب. فترة الصمت بعد إرسال إشعار
      "range": 50,                            // بالأمتار، الحد الأدنى 50، مطلوب. نطاق المنطقة الجغرافية.
      "content": "Lorem ipsum dolor sit amet,
       consectetur adipiscing elit.",         // أو كائن
      "presetCode": "AAAAA-BBBBB",            // اختياري. يمكن استخدام إعداد الدفع المسبق بدلاً من المحتوى
      "cluster": "GEOZONE CLUSTER CODE",      // اختياري. سيتم تطبيق فترة التهدئة للمجموعة
      "campaign": "CAMPAIGN_CODE",            // اختياري. حدد null لإلغاء ربط الحملة من المنطقة الجغرافية
      "timetable": {                          // اختياري
        "timezone": 1234,                     // بالثواني
        "Mon": [                              // الأيام المتاحة: Mon, Tue, Wed, Thu, Fri, Sat, Sun. إرسال الإشعارات
          {
            "start": "04:11",
            "stop": "12:00"
          }
        ],
        "Sun": [
          {                                    // فترة واحدة أو فترتان
            "start": "01:11",
            "stop": "17:00"
          },
          {
            "start": "18:01",
            "stop": "23:59"
          }
        ]
      }
    }]
  }
}

إضافة عدة مناطق جغرافية دفعة واحدة

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

{
  "status_code": 210,
  "status_message": "geozones[301]: range: يجب أن يكون النطاق 50 مترًا على الأقل"
}

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

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

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "GeoZones": [100016750, 100016751],
    "Errors": [{ "index": 2, "message": "لم يتم العثور على الإعداد المسبق" }]
  }
}

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

تنبيه

أسماء المناطق الجغرافية ليست فريدة. إعادة إرسال دفعة نجحت بالفعل تنشئ نسخة ثانية من كل منطقة جغرافية فيها.

المناطق الجغرافية المضلعة

أرسل polygon بدلاً من lat/lng/range لجعل المنطقة الجغرافية مضلعًا. polygon.vertices هي حلقة مرتبة من نقاط {lat, lng} تصف محيط الشكل:

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",
    "application": "XXXXX-XXXXX",
    "geozones": [{
      "name": "Downtown mall — ground floor",
      "cooldown": 60,
      "polygon": {
        "vertices": [
          { "lat": 40.70087797, "lng": -73.931851387 },
          { "lat": 40.70112456, "lng": -73.931602211 },
          { "lat": 40.70095321, "lng": -73.930987654 },
          { "lat": 40.70068912, "lng": -73.931233456 }
        ]
      },
      "content": "أهلاً بك! استمتع بخصم 15% على أول عملية شراء لك اليوم."
    }]
  }
}

يتم اشتقاق lat و lng و range من الحلقة — الدائرة التي يراقبها الجهاز بالفعل تتمركز على الشكل بنصف قطر يصل إلى أبعد رأس له (الحد الأدنى 50 مترًا). يتم رفض إرسال polygon مع lat/lng/range.

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

updateGeoZone

تحديث خصائص المنطقة الجغرافية.

POST https://api.pushwoosh.com/json/1.3/updateGeoZone

معلمات جسم الطلب

المعلمة	النوع	مطلوب	الوصف
auth	string	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
geoZoneId	string	نعم	معرف المنطقة الجغرافية (Geozone ID) من طلب /addGeoZone.
name	string	لا	اسم المنطقة الجغرافية الجديد.
cooldown	integer	لا	فترة التهدئة للتحديث، بالثواني.
status	integer	لا	0 - غير مفعل، 1 - مفعل.
content	string	لا	محتوى إشعار الدفع للمنطقة الجغرافية. لا يمكن استخدامه مع presetCode.
cluster	string	لا	اسم المجموعة الجديد. حدد null لإلغاء ربط المجموعة من المنطقة الجغرافية.
campaign	string	لا	معرف الحملة الجديد. حدد null لإلغاء ربط الحملة من المنطقة الجغرافية. إذا تم حذفه، لن تتغير قيمة الحملة. له أولوية أعلى من الحملة من الإعداد المسبق.
lat	number	لا	خط عرض المنطقة الجغرافية. لا يمكن دمجه مع polygon.
lng	number	لا	خط طول المنطقة الجغرافية. لا يمكن دمجه مع polygon.
range	integer	لا	النطاق الجديد بالأمتار. لا يمكن دمجه مع polygon.
polygon	object	لا	حلقة جديدة من رؤوس {lat, lng} — تستبدل الشكل وتعيد اشتقاق lat/lng/range منه. انظر المناطق الجغرافية المضلعة. يعمل في كلا الاتجاهين: أرسله على منطقة جغرافية دائرية موجودة لتحويلها إلى مضلع، أو أرسل حلقة فارغة ({"vertices": []}) على منطقة جغرافية مضلعة موجودة لتحويلها مرة أخرى إلى دائرة. احذف polygon بالكامل لترك الشكل دون تغيير. نفس التحقق من صحة الرؤوس مثل addGeoZone.
timetable	object	لا	الجدول الزمني للمنطقة الجغرافية. انظر المزيد من المعلومات أدناه.

---

مثال على الطلب

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "geoZoneId": 100016750,                  // مطلوب، من طريقة /addGeoZone
    "name": "new geozone name",              // اختياري
    "cooldown": 222,                         // بالثواني، اختياري
    "status": 0,                             // اختياري، 0 - غير مفعل، 1 - مفعل
    "presetCode": "BBBBB-AAAAA",             // اختياري، لا يمكن استخدامه مع "content"
    "content": "new geozone content",        // اختياري، لا يمكن استخدامه مع "presetCode"
    "cluster": "GEOZONE CLUSTER CODE",       // اختياري. حدد null لإلغاء ربط المجموعة من المنطقة الجغرافية
    "campaign": "CAMPAIGN_CODE",             // اختياري. حدد null لإلغاء ربط الحملة من المنطقة الجغرافية
    "lat": 10.56,                            // اختياري، خط عرض المنطقة الجغرافية
    "lng": 12.523,                           // اختياري، خط طول المنطقة الجغرافية
    "range": 500,                            // اختياري، نطاق المنطقة الجغرافية
    "timetable": {                           // اختياري
      "timezone": 1234,                      // بالثواني
      "Mon": [                               // الأيام المتاحة: Mon, Tue, Wed, Thu, Fri, Sat, Sun. إرسال الإشعارات
        {
          "start": "04:11",
          "stop": "12:00"
        }
      ],
      "Sun": [
        {                                    // فترة واحدة أو فترتان
          "start": "01:11",
          "stop": "17:00"
        },
        {
          "start": "18:01",
          "stop": "23:59"
        }
      ]
    }
  }
}

deleteGeoZone

إزالة المناطق الجغرافية من التطبيق.

POST https://api.pushwoosh.com/json/1.3/deleteGeoZone

معلمات جسم الطلب

المعلمة	النوع	مطلوب	الوصف
auth	string	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
application	string	نعم	رمز تطبيق Pushwoosh
geozones	string	نعم	مصفوفة من المعرفات أو معرف واحد لمنطقة جغرافية لإزالتها.

مثال على الطلب

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX",            // مطلوب، رمز تطبيق Pushwoosh
    "geozones": [550, 526]                   // مطلوب، معرفات المناطق الجغرافية
  }
}

addGeoZoneCluster

إضافة مجموعة مناطق جغرافية (Geozone Cluster) إلى التطبيق.

POST https://api.pushwoosh.com/json/1.3/addGeoZoneCluster

معلمات جسم الطلب

المعلمة	النوع	مطلوب	الوصف
auth	string	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
application	string	نعم	رمز تطبيق Pushwoosh
name	string	نعم	اسم المجموعة.
cooldown	integer	نعم	تأخير قبل أن يتمكن مستخدم واحد من تلقي نفس الرسالة من مجموعة المناطق الجغرافية، بالثواني.

مثال على الطلب

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX",            // مطلوب، رمز تطبيق Pushwoosh
    "name": "Raccoon city",                  // مطلوب، اسم المجموعة
    "cooldown": 3210                         // مطلوب، بالثواني
  }
}

deleteGeoZoneCluster

إزالة مجموعة مناطق جغرافية من التطبيق.

POST https://api.pushwoosh.com/json/1.3/deleteGeoZoneCluster

معلمات جسم الطلب

المعلمة	النوع	مطلوب	الوصف
auth	string	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
application	string	نعم	رمز تطبيق Pushwoosh
geoZoneCluster	string	نعم	معرف مجموعة المناطق الجغرافية المراد إزالتها.

مثال على الطلب

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX",            // مطلوب، رمز تطبيق Pushwoosh
    "geoZoneCluster": "EA1CE-69405"          // مطلوب، معرف المجموعة الذي تم الحصول عليه من طلب /addGeoZoneCluster
  }
}

listGeoZones

استرداد قائمة بالمناطق الجغرافية للتطبيق.

POST https://api.pushwoosh.com/json/1.3/listGeoZones

معلمات جسم الطلب

المعلمة	النوع	مطلوب	الوصف
auth	string	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
application	string	نعم	رمز تطبيق Pushwoosh

مثال على الطلب

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX"             // مطلوب، رمز تطبيق Pushwoosh
  }
}

listGeoZoneClusters

استرداد قائمة بمجموعات المناطق الجغرافية للتطبيق.

POST https://api.pushwoosh.com/json/1.3/listGeoZoneClusters

معلمات جسم الطلب

المعلمة	النوع	مطلوب	الوصف
auth	string	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
application	string	نعم	رمز تطبيق Pushwoosh

مثال على الطلب

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX"             // مطلوب، رمز تطبيق Pushwoosh
  }
}