# دليل الترحيل

### الترحيل من Android SDK 5 إلى 6

1.  قم بترحيل مشروعك إلى AndroidX وفقًا [للتوثيق الرسمي](https://developer.android.com/jetpack/androidx/migrate).
2.  أضف وحدة جديدة في ملف **build.gradle** الخاص بالتطبيق إذا كنت تستخدم **Firebase Cloud Messaging**.

```groovy title="build.gradle"
implementation 'com.pushwoosh:pushwoosh-firebase:+'
```

بالنسبة لأولئك الذين يستخدمون **Amazon**، ولا يستخدمون **Firebase**، لا توجد تغييرات مطلوبة.

### الترحيل من الإصدارات السابقة من Android SDK

أصبحت معظم فئات وأساليب Pushwoosh مهملة منذ إصدار 5.0، وبعضها انقرض. لا تزال فئات **PushManager** و **BasePushMessageReceiver** و **BaseRegistrationReceiver** و **SendPushTagsCallback** و **PushFragment** و **PushEventListener** متاحة كجزء من مكتبة `com.pushwoosh:pushwoosh-deprecated`، ولكن يوصى بالترحيل إلى واجهة برمجة التطبيقات (API) الجديدة في أقرب وقت ممكن.

## PushManager

تكون **PushManager** من أساليب متنوعة لميزات مختلفة. هذه الأساليب مقسمة الآن بين فئات ومكتبات مختلفة:
`com.pushwoosh:pushwoosh`: **Pushwoosh**, **PushwooshNotificationSettings**, **PushwooshInApp**.
`com.pushwoosh:pushwoosh-badge`: **PushwooshBadge**.
`com.pushwoosh:pushwoosh-location`: **PushwooshLocation**.
`com.pushwoosh:pushwoosh-beacon`: **PushwooshBeacon**.

## BaseRegistrationReceiver

كان **BaseRegistrationReceiver** يستخدم للتعامل مع أحداث تسجيل وإلغاء تسجيل Push. تم استبدال هذا المستقبل الآن بآلية رد اتصال بسيطة:

```java
Pushwoosh.getInstance().registerForPushNotifications(result -> {
    if (result.isSuccess()) {
        String token = result.getData();
        // handle successful registration
    }
    else {
        PushwooshException exception = result.getException();
        // handle registration error
    }
});
```

## BasePushMessageReceiver

كان **BasePushMessageReceiver** يستخدم لمحاكاة سلوك إشعارات iOS عند تلقي إشعار Push في المقدمة. تم تحقيق ذلك عن طريق إلغاء الإشعار الوارد واستدعاء رد الاتصال **onMessageReceive**. كان الأمر معقدًا ويتطلب تسجيلًا يدويًا عندما يصبح التطبيق نشطًا وإلغاء التسجيل عندما ينتقل التطبيق إلى الخلفية.
تم استبدال هذا المستقبل بـ **NotificationServiceExtension**:

```txt title="AndroidManifest.xml"
<meta-data
    android:name="com.pushwoosh.notification_service_extension"
    android:value="com.your.package.name.YourNotificationServiceExtension"/>
```

```java title="YourNotificationServiceExtension.java"
public class YourNotificationServiceExtension extends NotificationServiceExtension {
    @Override
    public boolean onMessageReceived(final PushMessage message) {
        if (isAppOnForeground()) {
            Handler mainHandler = new Handler(getApplicationContext().getMainLooper());
            mainHandler.post(() -> {
                handlePush(message);
            });

            // this indicates that notification should not be displayed
            return true;
        }

        return false;
    }

    @Override
    protected void startActivityForPushMessage(PushMessage message) {
        super.startActivityForPushMessage(message);
        handlePush(message);
    }

    @MainThread
    private void handlePush(PushMessage message) {
        // TODO: handle push message
    }
}
```

يستخدم هذا الامتداد أيضًا للتعامل مع وصول الإشعارات وقبول الأحداث، وبالتالي استبدال جميع التعليمات البرمجية المعقدة التي كانت تستخدم في تكامل Activity اليدوي.

## PushFragment

كان **PushFragment** بديلاً خفيف الوزن للتكامل المعقد الذي يتضمن دورة حياة Activity. ولكن من ناحية أخرى، كان يتطلب وراثة **FragmentActivity** واستخدم ضمنيًا دورة حياة Fragment الأكثر تعقيدًا.
تم استبدال **PushFragment** و **PushEventListener** الآن بـ **Pushwoosh#registerForPushNotifications(Callback)** و **NotificationServiceExtension**.

## Custom Push Broadcast Receiver (PW\_NOTIFICATION\_RECEIVER)

كان **PW\_NOTIFICATION\_RECEIVER** يستخدم لتخصيص السلوك عندما ينقر المستخدم على إشعار. سمح هذا بالتعامل مع الإشعارات خارج سياق Activity وفتح أنشطة مختلفة اعتمادًا على محتوى الإشعار. استخدم هذا التكامل واجهة برمجة تطبيقات Pushwoosh SDK الداخلية التي لم تعد موجودة.
تم استبدال هذا المستقبل الآن بالكامل بـ **NotificationServiceExtension**:

```java title="YourNotificationServiceExtension.java"
public class YourNotificationServiceExtension extends NotificationServiceExtension {
    @Override
    protected void startActivityForPushMessage(PushMessage message) {
    	// super.startActivityForPushMessage() starts default launcher activity 
    	// or activity marked with ${applicationId}.MESSAGE action.
    	// Simply do not call it to override this behaviour.
        // super.startActivityForPushMessage(message);

        // start your activity instead:
        Intent launchIntent  = new Intent(getApplicationContext(), YourActivity.class);             
        launchIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED);
 
        // (Optional) pass notification data to Activity
        launchIntent.putExtra(Pushwoosh.PUSH_RECEIVE_EVENT, message.toJson().toString());
 
        context.startActivity(launchIntent);
    }
}
```

## Notification Factory

كانت هناك أيضًا بعض التغييرات الجذرية التي تتضمن مصنع الإشعارات:

**1.** تم استبدال **AbsNotificationFactory** بـ **NotificationFactory**.
**2.** تم استبدال أساليب **AbsNotificationFactory#onPushReceived(PushData)** و **AbsNotificationFactory#onPushHandle(Activity)** بفئة **NotificationServiceExtension** (**onMessageReceived**, **startActivityForPushMessage**).
**3.** تم استبدال **DefaultNotificationFactory** بـ **PushwooshNotificationFactory**.
**4.** تم استبدال **PushData** بـ **PushMessage**.

## In-App Messages

**1.** تم استبدال **InAppFacade** بـ **PushwooshInApp**.
**2.** تم تقديم كائن `pushwoosh` لواجهة JavaScript الأصلية مع واجهة برمجة التطبيقات (API) التالية:
**getHwid(): string** - تُرجع معرف الجهاز (hwid) الخاص بـ Pushwoosh للجهاز الحالي.
**getVersion(): string** - تُرجع إصدار Pushwoosh SDK الحالي.
**postEvent(event: string, attributes?: object, successCallback?: function, errorCallback?: function)** - تُرسل طلب postEvent.
**sendTags(tags: object)** - تُرسل العلامات المرتبطة بالجهاز الحالي.
**getTags(successCallback: function, errorCallback?: function)** - تُرجع العلامات المرتبطة بالجهاز الحالي.
**closeInApp()** - تُغلق صفحة HTML الخاصة بالرسائل داخل التطبيق (In-App).

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

تساعدنا ملاحظاتك في إنشاء تجربة أفضل، لذا نود أن نسمع منك إذا واجهت أي مشاكل أثناء عملية دمج SDK. إذا واجهت أي صعوبات، فلا تتردد في مشاركة أفكارك معنا [عبر هذا النموذج](https://docs.google.com/forms/d/e/1FAIpQLSd_0b8jwn-V_JmoPLIxIFYbHACCQhrzidOZV3ELywoQPXRSxw/viewform).