# دليل التكامل الأساسي لـ Cordova SDK
يحتوي هذا القسم على معلومات حول كيفية دمج Pushwoosh Cordova SDK في تطبيقك.
## المتطلبات الأساسية
لدمج Pushwoosh Cordova SDK في تطبيقك، ستحتاج إلى ما يلي:
## خطوات التكامل
### 1. إضافة اعتمادية Pushwoosh Cordova SDK
أضف اعتمادية Pushwoosh Cordova SDK إلى مشروعك:
```bash
cordova plugin add pushwoosh-cordova-plugin
```
### 2. تهيئة Cordova SDK
في المكون الجذري لملف `index.js` الخاص بك، أضف الكود التالي داخل معالج حدث `deviceready`. اتبع الخطوات بالترتيب الدقيق:
```javascript title="index.js"
document.addEventListener('deviceready', function() {
var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");
// 1. Register notification callbacks before initialization
document.addEventListener('push-receive', function(event) {
var notification = event.notification;
console.log("Push received: " + JSON.stringify(notification));
});
document.addEventListener('push-notification', function(event) {
var notification = event.notification;
console.log("Push opened: " + JSON.stringify(notification));
});
// 2. Initialize Pushwoosh
pushwoosh.onDeviceReady({
appid: "__YOUR_APP_ID__"
});
// 3. Register the device to receive push notifications
pushwoosh.registerDevice(
function(status) {
var pushToken = status.pushToken;
// Handle successful registration
},
function(status) {
// Handle registration error
}
);
}, false);
```
حيث:
- `__YOUR_APP_ID__` هو رمز التطبيق من لوحة تحكم Pushwoosh.
### 3. الإعداد الأصلي لـ iOS
#### 3.1 القدرات
لتمكين الإشعارات الفورية في مشروعك، تحتاج إلى إضافة قدرات معينة.
في قسم التوقيع والقدرات (Signing & Capabilities)، أضف القدرات التالية:
- `Push Notifications`
- `Background Modes`. بعد إضافة هذه القدرة، حدد مربع `Remote notifications`.
إذا كنت تنوي استخدام الإشعارات الحساسة للوقت (Time Sensitive Notifications) (iOS 15+)، فأضف أيضًا قدرة `Time Sensitive Notifications`.
#### 3.2 Info.plist
في ملف `Runner/Info.plist` الخاص بك، اضبط مفتاح `__PUSHWOOSH_DEVICE_API_TOKEN__` على [رمز API للجهاز من Pushwoosh](/ar/developer/api-reference/api-access-token/#device-api-token):
```swift title="info.plist"
Pushwoosh_API_TOKEN__PUSHWOOSH_DEVICE_API_TOKEN__
```
#### 3.3 تتبع تسليم الرسائل
يجب عليك إضافة هدف ملحق خدمة الإشعارات (Notification Service Extension) إلى مشروعك. هذا ضروري لتتبع التسليم بدقة وميزات مثل الوسائط الغنية (Rich Media) على iOS.
اتبع [خطوات الدليل الأصلي](/ar/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#4-message-delivery-tracking) لإضافة هدف الملحق وكود Pushwoosh اللازم بداخله.
### 4. الإعداد الأصلي لـ Android
#### 4.1 تثبيت الاعتماديات
تأكد من إضافة الاعتماديات والمكونات الإضافية المطلوبة إلى نصوص Gradle الخاصة بك:
أضف مكون Google Services Gradle الإضافي إلى اعتماديات `build.gradle` على مستوى المشروع:
```groovy title="android/build.gradle"
buildscript {
dependencies {
classpath 'com.google.gms:google-services:4.3.15'
}
}
```
طبق المكون الإضافي في ملف `build.gradle` على مستوى التطبيق:
```groovy title="app/build.gradle"
apply plugin: 'com.google.gms.google-services'
```
#### 4.2 إضافة ملف تكوين Firebase
ضع ملف `google-services.json` في مجلد `android/app` في دليل مشروعك.
#### 4.3 إضافة بيانات Pushwoosh الوصفية
في ملف `main/AndroidManifest.xml` الخاص بك، أضف [رمز API للجهاز من Pushwoosh](/ar/developer/api-reference/api-access-token/#device-api-token) داخل وسم ``:
```xml title="AndroidManifest.xml"
```
> **مهم:** تأكد من منح الرمز وصولاً إلى التطبيق الصحيح في لوحة تحكم Pushwoosh. [اعرف المزيد](/ar/developer/api-reference/api-access-token/#edit-token)
### 5. تشغيل المشروع
1. قم ببناء وتشغيل المشروع.
2. اذهب إلى لوحة تحكم Pushwoosh و[أرسل إشعارًا فوريًا](/ar/product/messaging-channels/push-notifications/send-push-notifications/one-time-push).
3. يجب أن ترى الإشعار في التطبيق.
## التكامل الممتد
في هذه المرحلة، لقد قمت بالفعل بدمج SDK ويمكنك إرسال واستقبال الإشعارات الفورية. الآن، دعنا نستكشف الوظائف الأساسية
### مستمعو أحداث الإشعارات الفورية
في Pushwoosh SDK، يوجد مستمعان للأحداث، مصممان للتعامل مع الإشعارات الفورية:
- يتم تشغيل حدث `push-receive` عند استلام إشعار فوري بينما يكون التطبيق في المقدمة
- يتم تشغيل حدث `push-notification` عندما يفتح المستخدم إشعارًا
يجب تسجيل مستمعي الأحداث هؤلاء **قبل** استدعاء `onDeviceReady()`، كما هو موضح في [خطوة التهيئة أعلاه](#2-cordova-sdk-initialization). يمكنك تخصيص منطق المعالج ليناسب احتياجاتك:
```javascript title="index.js"
// Register before onDeviceReady()
document.addEventListener('push-receive', function(event) {
var message = event.notification.message;
var payload = event.notification.userdata;
console.log("Push received: " + message);
// Add your custom logic here
});
document.addEventListener('push-notification', function(event) {
var message = event.notification.message;
var payload = event.notification.userdata;
console.log("Push accepted: " + message);
// Add your custom logic here (e.g., navigate to a specific screen)
});
```
### تكوين المستخدم
من خلال التركيز على سلوك المستخدم الفردي وتفضيلاته، يمكنك تقديم محتوى مخصص، مما يؤدي إلى زيادة رضا المستخدم وولائه
```javascript
class Registration {
afterUserLogin(user) {
// Set user ID
pushwoosh.setUserId(user.getId());
// Setting additional user information as tags for Pushwoosh
pushwoosh.setTags({
"age": user.getAge(),
"name": user.getName(),
"last_login": user.getLastLoginDate()
});
}
}
```
### العلامات (Tags)
العلامات (Tags) هي أزواج من المفاتيح والقيم يتم تعيينها للمستخدمين أو الأجهزة، مما يسمح بالتقسيم بناءً على سمات مثل التفضيلات أو السلوك، مما يتيح المراسلة المستهدفة.
```javascript
class UpdateUser {
afterUserUpdateProfile(user) {
// Set list of favorite categories
pushwoosh.setTags({
"favorite_categories": user.getFavoriteCategoriesList()
});
// Set payment information
pushwoosh.setTags({
"is_subscribed": user.isSubscribed(),
"payment_status": user.getPaymentStatus(),
"billing_address": user.getBillingAddress()
});
}
}
```
### الأحداث (Events)
الأحداث (Events) هي إجراءات أو وقائع محددة للمستخدم داخل التطبيق يمكن تتبعها لتحليل السلوك وتشغيل الرسائل أو الإجراءات المقابلة
```javascript
class Registration {
// Track login event
afterUserLogin(user) {
pushwoosh.postEvent("login", {
"name": user.getName(),
"last_login": user.getLastLoginDate()
});
}
// Track purchase event
afterUserPurchase(product) {
pushwoosh.postEvent("purchase", {
"product_id": product.getId(),
"product_name": product.getName(),
"price": product.getPrice(),
"quantity": product.getQuantity()
});
}
}
```
## استكشاف الأخطاء وإصلاحها
إذا واجهت أي مشاكل أثناء عملية التكامل، يرجى الرجوع إلى قسم [الدعم والمجتمع](/ar/developer/pushwoosh-sdk/support-and-community).