التحديثات المباشرة على أندرويد

يدعم Pushwoosh تحديثات أندرويد المباشرة (Android Live Updates) من خلال وحدة pushwoosh-liveupdates (SDK 6.9.0 والإصدارات الأحدث). التحديث المباشر هو إشعار مستمر بنمط التقدم يروجه النظام على شاشة القفل، وفي درج الإشعارات، وكشريحة حالة في شريط الحالة، حتى يتمكن المستخدمون من متابعة نشاط ما دون فتح تطبيقك.

تتم إدارة دورة الحياة بأكملها من الخادم: يرسل نظامك الخلفي إشعارًا فوريًا (push) عند بدء النشاط، والمزيد من الإشعارات مع تقدمه، وإشعارًا نهائيًا عند انتهائه. يقوم SDK بعرض كل إشعار تلقائيًا.

ما هي التحديثات المباشرة

تم تقديم التحديثات المباشرة في أندرويد 16 (API 36) كطريقة لإظهار نشاط حساس للوقت يبدأه المستخدم من البداية إلى النهاية. وهي تعتمد على إشعارات المنصة التي تركز على التقدم وواجهة برمجة التطبيقات Notification.ProgressStyle. من حيث المفهوم، هي النظير في أندرويد لـ Live Activities في iOS.

تغطي هذه الصفحة تكامل Pushwoosh فقط. لمعرفة سلوك المنصة وقواعد الترويج وإرشادات التصميم، راجع وثائق أندرويد الرسمية:

متى تستخدم التحديثات المباشرة

التحديثات المباشرة مخصصة لنشاط مستمر، يبدأه المستخدم، وحساس للوقت — شيء له بداية ونهاية واضحتان يهتم به المستخدم بشكل فعال في الوقت الحالي. السيناريوهات النموذجية لعملاء Pushwoosh:

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

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

المتطلبات

أندرويد 16 (API 36) أو أحدث. على الأجهزة الأقدم، تظل الوحدة غير نشطة وكل استدعاء لواجهة برمجة تطبيقات التحديث المباشر هو عملية آمنة لا تفعل شيئًا (no-op).
Pushwoosh Android SDK 6.9.0 أو أحدث.

أضف وحدة pushwoosh-liveupdates

أضف التبعية إلى ملف app/build.gradle الخاص بك:

dependencies {
    implementation 'com.pushwoosh:pushwoosh-liveupdates:<latest-version>'
}

استبدل <latest-version> بالإصدار الحالي من Maven Central.

يتم اكتشاف الوحدة تلقائيًا عند بدء التشغيل. تعلن عن الإذن المطلوب POST_PROMOTED_NOTIFICATIONS، وتسجل قناة الإشعارات الخاصة بها، وتعترض إشعارات التحديث المباشر قبل مسار الإشعارات الافتراضي. لا يوجد كود تهيئة إضافي — يقوم SDK بتعيين علامات ongoing و promoted، وتنزيل الأيقونة الكبيرة، وتعيين أزرار الإجراءات، ونشر الإشعار نيابة عنك.

إرسال تحديث مباشر

يمكنك إرسال التحديثات المباشرة من خلال Messaging API v2 عن طريق إضافة حقول التحديث المباشر إلى كائن root_params في كتلة محتوى android. استخدم طلب transactional — يستهدف التحديث المباشر المستخدم المحدد الذي يتم تتبع نشاطه. حقل schedule مطلوب؛ { "after": "0s" } يرسل على الفور. تحتوي دورة الحياة على ثلاث عمليات، يتم تعيينها في pw_live_op:

start — أول إشعار لنشاط. ينشر الإشعار المستمر.
update — إشعار لاحق لنفس النشاط. يحدّثه في مكانه، بصمت.
end — الإشعار النهائي. يغلق الإشعار.

يجب أن تشترك جميع الإشعارات التي تنتمي إلى نفس النشاط في نفس pw_live_id. يربط هذا المعرف التحديثات معًا وهو أيضًا ما تستخدمه لإغلاق التحديث من التطبيق.

يصف كل إشعار الإشعار بالكامل — لا يتم ترحيل أي شيء من الإشعار السابق. أعد إرسال كل حقل تريد الاحتفاظ به، مثل الأجزاء والأيقونة الكبيرة، مع كل update؛ يتم عرض الحقل المحذوف على أنه غائب.

