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

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

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

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

المتطلبات

• حساب Pushwoosh.
• مشروع Pushwoosh مُعد في حسابك.
• للتكامل مع iOS:
  • منصة iOS مهيأة لإرسال الإشعارات الفورية. نوصي باستخدام تكوين المصادقة المستندة إلى الرمز كأبسط نهج.
  • اضبط البوابة على Sandbox لإرسال الإشعارات إلى جهاز محاكاة.
• للتكامل مع 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

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

في Runner/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 اللازم بداخله.

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

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

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