MAUI Dotnet

• مصدر الوحدة
• تنزيل العينة

المتطلبات

لدمج SDK، يحتاج مشروع MAUI الخاص بك إلى إصدار الحزمة وأطر العمل المستهدفة والحد الأدنى لإصدارات نظام التشغيل التالية:

• Pushwoosh.DotNet 2.1.0 أو أحدث. تتضمن الحزمة إصدارات لـ .NET 8 و .NET 10 (net10.0-android36.0 و net10.0-ios26.0).

• Android: إطار العمل المستهدف net8.0-android34.0 أو أعلى، والأجهزة التي تعمل بـ API 23 أو أحدث. يتحول net8.0-android العادي إلى android34.0 في .NET 8 SDK.

• iOS: الأجهزة التي تعمل بـ iOS 15.0 أو أحدث. حدد الحد الأدنى في ملف مشروعك:

  <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">15.0</SupportedOSPlatformVersion>

  مع قيمة أقل، يتوقف البناء مع error PW0001.

دمج SDK

1. أضف حزمة Nuget Pushwoosh.DotNet إلى كل من مشروعي Android و iOS:

2. اقبل التراخيص للاعتماديات العابرة لـ Android إذا لزم الأمر:

3. قم بتهيئة مشروعك في Firebase Console.

4. أضف google-services.json إلى الدليل الجذر لمنصة Android الخاصة بك. قم بتعيين إجراء البناء GoogleServicesJson لهذا الملف:

5. أضف السطر التالي قبل تعريف مساحة الاسم (namespace) في ملف MainApplication.cs الخاص بك (XXXXX-XXXXX هنا هو رمز تطبيق Pushwoosh الخاص بك):

[assembly: MetaData("com.pushwoosh.appid", Value = "XXXXX-XXXXX")]

6. في ملف MainApplication.cs الخاص بك، قم بتجاوز (override) دالة OnCreate() واستدعِ PushManager.Init(); قبل base.OnCreate();:

using Android.App;
using Android.Runtime;
using Pushwoosh.Android;
...
[Application]
public class MainApplication : MauiApplication
{
    public MainApplication(IntPtr handle, JniHandleOwnership ownership)
        : base(handle, ownership)
    {
    }