معلمات التحديث المباشر

توضع هذه المفاتيح داخل كائن root_params في كتلة محتوى android. يستخدم العنوان والنص والأيقونة الكبيرة حقول الإشعارات الفورية القياسية في أندرويد (title، body، custom_icon).

المعلمة (Parameter)	النوع (Type)	الوصف (Description)
`pw_live_op`	سلسلة نصية (string)	عملية دورة الحياة: `start`، `update`، أو `end`. مطلوب.
`pw_live_id`	سلسلة نصية (string)	معرّف نشاط ثابت مشترك بين جميع إشعارات التحديث المباشر الواحد. مطلوب.
`pw_live_progress`	عدد صحيح (int)	قيمة التقدم، مقاسة مقابل مجموع أطوال الأجزاء.
`pw_live_progress_indeterminate`	منطقي (bool)	عرض رسم متحرك غير محدد بدلاً من قيمة ملموسة.
`pw_live_segments`	سلسلة JSON	أجزاء تقدم مرتبة، كل منها `{"color": "#RRGGBB", "length": N}`.
`pw_live_extras`	سلسلة JSON	بيانات عشوائية يتم تمريرها إلى موفر نمط مخصص.
`pw_live_when`	long	مرساة زمنية للرأس، بالمللي ثانية منذ بداية الحقبة (epoch).
`pw_live_chronometer`	منطقي (bool)	عرض وقت الرأس كمؤقت يعمل.
`pw_live_chronometer_count_down`	منطقي (bool)	مؤقت يعمل يعد تنازليًا بدلاً من التصاعدي.
`pw_live_show_when`	منطقي (bool)	عرض عمود وقت الرأس على الإطلاق. القيمة الافتراضية هي `true`.

تتحد حقول الوقت الأربعة على النحو التالي: عند تعيين pw_live_show_when إلى false يتم إخفاء الوقت؛ وإلا فإن pw_live_when هو المرساة، و pw_live_chronometer يحوله إلى عداد مباشر، و pw_live_chronometer_count_down يجعل هذا العداد يعمل بشكل عكسي.

