تخصيص Android SDK

ملاحظة

تأكد من أنك قمت بدمج Pushwoosh Android SDK في مشروعك:

• تكامل Firebase
• تكامل Amazon

الربط العميق (Deep linking)

في نشاطك (activity) الذي سيتعامل مع الرابط العميق، أضف وسم <data> مع معلمات scheme و host و pathPrefix.

<activity
          android:name=".PromoActivity"
          android:label="PromoActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="com.pushwoosh"
          android:host="promotion"
          android:pathPrefix="" />
    </intent-filter>
</activity>

ملاحظة

اسم صفحة الرابط العميق (promotion في المثال المعطى) يذهب إلى حقل host، وليس pathPrefix.

في المثال أعلاه، سيفتح الرابط العميق PromoActivity. التنفيذ الأساسي أدناه يعرض تنبيهًا بقيمة معرف العرض الترويجي (promo id) من أجل البساطة. في تطبيقك، يمكنه بالتأكيد أن يفعل شيئًا مفيدًا!

public class PromoActivity extends Activity
{
    @Override
    protected void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);

        setContentView(R.layout.deep_link);
        setTitle("Deep link activity");

        Intent intent = getIntent();
        String action = intent.getAction();
        Uri data = intent.getData();

        if (TextUtils.equals(action, Intent.ACTION_VIEW))
        {
            openUrl(data);
        }
    }

    private void openUrl(Uri uri)
    {
        String promoId = uri.getQueryParameter("id");
        Toast.makeText(getApplicationContext(), promoId, Toast.LENGTH_LONG).show();
    }
}

تتبع عمليات الشراء داخل التطبيق

إذا كنت ترغب في تتبع عمليات الشراء داخل التطبيق في Customer Journeys، فقم بتهيئة إرسال معلومات الشراء إلى Pushwoosh عن طريق استدعاء هذه الطريقة:

Pushwoosh.getInstance().sendInappPurchase(@NonNull String sku, @NonNull BigDecimal price, @NonNull String currency);

إشعارات الدفع للمناطق الجغرافية (Geozones)

لاستخدام إشعارات الدفع للمناطق الجغرافية، أضف مكتبة com.pushwoosh:pushwoosh-location واستدعِ:

PushwooshLocation.startLocationTracking();

في ملف AndroidManifest.xml الخاص بك، قم بتضمين الأذونات اللازمة:

<manifest ... >
  <!-- Required for geolocation-based push notifications -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Required for precise location tracking -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

  <!-- Required for background location access on Android 10 (API level 29) and higher -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>

استخدام الإشعارات المحلية مع Pushwoosh

إذا كنت تستخدم Pushwoosh Local Notifications API، أضف إذن RECEIVE_BOOT_COMPLETED إلى ملف AndroidManifest.xml الخاص بك:

AndroidManifest.xml

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>x

استخدام رقم الشارة (badge number) على Android

يدعم Pushwoosh تعيين رقم الشارة على اختصار أيقونة التطبيق لمشغلات Android التالية:
Sony, Samsung, LG, HTC, ASUS, ADW, APEX, NOVA, HUAWEI, ZUK, OPPO.
لاستخدام هذه الوظيفة، ما عليك سوى إضافة مكتبة com.pushwoosh:pushwoosh-badge إلى تطبيقك.

فتح نشاط مخصص

إذا كنت ترغب في بدء نشاط معين استجابةً لإشعارات الدفع، أضف مرشح النوايا (intent-filter) التالي إلى ذلك النشاط:

AndroidManifest.xml

<activity android:name="YourActivity">
    <intent-filter>
        <action android:name="${applicationId}.MESSAGE"/>
        <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
</activity>

التحكم في مستوى السجل (Log Level)

للمساعدة في تصحيح الأخطاء والتكامل، ستقوم SDK بطباعة جميع الطلبات إلى وحدة التحكم بشكل افتراضي. عندما تكون جاهزًا للبناء الإنتاجي، أضف بيانات وصفية com.pushwoosh.log_level بقيمة “ERROR” إلى AndroidManifest.xml. بهذه الطريقة، ستذهب فقط المعلومات حول الأخطاء إلى وحدة التحكم. يمكن أن يكون الخيار الآخر واحدًا مما يلي:

