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

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

المتطلبات المسبقة

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

المتطلبات

• حساب Pushwoosh.
• مشروع Pushwoosh تم إعداده في حسابك.
• لتكامل iOS:
  • منصة iOS تم تكوينها لإرسال إشعارات الدفع. نوصي باستخدام تكوين المصادقة المستندة إلى الرمز المميز (Token-Based Authentication) كأبسط طريقة.
  • اضبط Gateway على Sandbox لإرسال إشعارات الدفع إلى محاكي.
• لتكامل Android:
  • منصة Android مهيأة
  • رقم المشروع (المعروف أيضًا باسم Sender ID)، ملف google-services.json و اسم الحزمة من مشروع Firebase الخاص بك.
  • مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع دليل إعداد Firebase إذا لزم الأمر.
• رمز تطبيق Pushwoosh الخاص بك و رمز API لجهاز Pushwoosh من لوحة تحكم 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__",
    projectid: "__YOUR_FCM_SENDER_ID__"
});

// 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.
• __YOUR_FCM_SENDER_ID__ هو رقم مشروع Firebase من Firebase Console.

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

3.1 الإمكانيات

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

في قسم Signing & Capabilities، أضف الإمكانيات التالية:

• Push Notifications
• Background Modes. بعد إضافة هذه الإمكانية، حدد المربع الخاص بـ Remote notifications.

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

3.2 Info.plist

في Runner/Info.plist الخاص بك، اضبط المفتاح Pushwoosh_API_TOKEN على رمز API لجهاز Pushwoosh:

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 plugin إلى تبعيات 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 الخاص بك، أضف رمز API لجهاز Pushwoosh داخل وسم <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 methods) للتعامل مع إشعارات الدفع:

• يتم تشغيل 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 } => '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()
    });
  }
}

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

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