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

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

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

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

المتطلبات

• حساب Pushwoosh.
• مشروع Pushwoosh تم إعداده في حسابك.
• للتكامل مع iOS:
  • منصة iOS مهيأة لإرسال الإشعارات الفورية. نوصي باستخدام تكوين المصادقة المستندة إلى الرمز كأبسط طريقة.
  • اضبط البوابة (Gateway) على Sandbox لإرسال الإشعارات إلى جهاز محاكاة.
• للتكامل مع Android:
  • منصة Android مهيأة
  • رقم المشروع (المعروف أيضًا بـ Sender ID)، وملف google-services.json، واسم الحزمة من مشروع Firebase الخاص بك.
  • مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع دليل إعداد Firebase إذا لزم الأمر.
• رمز تطبيق Pushwoosh الخاص بك و رمز واجهة برمجة تطبيقات جهاز Pushwoosh من لوحة تحكم Pushwoosh لتطبيقك.

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

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

أضف حزمة pushwoosh_flutter إلى ملف pubspec.yaml الخاص بك:

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  # Use the latest version from https://pub.dev/packages/pushwoosh_flutter
  pushwoosh_flutter: ^[LATEST_VERSION]

تحقق من أحدث إصدار على pub.dev.

بعد ذلك، قم بتشغيل الأمر التالي في الدليل الجذر لمشروعك لتثبيت التبعية:

flutter pub get

تحقق مرة أخرى من تثبيت الحزمة بشكل صحيح:

flutter pub deps | grep pushwoosh_flutter

# Example output:
# ❯ flutter pub deps | grep pushwoosh_flutter
# └── pushwoosh_flutter 2.3.11

2. تهيئة Flutter SDK

في المكون الجذر لملف main.dart الخاص بك:

• استورد حزمة pushwoosh_flutter.
• قم بتهيئة Pushwoosh SDK.
• استدعِ registerForPushNotifications() في منطق التهيئة الخاص بك للتسجيل في الإشعارات الفورية.

main.dart

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

void main() async {
  runApp(const MyApp());
  Pushwoosh.initialize({
    "app_id": "__YOUR_APP_ID__",
    "sender_id": "__YOUR_FCM_SENDER_ID__"
  });
  Pushwoosh.getInstance.registerForPushNotifications();
}

حيث:

• __YOUR_APP_ID__ هو رمز التطبيق من لوحة تحكم Pushwoosh.
• __YOUR_FCM_SENDER_ID__ هو رقم مشروع Firebase من Firebase Console.

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:

info.plist

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

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

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

اتبع خطوات الدليل الأصلي لإضافة هدف الامتداد ورمز Pushwoosh الضروري بداخله.

للتأكد من أن Notification Service Extension مدمج بشكل صحيح في مشروع Flutter الخاص بك، تحتاج إلى استخدام تكوين Podfile التالي:

Podfile

target 'NotificationServiceExtension' do
  use_frameworks!
  use_modular_headers!

  pod 'PushwooshXCFramework'

  inherit! :search_paths
end

3.4 تثبيت التبعيات لمشروع iOS Flutter

لتثبيت التبعيات لمشروع iOS Flutter، قم بتشغيل الأمر التالي:

flutter run

أو انتقل إلى مجلد ios في الطرفية وقم بتشغيل:

pod install --repo-update

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 داخل وسم <application>:

AndroidManifest.xml

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

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

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

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

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

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

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

في Pushwoosh SDK، يوجد مستمعان للأحداث، مصممان للتعامل مع الإشعارات الفورية:

• يتم تشغيل حدث onPushReceived عند استلام إشعار فوري
• يتم تشغيل حدث onPushAccepted عندما يفتح المستخدم إشعارًا

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class PushwooshNotificationHandler {
  void setupPushListeners(Pushwoosh pushwoosh) {

    pushwoosh.onPushReceived.listen((event) {
      print("Push received: ${event.pushwooshMessage.payload}");
    });

    pushwoosh.onPushAccepted.listen((event) {
      print("Push accepted: ${event.pushwooshMessage.payload}");
    });

  }
}

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

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {
  void afterUserLogin(User user) {

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

    // Set user email
    Pushwoosh().setEmail(user.getEmail());

    // Register SMS number
    // The SMS and WhatsApp numbers must be in E.164 format (e.g., "+1234567890") and be valid
    Pushwoosh().registerSmsNumber(user.getSmsNumber());

    // Register WhatsApp number
    Pushwoosh().registerWhatsappNumber(user.getWhatsappNumber());

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

العلامات (Tags)

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class UpdateUser {
  void afterUserUpdateProfile(User 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)

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {

  // Track login event
  void afterUserLogin(User user) {
    Pushwoosh().postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  void afterUserPurchase(Product product) {

  // Track purchase event
  Pushwoosh().postEvent("purchase", {
    "product_id": product.getId(),
    "product_name": product.getName(),
    "price": product.getPrice(),
    "quantity": product.getQuantity()
  });
 }
}

استخدام ProGuard

ملاحظة

لاحظ أن أمر flutter build apk يقوم بإخفاء (obfuscates) الكود الخاص بك بشكل افتراضي.

وبالتالي، قد تحصل على هذا الاستثناء:

java.lang.IllegalStateException: Could not find class for name: com.pushwoosh.plugin.PushwooshNotificationServiceExtension

هناك حلان في هذه الحالة:

1. استخدم أمر flutter build apk --no-shrink لتجميع الكود الخاص بك دون إخفاء.
2. أو يمكنك تمكين ProGuard يدويًا وإضافة القواعد اللازمة.

لتمكين ProGuard لمشروعك، أضف السلاسل التالية إلى ملف build.gradle الخاص بك:

build.gradle

buildTypes {
        release {
            minifyEnabled true
            useProguard true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

            signingConfig signingConfigs.debug
        }
    }

بعد ذلك، أضف القواعد التالية إلى android/app/proguard-rules.pro

proguard-rules.pro

#Pushwoosh Flutter
-keep class com.pushwoosh.plugin.PushwooshPlugin { *; }
-keep class com.pushwoosh.plugin.PushwooshNotificationServiceExtension { *; }

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

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