NONE - لا توجد سجلات من SDK
ERROR - عرض الأخطاء فقط في وحدة التحكم
WARN - عرض التحذيرات أيضًا
INFO - عرض الرسائل الإعلامية
DEBUG - حتى معلومات تصحيح الأخطاء يتم عرضها الآن
NOISE - كل ما يمكن لـ SDK طباعته وأكثر

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.log_level" android:value="ERROR" />

استخدام Proguard

عند استخدام Proguard، أضف الخيارات التالية:

proguard-rules.pro

-keep class com.pushwoosh.** { *; }
-dontwarn com.pushwoosh.**

راجع متطلبات مكتبة Google Play Services بخصوص Proguard هنا:
https://developers.google.com/android/guides/setup

تخصيص سلوك فتح الإشعارات

إذا كنت بحاجة إلى تحديد النشاط الذي سيتم عرضه برمجيًا نتيجة لإشعار الدفع، يمكنك إنشاء NotificationServiceExtension مخصص وتضمين اسم الفئة المؤهل بالكامل لـ NotificationServiceExtension الخاص بك في البيانات الوصفية تحت قيمة com.pushwoosh.notification_service_extension.

AndroidManifest.xml

<meta-data
    android:name="com.pushwoosh.notification_service_extension"
    android:value="com.your.package.YourNotificationServiceExtension" />

YourNotificationServiceExtension.java

public class YourNotificationServiceExtension extends NotificationServiceExtension {
    @Override
    protected void startActivityForPushMessage(PushMessage message) {
      // super.startActivityForPushMessage() يبدأ نشاط المشغل الافتراضي
      // أو النشاط المحدد بإجراء ${applicationId}.MESSAGE.
      // ببساطة لا تستدعه لتجاوز هذا السلوك.
        // super.startActivityForPushMessage(message);

        // ابدأ نشاطك بدلاً من ذلك:
        Intent launchIntent  = new Intent(getApplicationContext(), YourActivity.class);
        launchIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED);

        // (اختياري) مرر بيانات الإشعار إلى النشاط
        launchIntent.putExtra(Pushwoosh.PUSH_RECEIVE_EVENT, message.toJson().toString());

        context.startActivity(launchIntent);
    }
}

ملاحظة

مهم

إذا كنت تستخدم proguard في البناءات الإنتاجية، فتأكد من أن NotificationServiceExtension المخصص الخاص بك ليس مشوشًا (عن طريق إضافة قاعدة -keep class)، وإلا فسيؤدي ذلك إلى ClassNotFoundException.

تخصيص إشعارات الدفع

لتخصيص عرض إشعارات الدفع، تحتاج إلى إنشاء Factory مخصص، يمكنك إنشاء NotificationFactory مخصص وتضمين اسم الفئة المؤهل بالكامل لـ NotificationFactory الخاص بك في البيانات الوصفية تحت قيمة com.pushwoosh.notification_factory.

AndroidManifest.xml

<meta-data
    android:name="com.pushwoosh.notification_factory"
    android:value="com.your.package.YourNotificationFactory" />

YourNotificationFactory

public class YourNotificationFactory extends PushwooshNotificationFactory {
  @Override
  public Notification onGenerateNotification(@NonNull PushMessage pushMessage) {
    if (customNotification) {
       // TODO: إنشاء وإرجاع إشعار مخصص
    }

    // إرجاع إشعار Pushwoosh الافتراضي
    return super.onGenerateNotification(pushMessage);
  }
}

تخصيص ملخص المجموعة

لتخصيص مظهر ملخص المجموعة، قم بإنشاء Factory مخصص. يمكنك إنشاء SummaryNotificationFactory مخصص وتضمين اسم الفئة المؤهل بالكامل لـ SummaryNotificationFactory الخاص بك في البيانات الوصفية تحت قيمة com.pushwoosh.summary_notification_factory.

AndroidManifest.xml

<meta-data
    android:name="com.pushwoosh.summary_notification_factory"
    android:value="com.your.package.YourSummaryNotificationFactory" />

YourSummaryNotificationFactory

public class YourSummaryNotificationFactory extends PushwooshSummaryNotificationFactory {
    @Override
    public String summaryNotificationMessage(int notificationsAmount) {
        // أرجع الرسالة التي تريدها
        return super.summaryNotificationMessage(notificationsAmount);
    }
    @Override
    public int summaryNotificationIconResId() {
        // أرجع معرف مورد الأيقونة الذي تريده
        return super.summaryNotificationIconResId();
    }
}

عنوان URL لنقطة النهاية الخاصة