إشعار البدء (Start push)

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "title": "Order #4521",
                "body": "We are preparing your order",
                "custom_icon": "https://example.com/restaurant.png",
                "root_params": {
                  "pw_live_op": "start",
                  "pw_live_id": "order_4521",
                  "pw_live_progress": "1",
                  "pw_live_segments": "[{\"color\":\"#34A853\",\"length\":3},{\"color\":\"#FBBC05\",\"length\":4},{\"color\":\"#4285F4\",\"length\":3}]",
                  "pw_live_extras": "{\"eta\":\"18:40\"}"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

إشعار التحديث (Update push)

أرسل update بنفس pw_live_id كلما تقدم النشاط. كرر الأجزاء والأيقونة — التحديث الذي يحذفها يتم عرضه بدونها.

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "title": "Order #4521",
                "body": "Your courier is on the way",
                "custom_icon": "https://example.com/restaurant.png",
                "root_params": {
                  "pw_live_op": "update",
                  "pw_live_id": "order_4521",
                  "pw_live_progress": "7",
                  "pw_live_segments": "[{\"color\":\"#34A853\",\"length\":3},{\"color\":\"#FBBC05\",\"length\":4},{\"color\":\"#4285F4\",\"length\":3}]"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

إشعار الإنهاء (End push)

يحتاج الإشعار النهائي فقط إلى العملية والمعرف.

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "root_params": {
                  "pw_live_op": "end",
                  "pw_live_id": "order_4521"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

تخصيص المظهر

يأتي SDK مع نمط تقدم افتراضي مبني من pw_live_progress، pw_live_progress_indeterminate، و pw_live_segments. للتحكم الكامل في شريط التقدم، قم بتنفيذ LiveUpdateProgressStyleProvider وشكّل Notification.ProgressStyle بنفسك.

الموفر هو نقطة التخصيص الوحيدة. لا يزال SDK مسؤولاً عن إعداد القناة، وعلامات ongoing و promoted، والأيقونة الكبيرة، وأزرار الإجراءات، ووقت الرأس — يمكن لموفر مخصص فقط تشكيل شريط التقدم، لذلك لا يمكنه كسر أهلية الترويج. يجب أن يكون عديم الحالة (stateless): اشتق النمط المُرجع فقط من LiveUpdateState المقدم. إذا ألقى استثناءً، يعود SDK إلى النمط الافتراضي ولا يزال الإشعار يُنشر.

Java
Kotlin

import android.app.Notification;
import androidx.annotation.NonNull;
import com.pushwoosh.liveupdates.LiveUpdateProgressStyleProvider;
import com.pushwoosh.liveupdates.LiveUpdateSegment;
import com.pushwoosh.liveupdates.LiveUpdateState;
import java.util.List;

public class OrderStyleProvider implements LiveUpdateProgressStyleProvider {
    @NonNull
    @Override
    public Notification.ProgressStyle createStyle(@NonNull LiveUpdateState state) {
        Notification.ProgressStyle style = new Notification.ProgressStyle();
        if (state.getProgress() != null) {
            style.setProgress(state.getProgress());
        }
        style.setProgressIndeterminate(state.isProgressIndeterminate());

        List<LiveUpdateSegment> segments = state.getSegments();
        int boundary = 0;
        for (int i = 0; i < segments.size(); i++) {
            LiveUpdateSegment seg = segments.get(i);
            style.addProgressSegment(
                new Notification.ProgressStyle.Segment(seg.getLength()).setColor(seg.getColor()));
            boundary += seg.getLength();
            if (i < segments.size() - 1) {
                style.addProgressPoint(new Notification.ProgressStyle.Point(boundary));
            }
        }
        return style;
    }
}

import android.app.Notification
import com.pushwoosh.liveupdates.LiveUpdateProgressStyleProvider
import com.pushwoosh.liveupdates.LiveUpdateState

class OrderStyleProvider : LiveUpdateProgressStyleProvider {
    override fun createStyle(state: LiveUpdateState): Notification.ProgressStyle {
        val style = Notification.ProgressStyle()
        state.progress?.let { style.setProgress(it) }
        style.setProgressIndeterminate(state.isProgressIndeterminate)

        val segments = state.segments
        var boundary = 0
        segments.forEachIndexed { i, seg ->
            style.addProgressSegment(
                Notification.ProgressStyle.Segment(seg.length).setColor(seg.color))
            boundary += seg.length
            if (i < segments.size - 1) {
                style.addProgressPoint(Notification.ProgressStyle.Point(boundary))
            }
        }
        return style
    }
}

سجل الموفر باستخدام علامة <meta-data> في AndroidManifest.xml. يجب أن يحتوي الصنف على مُنشئ عام بدون وسائط.

<meta-data
    android:name="com.pushwoosh.LIVE_UPDATE_STYLE_PROVIDER"
    android:value="com.example.OrderStyleProvider" />

استخدم LiveUpdateState.getExtras() لقراءة JSON الذي أرسلته في pw_live_extras وتكييف النمط مع بيانات عملك الخاصة.

إدارة التحديثات المباشرة من تطبيقك

يقود الخادم كل start، update، و end، لذلك لا توجد واجهة برمجة تطبيقات من جانب التطبيق لنشر أو تحديث تحديث مباشر. تغطي واجهة PushwooshLiveUpdates فقط ما لا يستطيع الخادم القيام به — إغلاق تحديث محليًا والتحقق من التحديثات المعروضة على الشاشة.

import com.pushwoosh.liveupdates.PushwooshLiveUpdates;

// إغلاق تحديث مباشر محدد عندما ينهي المستخدم النشاط داخل التطبيق،
// دون انتظار إشعار "end" النهائي من الخادم
PushwooshLiveUpdates.endLiveUpdate("order_4521");

// سرد معرفات الأنشطة المعروضة حاليًا بواسطة هذا التطبيق
List<String> active = PushwooshLiveUpdates.getActiveIds();

// مسح كل ما يعرضه هذا التطبيق، على سبيل المثال عند تسجيل الخروج
PushwooshLiveUpdates.endAllLiveUpdates();

جميع الطرق آمنة للاستدعاء من أي خيط وهي عملية لا تفعل شيئًا (no-op) على الأجهزة التي تعمل بإصدار أقدم من أندرويد 16.