    public override void OnCreate()
    {
        PushManager.Init();
        base.OnCreate();
    }

    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

تقوم base.OnCreate() ببناء تطبيق MAUI وإنشاء App، الذي يستخدم PushManager.Instance بالفعل. لا تستدعِ PushManager.Init() من MainActivity.OnCreate. يتم إنشاء الـ Activity بعد App، لذلك سيظل PushManager.Instance بقيمة null عندما يحتاجه App.

7. في ملف AndroidManifest.xml الخاص بك، أضف ما يلي:

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

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

8. في مجلد منصة iOS، أنشئ الملف Platforms/iOS/Entitlements.plist مع المفتاح aps-environment:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>aps-environment</key>
  <string>development</string>
</dict>
</plist>

بدون هذا الـ entitlement، لا يصدر iOS رمز جهاز APNs، لذلك يفشل Register() دائمًا. استخدم development لإصدارات التصحيح. يحتاج إصدار التوزيع إلى production وملف تعريف توفير (provisioning profile) مع تمكين الإشعارات الفورية.

9. في ملف مشروعك (.csproj)، وجّه هدف iOS إلى ملف الـ entitlements:

<PropertyGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">
  <CodesignEntitlements>Platforms/iOS/Entitlements.plist</CodesignEntitlements>
</PropertyGroup>

10. في ملف AppDelegate.cs لمشروع iOS الخاص بك، استدعِ PushManager.Init(); في بداية دالة FinishedLaunching:

using Foundation;
using UIKit;
using Pushwoosh.iOS;
...
public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
{
    PushManager.Init();
    return base.FinishedLaunching(application, launchOptions);
}

11. أضف هذه الدوال إلى AppDelegate. فئة MauiUIApplicationDelegate لا تقوم بتصديرها بشكل افتراضي، لذلك أضفها يدويًا:

[Export("application:didReceiveRemoteNotification:fetchCompletionHandler:")]
    public void DidReceiveRemoteNotification(UIKit.UIApplication application, NSDictionary userInfo, Action<UIKit.UIBackgroundFetchResult> completionHandler)
    {
        PushManager.Instance.ReceivedRemoteNotification(userInfo);
    }

[Export("application:didRegisterForRemoteNotificationsWithDeviceToken:")]
    public void RegisteredForRemoteNotifications(UIKit.UIApplication application, NSData deviceToken)
    {
        PushManager.Instance.RegisteredForRemoteNotifications(deviceToken);
    }

[Export("application:didFailToRegisterForRemoteNotificationsWithError:")]
    public void FailedToRegisterForRemoteNotifications(UIKit.UIApplication application, NSError error)
    {
        PushManager.Instance.FailedToRegisterForRemoteNotifications(error);
    }

12. في ملف Info.plist، قم بتغيير قيمة Pushwoosh_APPID إلى رمز تطبيق Pushwoosh الخاص بك. يمكنك العثور عليه في لوحة التحكم الخاصة بك:

13. في ملف Info.plist، اضبط المفتاح Pushwoosh_API_TOKEN على رمز Pushwoosh Device API الخاص بك.

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

14. في الجزء متعدد المنصات من ملف App.xaml.cs، استدعِ Register() في دالة OnStart. تطلب من المستخدم إذن الإشعارات وتسجل الجهاز لتلقي الإشعارات الفورية:

using PushwooshSDK.DotNet.Core;
...
public partial class App : Application
{
...
    protected override void OnStart()
    {
        base.OnStart();
        PushManager.Instance.Register();
    }
}

الترقية من 2.0.x إلى 2.1.0

إذا تم إعداد تطبيقك باستخدام إصدار سابق من هذا الدليل، فأجرِ هذه التغييرات عند التحديث إلى 2.1.0:

• على Android، انقل PushManager.Init() من MainActivity.OnCreate إلى MainApplication.OnCreate، قبل base.OnCreate()، كما في الخطوة 6. إذا كنت تستخدم Geozones، فانقل LocationManager.Init() إلى هناك أيضًا، مباشرةً بعد PushManager.Init().
• احذف سطر البيانات الوصفية com.pushwoosh.senderid والسلسلة fcm_sender_id من Resources/values/strings.xml. لا يقرأها SDK.
• على iOS، أضف الـ entitlement aps-environment من الخطوتين 8 و 9 إذا لم يكن موجودًا في تطبيقك بعد.
• ارفع SupportedOSPlatformVersion لهدف iOS إلى 15.0، كما هو موضح في المتطلبات. يضبط قالب مشروع MAUI 8 القيمة 11.0.
• إذا كان تطبيقك يستخدم Geozones، فحدّث Pushwoosh.DotNet.Geozones إلى 2.1.0 مع Pushwoosh.DotNet. مع Geozones 2.0.x، يتوقف البناء مع error PW0002.
• تم وضع علامة [Obsolete] على PWInlineInAppView في iOS ولا يعرض شيئًا، لأن iOS SDK الأصلي 7.x لا يحتوي على رسائل In-App مضمّنة. احذفه من تخطيطاتك.

ملاحظة لمستخدمي Windows: عند البناء، قد تواجه مشكلة تتعلق بطول مسار الملف. يرجع هذا إلى أن الطول المجمع للمجلدات التي يستخدمها Visual Studio ومسارات الملفات داخل Pushwoosh SDK يتجاوز الحد الأقصى لطول المسار في Windows وهو 260 حرفًا. لحل هذه المشكلة، قم بتمكين إعداد LongPathsEnabled في سجل Windows.

شاركنا ملاحظاتك

تساعدنا ملاحظاتك في إنشاء تجربة أفضل، لذلك نود أن نسمع منك إذا واجهت أي مشاكل أثناء عملية دمج SDK. إذا واجهت أي صعوبات، فلا تتردد في مشاركة أفكارك معنا عبر هذا النموذج.