دليل التكامل الأساسي لـ Capacitor SDK

يحتوي هذا القسم على معلومات حول كيفية دمج Pushwoosh Capacitor SDK في تطبيقك.

المتطلبات الأساسية

لدمج Pushwoosh Capacitor SDK في تطبيقك، ستحتاج إلى ما يلي:

المتطلبات

• حساب Pushwoosh.
• مشروع Pushwoosh مُعد في حسابك.
• لتكامل iOS:
  • منصة iOS مكونة لإرسال الإشعارات الفورية. نوصي باستخدام تكوين المصادقة المستندة إلى الرمز المميز كأبسط نهج.
  • اضبط البوابة (Gateway) على Sandbox لإرسال الإشعارات إلى جهاز محاكاة.
  • لإضافة المكوّن الإضافي باستخدام Swift Package Manager: Capacitor 7 أو 8. لترحيل مشروع CocoaPods إلى Swift Package Manager: @capacitor/cli 7.4.0 أو أحدث.
• لتكامل Android:
  • منصة Android مكونة
  • ملف google-services.json و package name من مشروع Firebase الخاص بك.
  • مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع دليل إعداد Firebase إذا لزم الأمر.
• Pushwoosh Application Code الخاص بك و Pushwoosh Device API Token من لوحة تحكم Pushwoosh لتطبيقك.

خطوات التكامل

1. إضافة تبعية Pushwoosh Capacitor SDK

أضف تبعية Pushwoosh Capacitor SDK إلى مشروعك:

npm install pushwoosh-capacitor-plugin

قم بمزامنة تكوين Capacitor:

npx cap sync

1.1 اختر مدير حزم iOS

يثبّت npx cap sync جزء iOS من المكوّن الإضافي باستخدام مدير الحزم الذي يستخدمه مشروع Capacitor الخاص بك: Swift Package Manager أو CocoaPods. يوفّر كلاهما الإصدار نفسه من Pushwoosh SDK الأصلي وInbox UI. يتوفر دعم Swift Package Manager مع Capacitor 7 وCapacitor 8.

يحتفظ المشروع الحالي بمدير الحزم الخاص به: إذا كان ios/App/CapApp-SPM موجودًا، يستخدم Capacitor CLI مدير Swift Package Manager، وإلا يستخدم CocoaPods. لمنصة iOS جديدة:

Capacitor 8

ينشئ Capacitor 8 مشروع Swift Package Manager افتراضيًا:

npx cap add ios

لاستخدام CocoaPods بدلاً من ذلك، شغّل npx cap add ios --packagemanager CocoaPods.

Capacitor 7

ينشئ Capacitor 7 مشروع CocoaPods افتراضيًا. لاستخدام Swift Package Manager، شغّل:

npx cap add ios --packagemanager SPM

ينشئ الأمر المشروع ثم يتوقف مع الخطأ ENOENT ... Podfile أثناء محاولة تشغيل pod install. يتم إنشاء المشروع بشكل صحيح. أكمل الإعداد باستخدام:

npx cap sync ios

مع Swift Package Manager، يضيف Capacitor CLI المكوّن الإضافي إلى ios/App/CapApp-SPM، ويجلب المكوّن الإضافي Pushwoosh iOS SDK وInbox UI. لا تُضف Pushwoosh SDK إلى التطبيق مرة ثانية، لا كـ pod ولا كحزمة بإصدار مختلف.

إيقاف دعم CocoaPods

يصبح CocoaPods trunk للقراءة فقط في 2 ديسمبر 2026، وتنقل Pushwoosh حزمة iOS SDK إلى Swift Package Manager. إصدارات المكوّن الإضافي بعد هذا التاريخ ستستخدم حزمة Swift فقط. حتى ذلك الحين، يعرض pod install وبناء Xcode لمشروع CocoaPods تحذيرًا بشأن ذلك. لا يؤثر التحذير على البناء.

لترحيل مشروع CocoaPods موجود، شغّل npx cap spm-migration-assistant، ثم اتبع خطوة Xcode اليدوية التي يشير إليها. يتطلب الأمر @capacitor/cli 7.4.0 أو أحدث.

2. تهيئة Capacitor SDK

في ملف JavaScript الرئيسي الخاص بك، قم باستيراد وتهيئة Pushwoosh SDK:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Initialize the SDK
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// Register for push notifications
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // Handle successful registration
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // Handle registration error
    });

حيث:

• __YOUR_APP_CODE__ هو رمز التطبيق من لوحة تحكم Pushwoosh.

3. الإعداد الأصلي لـ iOS

3.1 القدرات (Capabilities)

لتمكين الإشعارات الفورية في مشروعك، تحتاج إلى إضافة قدرات معينة.

في قسم Signing & Capabilities، أضف القدرات التالية:

• Push Notifications
• Background Modes. بعد إضافة هذه القدرة، حدد مربع Remote notifications.

إذا كنت تنوي استخدام Time Sensitive Notifications (iOS 15+)، أضف أيضًا قدرة Time Sensitive Notifications.

3.2 Info.plist

