# مرجع واجهة برمجة التطبيقات (API) لمكون Cordova الإضافي

```txt title="مثال"
var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");

// يجب استدعاؤه قبل pushwoosh.onDeviceReady
document.addEventListener('push-notification', function(event) {
	var notification = event.notification;
	// تعامل مع فتح الإشعار هنا
});

// تهيئة Pushwoosh. سيؤدي هذا إلى إطلاق جميع الإشعارات الفورية المعلقة عند البدء.
pushwoosh.onDeviceReady({
	appid: "XXXXX-XXXXX",
	serviceName: "XXXX"
});

pushwoosh.registerDevice(
	function(status) {
		var pushToken = status.pushToken;
    	// تعامل مع التسجيل الناجح هنا
  },
  function(status) {
    // تعامل مع خطأ التسجيل هنا
  }
);
```

## onDeviceReady

```javascript
PushNotification.prototype.onDeviceReady = function( config )
```

_\[android, ios, wp8, windows]_\
يقوم بتهيئة مكون Pushwoosh الإضافي ويطلق رسالة دفع عند البدء. يجب استدعاؤه عند كل تشغيل للتطبيق.

`config.appid` – رمز تطبيق Pushwoosh.

`config.serviceName` – اسم خدمة MPNS لمنصة wp8.

```txt title="مثال"
// تهيئة Pushwoosh باستخدام appid: "PUSHWOOSH_APP_ID"، serviceName: "WINDOWS_PHONE_SERVICE". سيؤدي هذا إلى إطلاق جميع الإشعارات الفورية المعلقة عند البدء.
pushwoosh.onDeviceReady({
    appid : "XXXXX-XXXXX",
    serviceName: "XXXX"
});
```

## registerDevice

```javascript
PushNotification.prototype.registerDevice = function( success, fail )
```

_\[android, ios, wp8, windows]_\
يسجل الجهاز لتلقي الإشعارات الفورية ويسترجع رمز الدفع (Push Token).

`success` – دالة رد النداء للنجاح. يتم تمرير رمز الدفع كمعامل “status.pushToken” إلى دالة رد النداء هذه.

`fail` – دالة رد النداء للخطأ.

```txt title="مثال"
pushwoosh.registerDevice(
    function(status) {
        alert("Registered with push token: " + status.pushToken);
    },
    function(error) {
        alert("Failed to register: " +  error);
    }
);
```

## unregisterDevice

```javascript
PushNotification.prototype.unregisterDevice = function(	success, fail	)
```

_\[android, ios, wp8, windows]_\
يلغي تسجيل الجهاز من تلقي الإشعارات الفورية.

`success` – دالة رد النداء للنجاح.

`fail` – دالة رد النداء للخطأ.

## setTags

```javascript
PushNotification.prototype.setTags = function(	config, success, fail	)
```

_\[android, ios, wp8, windows]_\
يضبط الوسوم للجهاز.

**المعاملات**

`config` – كائن يحتوي على وسوم الجهاز المخصصة.

`success` – دالة رد النداء للنجاح. يتم تمرير رمز الدفع كمعامل “status.pushToken” إلى دالة رد النداء هذه.

`fail` – دالة رد النداء للخطأ.

```txt title="مثال"
// يضبط الوسوم: “deviceName” بالقيمة “hello” و “deviceId” بالقيمة 10
pushwoosh.setTags({deviceName:"hello", deviceId:10},
    function() {
        console.warn('setTags success');
    },
    function(error) {
        console.warn('setTags failed');
    }
);

// يضبط وسوم القائمة "MyTag" بالقيم (مصفوفة) "hello", "world"
pushwoosh.setTags({"MyTag":["hello", "world"]});
```

## getTags

```javascript
PushNotification.prototype.getTags = function(	success, fail	)
```

_\[android, ios, wp8, windows]_\
يعيد الوسوم الخاصة بالجهاز بما في ذلك الوسوم الافتراضية.