ملاحظة

لاشتراكات الخطة المخصصة فقط. لمزيد من التفاصيل، يرجى الاتصال بفريق المبيعات.

يوفر Pushwoosh نقاط نهاية خاصة للعملاء الذين لديهم اشتراكات في الخطة المخصصة. لإعداد نقطة نهاية خاصة لـ Android SDK، تحتاج إلى إضافة ما يلي إلى ملف AndroidManifest.xml الخاص بك:

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.base_url" android:value="PUSHWOOSH_PRIVATE_ENDPOINT_URL_PROVIDED" />

إنشاء قائمة انتظار للوسائط الغنية (Rich Media)

في حالة وجود العديد من صفحات الوسائط الغنية لعرضها في وقت واحد (على سبيل المثال، تحدث أحداث التشغيل لاثنين أو أكثر من الرسائل داخل التطبيق في لحظة واحدة، أو يتم عرض صفحة وسائط غنية بالفعل في اللحظة التي يحدث فيها حدث تشغيل مختلف)، يمكنك إعداد قائمة انتظار لعرض صفحات الوسائط الغنية. لإنشاء قائمة انتظار، أضف الكود التالي إلى مشروعك:

Application.java

package com.pushwoosh.testingapp;

import com.pushwoosh.RichMediaManager;
import com.pushwoosh.exception.PushwooshException;
import com.pushwoosh.richmedia.RichMediaPresentingDelegate;
import com.pushwoosh.richmedia.RichMedia;
import com.pushwoosh.internal.utils.PWLog;

import java.util.ArrayDeque;
import java.util.concurrent.locks.ReentrantLock;

public class DefaultRichMediaPresentingDelegate implements RichMediaPresentingDelegate {
    private final String TAG = DefaultRichMediaPresentingDelegate.class.getSimpleName();
    private ArrayDeque<RichMedia> richMediaQueue = new ArrayDeque<>();
    private RichMedia currentRichMedia = null;
    private ReentrantLock reentrantLock;

    public DefaultRichMediaPresentingDelegate() {
        PWLog.noise(TAG, "new DefaultRichMediaPresentingDelegate:" + this);
        reentrantLock = new ReentrantLock();
    }

    @Override
    public boolean shouldPresent(RichMedia richMedia) {
        PWLog.noise(TAG, "shouldPresent:" + richMedia);
        if (currentRichMedia == null) {
            PWLog.noise(TAG, "currentRichMedia is null");
        }
        if (richMedia.isLockScreen()) {
            PWLog.noise(TAG, "isLockScreen is true");
            return true;
        }
        try {
            reentrantLock.lock();
            if (currentRichMedia == null) {
                PWLog.noise(TAG, "show:" + richMedia);
                currentRichMedia = richMedia;
                return true;
            } else {
                PWLog.noise(TAG, "add to queue:" + richMedia);
                richMediaQueue.add(richMedia);
                return false;
            }
        } finally {
            reentrantLock.unlock();
        }
    }

    @Override
    public void onPresent(RichMedia richMedia) {
        PWLog.noise(TAG, "onPresent" + richMedia);
    }

    @Override
    public void onError(RichMedia richMedia, PushwooshException pushwooshException) {
        PWLog.error(TAG, pushwooshException + " richMedia:"+richMedia.toString());
        tryShowNextRichMediaThreadSafety();
    }

    @Override
    public void onClose(RichMedia richMedia) {
        PWLog.noise(TAG, "onClose:" + richMedia);
        tryShowNextRichMediaThreadSafety();
    }

    private void tryShowNextRichMediaThreadSafety() {
        try {
            reentrantLock.lock();
            tryShowNextRichMedia();
        } finally {
            reentrantLock.unlock();
        }
    }

    private void tryShowNextRichMedia() {
        if (!richMediaQueue.isEmpty()) {
      currentRichMedia = richMediaQueue.poll();
      PWLog.noise(TAG, "try manual show:" + currentRichMedia);
      RichMediaManager.present(currentRichMedia);
    } else {
      PWLog.noise(TAG, "richMediaQueue is empty");
      currentRichMedia = null;
    }
    }
}

هام

نوصي بشدة بإعداد قائمة انتظار في Application بدلاً من Activity. وإلا، فقد يؤدي ذلك إلى إنشاء قوائم انتظار متعددة.

ملاحظة

