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

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

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

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

حساب Pushwoosh.
مشروع Pushwoosh مُعد في حسابك.
للتكامل مع iOS:
- منصة iOS مُهيأة لإرسال الإشعارات الفورية. نوصي باستخدام تهيئة المصادقة المستندة إلى الرمز المميز كأبسط طريقة.
- اضبط البوابة (Gateway) على Sandbox لإرسال الإشعارات إلى جهاز محاكاة.
للتكامل مع Android:
- منصة Android مُهيأة
- ملف google-services.json وpackage name من مشروع Firebase الخاص بك.
- مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع دليل إعداد Firebase إذا لزم الأمر.
Pushwoosh Application Code الخاص بك و Pushwoosh Device API Token من لوحة تحكم Pushwoosh لتطبيقك.

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

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

أضف حزمة pushwoosh_flutter إلى ملف 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() في منطق التهيئة الخاص بك للتسجيل في الإشعارات الفورية.

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

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

حيث:

__YOUR_APP_ID__ هو رمز التطبيق من لوحة تحكم 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:

<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 التالي:

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 على مستوى المشروع:

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

طبق الإضافة في ملف 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>:

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

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

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

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

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

في هذه المرحلة، لقد قمت بالفعل بدمج 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)

العلامات (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)

الأحداث (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

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

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

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

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

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

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

            signingConfig signingConfigs.debug
        }
    }

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

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

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

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