`success` – دالة رد النداء للنجاح. تستقبل الوسوم كمعاملات.

`fail` – دالة رد النداء للخطأ.

```javascript
pushwoosh.getTags(
    function(tags) {
        console.warn('tags for the device: ' + JSON.stringify(tags));
    },
    function(error) {
        console.warn('get tags error: ' + JSON.stringify(error));
    }
);
```

## getPushToken

```javascript
PushNotification.prototype.getPushToken = function(	success	)
```

_\[android, ios, wp8, windows]_\
يعيد رمز الدفع إذا كان متاحًا. لاحظ أن الرمز يأتي أيضًا في دالة رد النداء لدالة registerDevice.

`success` – دالة رد النداء للنجاح.

```javascript
pushwoosh.getPushToken(
    function(token) {
        console.warn('push token: ' + token);
    }
);
```

## getPushwooshHWID

```javascript
PushNotification.prototype.getPushwooshHWID = function(	success	)
```

_\[android, ios, wp8, windows]_\
يعيد Pushwoosh HWID المستخدم للاتصالات مع Pushwoosh API.

`success` – دالة رد النداء لـ getPushwooshHWID.

```
pushwoosh.getPushwooshHWID(
    function(token) {
        console.warn('Pushwoosh HWID: ' + token);
    }
);
```

## getRemoteNotificationStatus

```javascript
PushNotification.prototype.getRemoteNotificationStatus = function(	callback, error	)
```

_\[android, ios]_\
يعيد حالة مفصلة لأذونات الإشعارات الفورية.

`callback` – دالة رد النداء للنجاح. تستقبل كائنًا بالخصائص التالية:

```
{
  "enabled" : علامة تمكين الإشعارات.
  "pushBadge" : تم منح إذن الشارات. (iOS فقط)
  "pushAlert" : تم منح إذن التنبيه. (iOS فقط)
  "pushSound" : تم منح إذن الصوت. (iOS فقط)
}
```

`error` — دالة رد النداء للخطأ.

## setApplicationIconBadgeNumber

```javascript
PushNotification.prototype.setApplicationIconBadgeNumber = function(	badgeNumber	)
```

_\[android, ios]_\
يضبط رقم شارة أيقونة التطبيق.

`badgeNumber` – رقم شارة الأيقونة.

## getApplicationIconBadgeNumber

```javascript
PushNotification.prototype.getApplicationIconBadgeNumber = function(	callback	)
```

_\[android, ios]_\
يعيد رقم شارة أيقونة التطبيق.

`callback` – دالة رد النداء للنجاح.

```
pushwoosh.getApplicationIconBadgeNumber(function(badge){ alert(badge);} );
```

## addToApplicationIconBadgeNumber

```javascript
PushNotification.prototype.addToApplicationIconBadgeNumber = function( badgeNumber )
```

_\[android, ios]_\
يضيف قيمة إلى شارة أيقونة التطبيق.

`badgeNumber` — رقم شارة الأيقونة التزايدي.

## getLaunchNotification

```javascript
PushNotification.prototype.getLaunchNotification = function(	callback	)
```

_\[android, ios]_\
يعيد حمولة الإشعار الفوري إذا تم بدء التطبيق استجابةً لإشعار فوري، أو null.

`callback` – دالة رد النداء للنجاح.

## clearLaunchNotification

```javascript
PushNotification.prototype.clearLaunchNotification = function(	callback	)
```

_\[android, ios]_\
يمسح إشعار التشغيل، وستعيد `getLaunchNotification()` القيمة null بعد هذا الاستدعاء.

## setUserId

```javascript
PushNotification.prototype.setUserId = function(	userId	)
```

_\[android, ios]_\
يضبط معرف المستخدم (User indentifier) – معرف فيسبوك، اسم مستخدم، بريد إلكتروني، أو أي معرف مستخدم آخر. يسمح هذا بمطابقة البيانات والأحداث عبر أجهزة المستخدم المتعددة.

`userId` – معرف المستخدم النصي.

