واجهة برمجة تطبيقات الجهاز

تسجّل واجهة برمجة تطبيقات الجهاز الأجهزة في تطبيق Pushwoosh وتسجّل نشاطها: قيم العلامات، وفتح التطبيق، وفتح رسائل push، وتسليم رسائل push. يستدعي Pushwoosh SDK معظم هذه الطرق تلقائيًا، لذا استدعها مباشرةً عندما تدير الأجهزة من الخادم الخاص بك أو من عميل مخصص. لتسجيل العديد من الأجهزة أو تعيين العلامات لها في طلب واحد، استخدم واجهة برمجة تطبيقات الجمهور (Audience API).

registerDevice

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

يتم استدعاؤها داخليًا من SDK. تسجل الجهاز للتطبيق.

ترويسات الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز API للجهاز للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز API الفعلي لجهازك.

نص الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
push_token	string	رمز الدفع للجهاز.
language	string	اللغة المحلية للجهاز. يجب أن يكون رمزًا من حرفين صغيرين وفقًا لمعيار ISO-639-1.
hwid*	string	سلسلة فريدة لتعريف الجهاز (IDFV على iOS، قيمة يتم إنشاؤها عشوائيًا على Android). اعرف المزيد
timezone	integer	إزاحة المنطقة الزمنية بالثواني للجهاز.
device_type*	integer	نوع الجهاز. انظر القيم الممكنة أدناه.
email	string	عنوان البريد الإلكتروني للتسجيل (يستخدم لمستخدمي البريد الإلكتروني بدلاً من HWID ورمز الدفع).
tags	object	قيم العلامات لتعيينها للجهاز المسجل.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "request": {
    "application": "XXXXX-XXXXX",        // required. Pushwoosh application code
    "push_token": "dec301908b9ba8XXXXX57a58e40f96f5XXXXX2068674f5XXXXa25cdc250a2a41", // optional.
    "hwid": "1CA6XXXXX-8DAC-XXXXX-XXXXX-B756288B6D3C",                                   // required. Hardware device ID
    "idfa": "AEBE52E7-0XXXXX-455A-XXXXX-E57283966239",                                   // optional.
    "timezone": 3600,                    // optional. Offset in seconds
    "device_type": 1,                    // required. See the possible values below. For emails,
                                         //           use the "emails" params as described below.
    "email": "email_address@domain.com", // use instead of "hwid" and "push_token" to register
                                         //           the email address for your email project
    "language": "en",                    // optional. ISO 639-1|639-2 language code
    "userId": "Alex",                    // optional.
    "tags": {                            // optional. Tag values to set for the device registered
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // sets the list of values for Tags of List type
      "DateTag": "2024-10-02 22:11",     // note the time should be in UTC
      "BooleanTag": true                 // valid values are: true, false
    },

    // system tags, optionals
    "app_version": "1.2.3",
    "device_model": "Samsung SM-G355H",
    "os_version": "2.3",

    // optional encryption keys for chrome/firefox
    "public_key": "BNmDO4BTKEMJqaqprTf7t/HBXXXXX/orcXXXXX/scS5CFP6XXXXXHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "auth_token": "RlRmCXXXXX/s7XXXXXjKFzoQ==",

    // optional FCM keys for Chrome (for XMPP)
    "fcm_token": "BNmDO4BTKEMJXXXXXprTf7t/XXXXXBQ/orXXXXXc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "fcm_push_set": "RlXXXXXGM/s7XXXXXjKFzoQ=="
  }
}

أنواع الأجهزة الممكنة:

1 – iOS
3 – Android
7 – Mac OS X
8 – Windows
9 – Amazon
10 – Safari
11 – Chrome
12 – Firefox
13 – Internet Explorer
14 – Email
17 – Huawei
18 – SMS
20 – Web
21 – WhatsApp
22 – Line
23 – Kakao Talk
24 – Telegram
25 – Apple Wallet
26 – Google Wallet
27 – Viber

تسجيل أجهزة البريد الإلكتروني

لتسجيل مشترك بريد إلكتروني لتطبيقك، أرسل المعلمة "email": "email_address@domain.com" في طلب /registerDevice أو /registerEmail كما يلي:

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

{
  "request":{
    "application": "XXXXX-XXXXX",        // required. Pushwoosh application code
    "email": "email_address@domain.com", // required. Email address to register for your email project
    "language": "en",                    // optional. ISO 639-1|639-2 language code
    "userId": "Alex",                    // optional.
    "tags": {                            // optional. Tag values to set for the device registered
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // sets the list of values for Tags of List type
      "DateTag": "2024-10-02 22:11",     // note the time should be in UTC
      "BooleanTag": true                 // valid values are: true, false
    }
  }
}

تسجيل أجهزة WhatsApp

لتسجيل جهاز WhatsApp لتطبيقك، اتبع هذه الإرشادات:

