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

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

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

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

المتطلبات

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

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

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

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

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  # استخدم أحدث إصدار من https://pub.dev/packages/pushwoosh_flutter
  pushwoosh_flutter: ^[LATEST_VERSION]

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

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

flutter pub get

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

flutter pub deps | grep pushwoosh_flutter

# مثال على الإخراج:
# ❯ 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.

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

3.1 الإمكانيات (Capabilities)

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

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

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

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

3.2 Info.plist

في ملف Runner/Info.plist الخاص بك، اضبط المفتاح __PUSHWOOSH_DEVICE_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 الضروري بداخله.

للتأكد من أن 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 في Terminal وقم بتشغيل:

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 الخاص بك، أضف رمز 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 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 { *; }

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

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