في ملف ios/App/App/Info.plist الخاص بك، اضبط مفتاح __PUSHWOOSH_DEVICE_API_TOKEN__ على Pushwoosh Device API Token:

info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

3.3 تتبع تسليم الرسائل

يجب عليك إضافة هدف Notification Service Extension إلى مشروعك. هذا ضروري لتتبع التسليم بدقة وميزات مثل Rich Media على iOS.

اتبع خطوات الدليل الأصلي لإضافة هدف الامتداد وكود Pushwoosh اللازم داخله. أضف Pushwoosh SDK إلى هدف الامتداد وفقًا لمدير الحزم الذي تستخدمه:

• CocoaPods: اتبع خطوة التبعيات لـ Notification Service Extension (CocoaPods فقط) في الدليل الأصلي. في ios/App/Podfile، أضف pod 'PushwooshXCFramework' بدون إصدار إلى هدف الامتداد، بحيث يُحل إلى الإصدار الذي يستخدمه المكوّن الإضافي، ثم شغّل npx cap sync ios.

• Swift Package Manager: تخطَّ خطوة تبعيات CocoaPods في الدليل الأصلي. أضف SDK إلى هدف الامتداد في Xcode بنفسك، لأن الهدف لا يرث تبعيات المكوّن الإضافي:

  1. افتح هدف الامتداد > General > Frameworks and Libraries.
  2. أضف المنتج PushwooshFramework من الحزمة Pushwoosh-XCFramework. استخدم الإصدار الموجود بالفعل في Package.resolved.

  إذا قمت بالترحيل من CocoaPods، فتأكد من أن الامتداد لم يعد يحصل على PushwooshXCFramework كـ pod، حتى لا يتضمن التطبيق SDK مرتين.

بعد ذلك، أضف import PushwooshFramework في كود الامتداد. لا يحتاج هدف App إلى أي شيء إضافي، لأنه يحصل على Pushwoosh SDK من خلال المكوّن الإضافي.

4. الإعداد الأصلي لـ Android

4.1 تثبيت التبعيات

تأكد من إضافة التبعيات والمكونات الإضافية المطلوبة إلى نصوص Gradle الخاصة بك:

أضف المكون الإضافي Google Services Gradle إلى تبعيات build.gradle على مستوى المشروع:

android/build.gradle

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

طبق المكون الإضافي في ملف build.gradle على مستوى التطبيق:

app/build.gradle

apply plugin: 'com.google.gms.google-services'

4.2 إضافة ملف تكوين Firebase

ضع ملف google-services.json في مجلد android/app في دليل مشروعك.

4.3 إضافة بيانات Pushwoosh الوصفية

في ملف main/AndroidManifest.xml الخاص بك، أضف Pushwoosh Device API Token داخل علامة <application>:

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

هام: تأكد من منح الرمز المميز حق الوصول إلى التطبيق الصحيح في لوحة تحكم Pushwoosh. اعرف المزيد

5. تشغيل المشروع

1. قم ببناء وتشغيل المشروع.
2. اذهب إلى لوحة تحكم Pushwoosh و أرسل إشعارًا فوريًا.
3. يجب أن ترى الإشعار في التطبيق.

التكامل الممتد

في هذه المرحلة، لقد قمت بالفعل بدمج SDK ويمكنك إرسال واستقبال الإشعارات الفورية. الآن، دعنا نستكشف الوظائف الأساسية.

مستمعو أحداث الإشعارات الفورية

في Pushwoosh Capacitor SDK، هناك طريقتان للاستدعاء (callback) للتعامل مع الإشعارات الفورية:

• يتم تشغيل pushReceivedCallback عند استلام إشعار فوري
• يتم تشغيل pushOpenedCallback عندما يفتح المستخدم إشعارًا

يجب عليك إعداد هذه الاستدعاءات مباشرة بعد تهيئة SDK:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Set up push received callback
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // Handle the received notification
    }
});

// Set up push opened callback
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // Handle the opened notification
    }
});

تكوين المستخدم

من خلال التركيز على سلوك وتفضيلات المستخدم الفردية، يمكنك تقديم محتوى مخصص، مما يؤدي إلى زيادة رضا المستخدم وولائه.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {
  async afterUserLogin(user) {

    // Set user ID
    Pushwoosh.setUserId(user.getId);

    // Setting additional user information as tags for Pushwoosh
    await Pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

العلامات (Tags)

العلامات هي أزواج من المفاتيح والقيم يتم تعيينها للمستخدمين أو الأجهزة، مما يسمح بالتقسيم بناءً على سمات مثل التفضيلات أو السلوك، مما يتيح المراسلة المستهدفة.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class UpdateUser {
 async afterUserUpdateProfile(user) {

    // Set list of favorite categories
    await Pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // Set payment information
    await Pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

الأحداث (Events)

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

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

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()
    });
  }
}

استكشاف الأخطاء وإصلاحها

إذا لم يتم تسليم إشعار فوري، فابحث عن رمز الخطأ الخاص بمنصتك في أخطاء الإرسال لمعرفة معناه وكيفية إصلاحه.

إذا واجهت أي مشاكل أثناء عملية التكامل، يرجى الرجوع إلى قسم الدعم والمجتمع.