hwid: تأكد من أن هذا الحقل يتضمن البادئة whatsapp: متبوعة برقم الهاتف بتنسيق E.164 (على سبيل المثال، whatsapp:+0000000000). يجب أن يكون رقم الهاتف صالحًا، وهو ما ستتحقق منه Pushwoosh.
رمز الدفع: رمز الدفع غير مطلوب، حيث سيعمل hwid تلقائيًا كرمز دفع.
device_type: اضبط هذا الحقل على 21 لتحديد WhatsApp كمنصة.

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

{
  "request": {
    "application": "XXXXX-XXXXX",        // required. Pushwoosh application code
    "hwid": "whatsapp:+0000000000",      // required. WhatsApp prefix and valid phone number
    "timezone": 3600,                    // optional. Time offset in seconds
    "device_type": 21,                   // required. WhatsApp device type is 21
    "language": "en",                    // optional. ISO 639-1|639-2 language code
    "userId": "Alex",                    // optional. User identifier
    "tags": {                            // optional. Tag values for custom segmentation
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",     // UTC format
      "BooleanTag": true
    },
    "app_version": "1.2.3",              // optional. Application version
    "device_model": "Samsung SM-G355H",  // optional. Device model
    "os_version": "2.3"                  // optional. Operating system version
  }
}

تسجيل أجهزة SMS

لتسجيل جهاز SMS لتطبيقك، اتبع هذه الإرشادات:

hwid: تأكد من أن هذا الحقل يتضمن رقم الهاتف بتنسيق E.164 (على سبيل المثال، +0000000000). يجب أن يكون رقم الهاتف صالحًا، وهو ما ستتحقق منه Pushwoosh.
رمز الدفع: رمز الدفع غير مطلوب، حيث سيعمل hwid تلقائيًا كرمز دفع.
device_type: اضبط هذا الحقل المطلوب على 18 لتحديد SMS كمنصة.

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

{
   "request": {
      "application": "XXXXX-XXXXX",           // required. Pushwoosh application code
      "hwid": "+0000000000",                  // required. Valid phone number in E.164 format
      "timezone": 3600,                       // optional. Time offset in seconds
      "device_type": 18,                      // required. SMS device type is 18
      "language": "en",                       // optional. ISO 639-1|639-2 language code
      "userId": "Alex",                       // optional. User identifier
      "tags": {                               // optional. Tag values for custom segmentation
           "StringTag": "string value",
           "IntegerTag": 42,
           "ListTag": ["string1", "string2"],
           "DateTag": "2024-10-02 22:11",     // UTC format
           "BooleanTag": true
      },
      "app_version": "1.2.3",                 // optional. Application version
      "device_model": "Samsung SM-G355H",     // optional. Device model
      "os_version": "2.3"                     // optional. Operating system version
   }
}

رموز الحالة:

رمز حالة HTTP	status_code	الوصف
200	200	تم تسجيل الجهاز بنجاح
200	210	خطأ في الوسيطة. انظر `status_message` لمزيد من المعلومات.
400	N/A	سلسلة طلب غير صالحة
500	500	خطأ داخلي

unregisterDevice

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

يزيل رمز الدفع الخاص بالجهاز. لا يزال الجهاز غير المسجل يُحتسب في إجمالي الأجهزة ويمكن الوصول إليه باستخدام In-Apps. يتم استدعاؤه داخليًا من SDK.

ترويسات الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز API للجهاز للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز API الفعلي لجهازك.

نص الطلب

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

{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}

{
  "request": {
    "application": "XXXXX-XXXXX",              // required. Pushwoosh application code
    "hwid": "8f65b16XXXXXe7a6beceXXXXX530fb2"  // required. Hardware device ID used in /registerDevice API
  }
}

رموز الحالة:

رمز حالة HTTP	status_code	الوصف
200	200	تم إلغاء اشتراك الجهاز بنجاح
200	210	خطأ في الوسيطة. انظر `status_message` لمزيد من المعلومات.
400	N/A	سلسلة طلب غير صالحة
500	500	خطأ داخلي

deleteDevice

POST https://api.pushwoosh.com/api/v2/device-api/deleteDevice

يحذف جهازًا وجميع بياناته المرتبطة به المحددة بواسطة HWID المحدد داخل التطبيق. على عكس /unregisterDevice، الذي يزيل فقط رمز الدفع ويحتفظ بسجل الجهاز، فإن /deleteDevice يزيل الجهاز بالكامل. تتم معالجة الطلب بشكل غير متزامن، وتعيد نقطة النهاية 200 OK بمجرد قبول طلب الحذف للمعالجة.

ترويسات الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز API للجهاز للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز API الفعلي لجهازك.
Content-Type	نعم	application/json

نص الطلب