كل استدعاء لطريقة postEvent يسمح فقط بعرض رسالة واحدة داخل التطبيق، وكل إشعار دفع يمكن أن يرتبط فقط بوسيط غني واحد. إذا كنت ترغب في عرض عدة رسائل داخل التطبيق، فاستدعِ طريقة postEvent بالعدد المطلوب من المرات.

إشعار دفع بصوت مخصص

ملاحظة

متاح لأجهزة Android 8+.

1. ضع ملف الصوت الخاص بك في المجلد المناسب. بالنسبة لإطار عمل Android الأصلي، يجب وضع ملفاتك في مجلد /app/src/main/res/raw.

ملاحظة

يرجى الرجوع إلى الأدلة المقابلة لمعرفة مكان وضع ملف الصوت في المشاريع المبنية على أطر عمل أخرى.

2. قم بإنشاء قناة إشعارات (Notification Channel).

3. حدد صوتًا أثناء تكوين رسالة الدفع.

4. قم بتعيين قناة الإشعارات التي ستنتمي إليها الرسالة. للقيام بذلك، حدد ما يلي في حقل “Android root params”: {"pw_channel": "PUSH NOTIFICATION CHANNEL NAME"} // _هنا تحتاج إلى تحديد اسم قناتك ذات الصوت المخصص_

في حالة استخدام remote API، قم بتعيين المعلمات على النحو التالي ضمن طلب /createMessage API الخاص بك:

"android_root_params": {"pw_channel": "push"} // هنا تحتاج إلى تحديد اسم قناتك ذات الصوت المخصص، على سبيل المثال، "push" للإشعارات بصوت push.wav.
"android_sound": "push" // هنا يجب تحديد اسم الملف بدون امتداد

بمجرد إرسال الدفع مع تحديد هذه المعلمات، يتم إنشاء قناة الإشعارات بالصوت المحدد لجميع الأجهزة التي تعمل بنظام Android 8+.

الآن، لإرسال الدفع بصوت مخصص، عليك فقط تحديد القناة المرتبطة بهذا الصوت.

قواعد Proguard لأصوات الإشعارات المخصصة

إذا كان تطبيقك يستخدم proguard لتقليص الكود والموارد، فمن المهم الحفاظ على ملفات الصوت الخاصة بك سليمة ومتاحة للمكتبات الخارجية. إذا كنت تستخدم خاصية minifyEnabled = true في build.gradle الخاص بك، فأضف القواعد التالية إلى proguard-rules.pro:

-keep public class your.package.name.R$raw {
 *;
}

إذا قمت بتقليص موارد تطبيقك بالإضافة إلى تقليص الكود باستخدام خاصية shrinkResources=true، فيجب عليك تحديد الموارد التي تريد الاحتفاظ بها بشكل إضافي. للقيام بذلك، قم بإنشاء ملف XML جديد بأي اسم، واحفظه في مكان ما في مشروعك (على سبيل المثال، في res/xml)، وحدد أسماء الموارد تحت معلمة tools:keep في وسم resources:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
 tools:keep="@raw/*"
/>

قائمة كاملة بعلامات البيانات الوصفية لـ Android SDK

لإعداد علامة، تحتاج إلى إضافة كتلة البيانات الوصفية إلى ملف AndroidManifest.xml الخاص بك داخل وسم application. على سبيل المثال، إذا كنت تريد تعيين معرف تطبيق Pushwoosh، أضف الكود التالي إلى ملف AndroidManifest.xml الخاص بك:

AndroidManifest.xml

<meta-data
    android:name="com.pushwoosh.appid"
    android:value="XXXXX-XXXXX" />

