تخصيص 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();
    }
}

تتبع عمليات الشراء داخل التطبيق (In-app purchase tracking)

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

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

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

لاستخدام إشعارات الدفع للمناطق الجغرافية (Geozone pushes)، أضف مكتبة 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) على Android

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

فتح نشاط مخصص (custom activity)

إذا كنت ترغب في بدء نشاط معين استجابةً لإشعارات الدفع، أضف 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() 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);
    }
}

ملاحظة

مهم

إذا كنت تستخدم 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: generate and return custom notification
    }

    // return default Pushwoosh notification
    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 the message you want
        return super.summaryNotificationMessage(notificationsAmount);
    }
    @Override
    public int summaryNotificationIconResId() {
        // return the icon resource id you want
        return super.summaryNotificationIconResId();
    }
}

عنوان URL لنقطة النهاية الخاصة (Private endpoint)

ملاحظة

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

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

AndroidManifest.xml

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

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

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

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 يسمح بعرض In-App واحد فقط، وكل إشعار دفع يمكن ربطه بوسيط غني واحد فقط. إذا كنت ترغب في عرض عدة In-Apps، قم باستدعاء تابع 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"} // here you need to specify the name for your channel with custom sound, for example, "push" for the notifications with push.wav sound.
"android_sound": "push" // here you should specify the file name without extension

بمجرد إرسال إشعار الدفع مع تحديد هذه المعلمات، يتم إنشاء قناة الإشعارات بالصوت المحدد لجميع الأجهزة التي تعمل بنظام 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.senderid	يعيّن معرف مرسل مشروع Firebase.	123456789000
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	يحد من عدد المرات التي يمكن فيها عرض In-App push-unregister في اليوم.	1 (افتراضي), 2, …, n
com.pushwoosh.start_foreground_service	إذا كانت القيمة true، يتم إطلاق خدمة Foreground مع استدعاء PushwooshLocation.startLocationTracking()	true / false (افتراضي)
com.pushwoosh.foreground_service_notification_text	يعيّن نص الإشعار الذي يتم إنشاؤه عند إطلاق خدمة Foreground لمفتاح “com.pushwoosh.start_foreground_service”.	Work in progress (افتراضي)
com.pushwoosh.foreground_service_notification_channel_name	يعيّن اسم القناة للإشعار الذي يتم إنشاؤه عند إطلاق خدمة Foreground لمفتاح “com.pushwoosh.start_foreground_service”.	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)
                                           // rest of your notification creation code
                                           .setTimeoutAfter(timeout) // time in milliseconds before the notification is canceled
                                           .build();
    }
}

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

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