الاسم	مطلوب	النوع	الوصف
application	نعم	string	رمز تطبيق Pushwoosh
hwid	نعم	string	معرف جهاز الجهاز للجهاز المراد حذفه.

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

{
  "application": "XXXXX-XXXXX",                 // required. Pushwoosh application code
  "hwid": "8f65b16df378e7a6bece9614e1530fb2"    // required. Hardware device ID of the device to delete
}

مثال على الاستجابة

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

رموز الحالة

رمز حالة HTTP	status_code	الوصف
200	200	تم قبول طلب الحذف
200	210	خطأ في الوسيطة. انظر `status_message` لمزيد من المعلومات.
400	N/A	سلسلة طلب غير صالحة
401	N/A	رمز `Authorization` مفقود أو غير صالح
500	500	خطأ داخلي

setTags

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

يضبط قيم العلامات للجهاز. يتم استدعاؤه من SDK.

ترويسات الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز API للجهاز للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز API الفعلي لجهازك.

نص الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
hwid*	string	معرف جهاز الجهاز المستخدم في طلب /registerDevice.
tags*	object	كائن JSON للعلامات المراد تعيينها، أرسل “null” لإزالة القيمة.

{
   "status_code": 200,
   "status_message": "OK",
   "response": null
}

يتم استدعاء الطريقة من SDK. من الممكن استدعاؤها عن بعد من الواجهة الخلفية الخاصة بك، ولكنك تحتاج إلى الحفاظ على قاعدة بيانات محدثة من hwids على جانب الواجهة الخلفية. يتم إنشاء اسم علامة غير موجود بعد تلقائيًا، مع استنتاج النوع من القيمة: يصبح الرقم الصحيح Integer، ويصبح الرقم الذي يحتوي على فاصلة عشرية Price، وتصبح السلسلة String (أو Date، لتنسيق تاريخ ووقت معترف به مثل 2024-10-02 22:11)، وتصبح المصفوفة List، وتصبح القيمة المنطقية Boolean. تكون العلامة المُنشأة تلقائيًا دائمًا من نوع User-specific. قم بإنشاء علامة Version، التي لا يمكن للإنشاء التلقائي استنتاجها، أو علامة General بشكل صريح أولاً، عبر لوحة التحكم أو /addTag. يتم تمكين الإنشاء التلقائي للعلامات افتراضيًا لغالبية الحسابات. إذا لم تقم setTags بإنشاء علامة جديدة كما هو متوقع، فاتصل بـ دعم Pushwoosh للتحقق مما إذا كان قد تم إيقاف تشغيله لحسابك.

{
  "request":{
    "application": "XXXXX-XXXXX",               // required. Pushwoosh application code
    "hwid": "8f65b16XXXXXe7a6becXXXXXe1530fb2", // required. Hardware device ID used in /registerDevice API
    "tags": {                                   // required.
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],        // sets the list of values for Tags of List type
      "DateTag": "2024-10-02 22:11",            // note the time is in UTC
      "BooleanTag": true                        // valid values are - true, false
    }
  }
}

زيادة قيم علامة Integer

لزيادة قيمة علامة Integer، استخدم المعلمة operation مع القيمة “increment” كما يلي:

{
  "request":{
    "application": "12345-67890",                   // required. Pushwoosh application code
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. hardware device ID used in /registerDevice API
    "tags": {                                       // required.
      "Level": {                                    // Tag name
        "operation": "increment",                   // overwrites the integer tag in increments of the following value
        "value": 1                                  // increment for the tag value
      }
    }
  }
}

إنقاص قيم علامة Integer

لإنقاص القيمة، استخدم الأرقام السالبة كقيمة لعملية “increment” (-1, -2, -3,-n):

{
  "request":{
    "application": "12345-67890",                   // required. Pushwoosh application code
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API
    "tags": {                                       // required
      "Level": {                                    // Tag name
        "operation": "increment",                   // overwrites the integer tag in decrement of the following value
        "value": -1                                 // decrement for the tag value
      }
    }
  }
}

إلحاق قيم علامة List

لتوسيع علامة List بقيم جديدة، استخدم المعلمة operation مع القيمة “append” كما يلي:

{
  "request": {
    "hwid": "3d124a79XXXXf189XXXX7dfd9XXXXafd", // required. Hardware device ID used in /registerDevice API
    "application": "6XXXX-XXXX3",               // required. Pushwoosh application code
    "tags": {                                   // required.
      "ListTag": {                              // Tag name
        "operation": "append",                  // appends following values to the Tag's list of values
        "value": [                              // values to append
          "tag2",
          "tag3"
        ]
      }
    }
  }
}

إزالة قيم علامة List

لإزالة بعض القيم من علامة List، استخدم عملية “remove” كما يلي:

