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

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

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

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

المتطلبات

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

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__"
  });
  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:

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 الوصفية (metadata)

في 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 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) {

    // تعيين معرف المستخدم
    Pushwoosh().setUserId(user.getId());

    // تعيين بريد المستخدم الإلكتروني
    Pushwoosh().setEmail(user.getEmail());

    // تسجيل رقم SMS
    // يجب أن تكون أرقام SMS و WhatsApp بتنسيق E.164 (على سبيل المثال، "+1234567890") وأن تكون صالحة
    Pushwoosh().registerSmsNumber(user.getSmsNumber());

    // تسجيل رقم WhatsApp
    Pushwoosh().registerWhatsappNumber(user.getWhatsappNumber());

    // تعيين معلومات مستخدم إضافية كعلامات لـ 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) {

    // تعيين قائمة الفئات المفضلة
    Pushwoosh().setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // تعيين معلومات الدفع
    Pushwoosh().setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

الأحداث (Events)

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {

  // تتبع حدث تسجيل الدخول
  void afterUserLogin(User user) {
    Pushwoosh().postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  void afterUserPurchase(Product product) {

  // تتبع حدث الشراء
  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 { *; }

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

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