العلامة	الوصف	القيم الممكنة
com.pushwoosh.appid	يضبط معرف تطبيق Pushwoosh.	XXXXX-XXXXX
com.pushwoosh.log_level	يضبط مستوى التسجيل. لمزيد من التفاصيل، راجع التحكم في مستوى السجل.	NONE / ERROR / WARN / INFO / DEBUG (افتراضي) / NOISE
com.pushwoosh.base_url	يتجاوز عنوان URL الأساسي لخادم Pushwoosh.	https://cp.pushwoosh.com/json/1.3/ (افتراضي)
com.pushwoosh.notification_service_extension	NotificationServiceExtension مخصص. لمزيد من التفاصيل، راجع تخصيص سلوك فتح الإشعارات.	com.myapp.MyNotificationServiceExtension
com.pushwoosh.notification_factory	NotificationFactory مخصص. لمزيد من التفاصيل، راجع تخصيص إشعارات الدفع.	com.myapp.MyNotificationFactory
com.pushwoosh.summary_notification_factory	SummaryNotificationFactory مخصص.	com.myapp.MySummaryNotificationFactory
com.pushwoosh.multi_notification_mode	إذا كانت القيمة true، سيتم تجميع الإشعارات. إذا كانت false، سيتم عرض آخر إشعار تم استلامه فقط.	true / false (افتراضي)
com.pushwoosh.allow_server_communication	إذا كانت القيمة true، يُسمح لـ SDK بإرسال طلبات الشبكة إلى خوادم Pushwoosh.	true (افتراضي) / false
com.pushwoosh.handle_notifications_using_workmanager	إذا كانت القيمة true، يتم تعيين WorkManager للتعامل مع الإشعارات.	true / false (افتراضي)
com.pushwoosh.notification_icon	اسم مورد أيقونة الإشعار المخصصة (الصغيرة). إذا كانت القيمة null، سيتم استخدام أيقونة التطبيق الافتراضية.	res/drawable-xxhdpi-v11/notification_small_icon.png / null
com.pushwoosh.notification_icon_color	لون خلفية أيقونة الإشعار (الصغيرة).	#FFFFFF
com.pushwoosh.allow_collecting_device_data	إذا كانت القيمة true، يُسمح لـ SDK بجمع وإرسال بيانات الجهاز إلى Pushwoosh.	true (افتراضي) / false
com.pushwoosh.allow_collecting_device_os_version	إذا كانت القيمة true، يُسمح لـ SDK بجمع وإرسال إصدار نظام تشغيل الجهاز إلى Pushwoosh.	true (افتراضي) / false
com.pushwoosh.allow_collecting_device_locale	إذا كانت القيمة true، يُسمح لـ SDK بجمع وإرسال لغة الجهاز إلى Pushwoosh.	true (افتراضي) / false
com.pushwoosh.allow_collecting_device_model	إذا كانت القيمة true، يُسمح لـ SDK بجمع وإرسال طراز الجهاز إلى Pushwoosh.	true (افتراضي) / false
com.pushwoosh.in_app_business_solutions_capping	يحد من عدد المرات التي يمكن فيها عرض الرسالة داخل التطبيق push-unregister في اليوم.	1 (افتراضي), 2, …, n
com.pushwoosh.start_foreground_service	إذا كانت القيمة true، يتم تشغيل خدمة المقدمة (Foreground Service) مع استدعاء PushwooshLocation.startLocationTracking()	true / false (افتراضي)
com.pushwoosh.foreground_service_notification_text	يضبط نص الإشعار الذي يتم إنشاؤه عند تشغيل خدمة المقدمة لمفتاح “com.pushwoosh.start_foreground_service”.	العمل قيد التقدم (افتراضي)
com.pushwoosh.foreground_service_notification_channel_name	يضبط اسم القناة للإشعار الذي يتم إنشاؤه عند تشغيل خدمة المقدمة لمفتاح “com.pushwoosh.start_foreground_service”.	خدمة المقدمة (افتراضي)
com.pushwoosh.trusted_package_names	يسمح بمشاركة Pushwoosh HWID مع الحزمة المحددة	”com.mycompany.myapp1, com.mycompany.myapp2”

حذف إشعارات الدفع عبر TTL (Time-To-Live)

لحذف إشعارات الدفع تلقائيًا بعد فترة زمنية محددة باستخدام TTL (Time-to-Live)، اتبع الخطوات التالية:

1. قم بإنشاء NotificationFactory مخصص. اعرف المزيد

2. في طريقة onGenerateNotification()، قم بإنشاء إشعار باستخدام فئة Notification.Builder أو NotificationCompat.Builder واستدعِ طريقة setTimeoutAfter:

public class YourNotificationFactory extends PushwooshNotificationFactory {

    @Override
    public Notification onGenerateNotification(@NonNull PushMessage pushMessage) {
        Notification.Builder builder = new Notification.Builder(getApplicationContext(), addChannel(pushData));

        Notification notification = builder.setContentText(pushData.getMessage())
                                           .setContentTitle(title)
                                           .setContentText(text)
                                           // بقية كود إنشاء الإشعار الخاص بك
                                           .setTimeoutAfter(timeout) // الوقت بالمللي ثانية قبل إلغاء الإشعار
                                           .build();
    }
}

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

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