## postEvent

```javascript
PushNotification.prototype.postEvent = function( event, attributes )
```

_\[android, ios]_\
ينشر أحداثًا للرسائل داخل التطبيق (In-App Messages). يمكن أن يؤدي هذا إلى عرض رسالة داخل التطبيق كما هو محدد في لوحة تحكم Pushwoosh.

`event` – الحدث المراد إطلاقه.

`attributes` – كائن بسمات حدث إضافية.

```
pushwoosh.setUserId("XXXXXX");
pushwoosh.postEvent("buttonPressed", { "buttonNumber" : 4, "buttonLabel" : "banner" });
```

## createLocalNotification

```javascript
PushNotification.prototype.createLocalNotification = function( config, success, fail )
```

_\[android, ios]_\
يجدول إشعارًا محليًا.

`config.msg` – رسالة الإشعار.

`config.seconds` – تأخير الإشعار بالثواني.

`config.userData` – بيانات إضافية لتمريرها في الإشعار.

`success` – دالة رد النداء للنجاح.

`fail` – دالة رد النداء للخطأ.

```
pushwoosh.createLocalNotification({msg:"Your pumpkins are ready!", seconds:30, userData:{}})
```

## clearLocalNotification

```javascript
PushNotification.prototype.clearLocalNotification = function()
```

_\[android]_\
يمسح جميع الإشعارات المحلية المعلقة التي تم إنشاؤها بواسطة createLocalNotification.

## clearNotificationCenter

```javascript
PushNotification.prototype.clearNotificationCenter = function()
```

_\[android]_\
يمسح جميع الإشعارات المعروضة في مركز إشعارات Android.

## setMultiNotificationMode

```javascript
PushNotification.prototype.setMultiNotificationMode = function( success, fail )
```

_\[android]_\
يسمح بعرض إشعارات متعددة في مركز إشعارات Android.

## setSingleNotificationMode

```javascript
PushNotification.prototype.setSingleNotificationMode = function(	success,
fail	)
```

_\[android]_\
يسمح بعرض الإشعار الأخير فقط في مركز إشعارات Android.

## setSoundType

```javascript
PushNotification.prototype.setSoundType = function( type, success, fail )
```

_\[android]_\
يضبط الصوت الافتراضي للإشعارات الواردة.

`type` – نوع الصوت (0 – افتراضي، 1 – بدون صوت، 2 – دائمًا).

## setVibrateType

```javascript
PushNotification.prototype.setVibrateType = function(type, success, fail )
```

_\[android]_\
يضبط وضع الاهتزاز الافتراضي للإشعارات الواردة.

`type` – نوع الاهتزاز (0 – افتراضي، 1 – بدون اهتزاز، 2 – دائمًا).

## setLightScreenOnNotification

```javascript
PushNotification.prototype.setLightScreenOnNotification = function( on, success, fail )
```

_\[android]_\
يشغل الشاشة عند وصول الإشعار.

`on` – تمكين/تعطيل فتح الشاشة (معطل افتراضيًا).

## setEnableLED

```javascript
PushNotification.prototype.setEnableLED = function( on, success, fail )
```

_\[android]_\
يمكّن وميض مؤشر LED عند وصول الإشعار وإيقاف تشغيل الشاشة.

`on` – تمكين/تعطيل وميض LED (معطل افتراضيًا).

## setColorLED

```javascript
PushNotification.prototype.setColorLED = function( color, success, fail )
```