{
  "request":{
    "application": "12345-67890",                   // required. Pushwoosh application code
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API
    "tags": {                                       // required.
      "In-app Product": {                           // Tag name
        "operation": "remove",                      // removes the following values from the list tag
        "value": "outwear_02"                       // value or values to remove
      }
    }
  }
}

تعيين العلامات بواسطة UserID

لتعيين علامات لجميع الأجهزة المرتبطة بـ User ID معين، استخدم المعلمة “userId” بدلاً من “hwid”.

{
  "request":{
    "application": "AAAAA-BBBBB", // Pushwoosh app code
    "userId": "some_user",        // user ID you'd like to set tags for
    "tags": {                     // tags and values to set
      "Language": "es"
    }
  }
}

رموز الحالة:

رمز حالة HTTP	status_code	الوصف
200	200	تم تعيين العلامات بنجاح
200	210	خطأ في الوسيطة. انظر `status_message` لمزيد من المعلومات.
400	N/A	سلسلة طلب غير صالحة
500	500	خطأ داخلي

getTags

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

يسترد قائمة بالعلامات مع القيم المقابلة للجهاز المحدد.

ترويسات الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز API للجهاز للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز API الفعلي لجهازك.

نص الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
userId	string	User ID لاستخدامه بدلاً من “hwid”. إذا تم استخدامه مع “hwid”، فإن “hwid” له الأسبقية.
hwid	string	معرف جهاز الجهاز المستخدم في طلب `/registerDevice`.

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "result": {
      "Language": "fr"
    }
  }
}

{
  "request":{
    "application": "XXXXX-XXXXX",   // required. Pushwoosh application code
    "hwid": "HWID",                 // optional. Hardware device ID used in /registerDevice API
    "userId": "USER_ID"             // optional. Can be used instead of "hwid" to retrieve tags for a specific user
  }
}

setBadge

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

ترويسات الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز API للجهاز للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز API الفعلي لجهازك.

نص الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
hwid*	string	معرف جهاز الجهاز المستخدم في طلب /registerDevice.
badge*	integer	الشارة الحالية على التطبيق.

{
  "status_code": 200,
  "status_message": "OK"
}

{
  "request":{
    "application": "XXXXX-XXXXX",               // required. Pushwoosh application code
    "hwid": "8f65b16dXXXXe7a6XXXX9614XXXX0fb2", // required. Hardware device ID used in /registerDevice API
    "badge": 4                                  // required. Current badge on the application
  }
}

هذه الطريقة لا تستخدم لتحديث قيمة الشارة على الجهاز. بدلاً من ذلك، يرجى استخدام طلب /createMessage مع المعلمة "ios_badges".

applicationOpen

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

يسجل حدث فتح التطبيق. يتم استدعاؤه داخليًا من SDK.

ترويسات الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز API للجهاز للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز API الفعلي لجهازك.

نص الطلب

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

{
  "status_code": 200,
  "status_message": "OK"
}

{
  "request": {
    "application": "XXXXX-XXXXX",              // required. Pushwoosh application code
    "hwid": "8f65b16dXXXXe7a6XXXX9614eXXXXfb2" // required. Hardware device ID used in /registerDevice API
  }
}

pushStat

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

يسجل حدث فتح الدفع. يتم استدعاؤه داخليًا من SDK.

ترويسات الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز API للجهاز للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز API الفعلي لجهازك.

نص الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
hwid*	string	معرف جهاز الجهاز المستخدم في طلب /registerDevice.
userId	string	User ID لربطه بحدث فتح الدفع.
hash	string	علامة التجزئة المستلمة في إشعار الدفع (المعلمة “p” في حمولة الدفع).

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "request": {
    "application": "XXXXX-XXXXX",               // required. Pushwoosh application code
    "hwid": "8f65b16dfXXXX7a6beXXXX14e1530fb2", // required. Hardware device ID used in /registerDevice API
    "userId": "USER012345",                     // optional. The user id to associate with the push open event
    "hash": "HASH_TAG"                          // optional. Hash tag received in push notification
                                                //           ("p" parameter in the push payload)
  }
}

messageDeliveryEvent

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

يسجل حدث تسليم الدفع للجهاز. يتم استدعاؤه داخليًا من SDK.

ترويسات الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز API للجهاز للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز API الفعلي لجهازك.

نص الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
hwid*	string	معرف جهاز الجهاز المستخدم في طلب `/registerDevice`.
hash	string	علامة التجزئة المستلمة في إشعار الدفع (المعلمة “p” في حمولة الدفع).

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

 {
  "request": {
    "application": "XXXXX-XXXXX",               // required. Pushwoosh application code
    "hwid": "8f65b16dfXXXX7a6bece9XXXX1530fb2", // required. Hardware device ID used in /registerDevice API
    "hash": "HASH_TAG"                          // optional. Hash tag received in push notification
                                                //           ("p" parameter in the push payload)
  }
}