_\[android]_\
يضبط لون مؤشر LED. استخدم مع [setEnableLED](#setenableled).

`color` – لون LED بتنسيق عدد صحيح ARGB.

## getPushHistory

```javascript
PushNotification.prototype.getPushHistory = function(	success	)
```

_\[android]_\
يعيد مصفوفة من الإشعارات الفورية المستلمة.

`success` – دالة رد النداء للنجاح.

```
pushwoosh.getPushHistory(function(pushHistory) {
    if(pushHistory.length == 0)
        alert("no push history");
    else
        alert(JSON.stringify(pushHistory));
});

pushwoosh.clearPushHistory();
```

## clearPushHistory

```javascript
PushNotification.prototype.clearPushHistory = function()
```

_\[android]_\
يمسح سجل الإشعارات.

## cancelAllLocalNotifications

```javascript
PushNotification.prototype.cancelAllLocalNotifications = function( callback )
```

_\[ios]_\
يمسح جميع الإشعارات المحلية من مركز الإشعارات.

## presentInboxUI

_\[android, ios]_\
يفتح شاشة [صندوق الوارد](/ar/developer/guides/message-inbox/mobile-message-inbox).

```javascript
PushNotification.prototype.presentInboxUI = function()
```

## setCommunicationEnabled

دالة ثنائية لتمكين/تعطيل كل الاتصالات مع Pushwoosh. القيمة المنطقية **false** تلغي اشتراك الجهاز من تلقي الإشعارات الفورية وتوقف تنزيل الرسائل داخل التطبيق. القيمة **true** تعكس التأثير.

```javascript
PushNotification.prototype.setCommunicationEnabled = function(enable, success, fail)
```

## removeAllDeviceData

يزيل جميع البيانات المتعلقة بالجهاز.

```javascript
PushNotification.prototype.removeAllDeviceData = function()
```

## push-receive

_\[android, ios]_\
حدث استلام الإشعار الفوري. يتم إطلاقه عندما يتلقى التطبيق إشعارًا فوريًا في الواجهة الأمامية أو في الخلفية. التطبيقات المغلقة لا تتلقى هذا الحدث.

**خصائص الحدث**

`message` – (`string`) رسالة الإشعار الفوري

`userdata` – (`object`/`array`) بيانات مخصصة للإشعار الفوري

`onStart` – (`boolean`) هل هو إشعار تشغيل

`foreground` – (`boolean`) هل تم استلام الإشعار في الواجهة الأمامية

`android` – (`object`) حمولة إشعار خاصة بـ Android

`ios` – (`object`) حمولة إشعار خاصة بـ iOS

`windows` – (`object`) حمولة إشعار خاصة بـ Windows

```
document.addEventListener('push-receive',
	function(event) {
		var userData = event.notification.userdata;

		if (typeof(userData) != "undefined") {
			// تعامل مع بيانات الإشعار المخصصة
			console.warn('user data: ' + JSON.stringify(userData));
		}
	}
);
```

## الإشعارات في الواجهة الأمامية

بشكل افتراضي، لا يعرض مكون Pushwoosh الإضافي الإشعارات في الواجهة الأمامية ويطلق حدث `push-receive` تلقائيًا. راجع [دليل تخصيص المكون الإضافي](/ar/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/customizing-cordova-plugin/) للتحكم في هذا السلوك.

### push-notification

_\[android, ios, wp8, windows]_\
حدث قبول الإشعار الفوري. يتم إطلاقه عندما ينقر المستخدم على الإشعار الفوري.

```
document.addEventListener('push-notification',
	function(event) {
		var message = event.notification.message;
		var userData = event.notification.userdata;

		if (typeof(userData) != "undefined") {
			console.warn('user data: ' + JSON.stringify(userData));
		}
	}
);
```

**خصائص الحدث**

نفس [push-receive](#push-receive)

### additionalAuthorizationOptions

_\[ios فقط]_\
يوفر خيارات إضافية لترخيص الإشعارات [notification authorization options](https://developer.apple.com/documentation/usernotifications/unauthorizationoptions?language=objc). يجب استدعاؤه قبل استدعاء **registerDevice**.

```
pushwoosh.additionalAuthorizationOptions({ 
	"UNAuthorizationOptionCriticalAlert" : 1,
	"UNAuthorizationOptionProvisional": 0 // اضبط القيمة على 0 أو لا تحدد الخيار إذا كنت لا تريد إضافته إلى تطبيقك. 
});
```