انتقل إلى المحتوى
أدلة المستخدم الدعم طلب عرض توضيحي تسجيل الدخول
Pushwoosh.com

الأنشطة المباشرة في iOS

تعرض الأنشطة المباشرة (Live Activities) أحدث بيانات تطبيقك على شاشة القفل في iPhone أو iPad وفي الجزيرة الديناميكية (Dynamic Island). تتيح هذه الميزة للمستخدمين رؤية المعلومات المباشرة بلمحة سريعة وتنفيذ إجراءات سريعة تتعلق بالمعلومات المعروضة.

إليك بعض الأمثلة على استخدام الأنشطة المباشرة:

  • عرض حالة الطلب في تطبيق توصيل؛
  • توفير عد تنازلي في الوقت الفعلي في تطبيق تدريب؛
  • عرض معلومات التتبع في تطبيق سيارات الأجرة؛
  • عرض إحصائيات اللعبة والنتائج الحالية في تطبيق رياضي؛
  • توفير توقعات الطقس كل ساعة في تطبيق الطقس.

يمكنك تمكين الأنشطة المباشرة باستخدام Pushwoosh iOS SDK كما هو موضح أدناه. لإدارة الأنشطة المباشرة وتحديث محتواها، استخدم طريقة /updateLiveActivity.

الإعداد

Anchor link to

إضافة ملحق واجهة المستخدم (Widget Extension)

Anchor link to
  1. إنشاء هدف جديد

اذهب إلى ملف > جديد > هدف (File > New > Target) واختر ملحق واجهة المستخدم (Widget Extension).

  1. إعداد ملحق واجهة المستخدم الرجاء إدخال اسم والتأكد من تحديد تضمين النشاط المباشر (Include Live Activity) والنقر على إنهاء (Finish).

إعداد Info.plist

Anchor link to

ابحث عن ملف Info.plist في الهدف الأساسي، وأدرج مفتاح “Supports Live Activities”، واضبط قيمته على YES.

  <key>NSSupportsLiveActivities</key>
  <true/>

تمكين الأنشطة المباشرة من التطبيق

Anchor link to

لتمكين الأنشطة المباشرة، أضف الكود الخاص بها إلى ملحق الواجهة الحالي أو أنشئ واحدًا جديدًا إذا لم يكن لدى تطبيقك واحد بالفعل. تستخدم الأنشطة المباشرة وظائف SwiftUI و WidgetKit لواجهتها الرسومية. يتعامل ActivityKit مع دورة حياة كل نشاط مباشر: يتم استخدام واجهة برمجة التطبيقات الخاصة به لطلب وتحديث وإنهاء نشاط مباشر واستلام إشعارات الدفع من ActivityKit. يمكنك معرفة المزيد عن الأنشطة المباشرة في توثيق Apple.

  1. انتقل إلى ملف ContentView لمشروعك في Xcode وأنشئ زرًا (Button)
import SwiftUI


struct ContentView: View {
    var body: some View {
        VStack(spacing: 20) {


            Button(action: {
                LiveActivityManager.shared.startActivity()
            }, label: {
                Text("Start Live Activity")
                    .foregroundColor(.white)
                    .padding()
                    .background(Color.blue)
                    .cornerRadius(10)
            })
        }
        .padding()
    }
}


#Preview {
    ContentView()
}
  1. أنشئ ملف LiveActivityManager.swift لإدارة الأنشطة المباشرة
import Foundation
import ActivityKit
import UIKit
import PushwooshFramework
import PushwooshLiveActivities


class LiveActivityManager: NSObject, ObservableObject {
    public static let shared: LiveActivityManager = LiveActivityManager()


    private var currentActivity: Activity<FoodDeliveryAttributes>? = nil


    override init() {
        super.init()
    }


    func startActivity() {
        guard ActivityAuthorizationInfo().areActivitiesEnabled else {
            print("You can't start live activity.")
            return
        }
        do {
            let pushwooshData = PushwooshLiveActivityAttributeData(activityId: "activity_id")
            let atttribute = FoodDeliveryAttributes(orderNumber: "1234567", pushwoosh: pushwooshData)
            let initialState = FoodDeliveryAttributes.ContentState(
                status: "Preparing your meal",
                estimatedTime: "25 min",
                emoji: "👨‍🍳",
                pushwoosh: nil
            )
            let activity = try Activity<FoodDeliveryAttributes>.request(
                attributes: atttribute,
                content: .init(state:initialState , staleDate: nil),
                pushType: .token
            )
            self.currentActivity = activity


            Task {
                for await pushToken in activity.pushTokenUpdates {
                    let pushTokenString = pushToken.reduce("") {
                        $0 + String(format: "%02x", $1)
                    }
                    print("Activity:\(activity.id) push token: \(pushTokenString)")


                    // MARK: - Send Push Token to Pushwoosh
                    Pushwoosh.LiveActivities.startLiveActivity(
                        token: pushTokenString,
                        activityId: "activity_id"
                    )
                }
            }
        } catch {
            print("Start Activity Error: \(error.localizedDescription)")
        }
    }
}
  1. هذا كل شيء، الآن نقوم بتشغيل المشروع ونضغط على زر ‘Start Live Activity’. ثم ننتقل إلى شاشة القفل ونرى النشاط المباشر الذي تم إنشاؤه.

بدء نشاط مباشر بإشعار دفع عن بعد

Anchor link to
  1. لبدء نشاط مباشر عبر إشعار دفع عن بعد، تحتاج إلى إرسال رمز pushToStartTokenUpdates إلى Pushwoosh.
func getPushToStartToken() {
    if #available(iOS 17.2, *) {
        Task {
            for await data in Activity<LiveActivityAttributes>.pushToStartTokenUpdates {
                let token = data.map {String(format: "%02x", $0)}.joined()
                print("Activity PushToStart Token: \(token)")


                // Send `pushToStartTokenUpdates` token to Pushwoosh
                try await Pushwoosh.LiveActivities.sendPushToStartLiveActivity(token: token)
            }
        }
    }
}
  1. بدء نشاط مباشر بإشعار دفع عن بعد

إدارة الأنشطة المباشرة

Anchor link to

يوفر Pushwoosh iOS SDK الطرق التالية للعمل مع الأنشطة المباشرة:

// Send Live Activity Push To Start Token to Pushwoosh
static func sendPushToStartLiveActivity(token: String)
static func sendPushToStartLiveActivity(token: String, completion: @escaping (Error?) -> Void)


// Start Live Activity Methods with Activity ID
static func startLiveActivity(token: String, activityId: String)
static func startLiveActivity(token: String, activityId: String, completion: @escaping (Error?) -> Void)


// Stop Live Activity Methods
static func stopLiveActivity()
static func stopLiveActivity(completion: @escaping (Error?) -> Void)


static func stopLiveActivity(activityId: String)
static func stopLiveActivity(activityId: String, completion: @escaping (Error?) -> Void)


// Schedule a Live Activity to start at a future date (iOS 26.0+)
static func schedule<Attributes: PushwooshLiveActivityAttributes>(attributes: Attributes, contentState: Attributes.ContentState, at startDate: Date, alertTitle: String, alertBody: String) throws -> Activity<Attributes>


// Cancel a scheduled or running Live Activity by its Activity ID (iOS 16.2+)
static func cancel<Attributes: PushwooshLiveActivityAttributes>(_ activityType: Attributes.Type, activityId: String)

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

على سبيل المثال، اشترك N من المستخدمين في نفس الحدث في نشاط مباشر. من الضروري أن يكون معامل Activity ID فريدًا لجميع هؤلاء المستخدمين N.

عند الانتهاء من العمل مع نشاط مباشر، استخدم هذه الطرق:

static func stopLiveActivity()
static func stopLiveActivity(completion: @escaping (Error?) -> Void)

جدولة نشاط مباشر ليبدأ في تاريخ مستقبلي

Anchor link to

بدلاً من بدء نشاط مباشر على الفور، يمكنك جدولته ليبدأ في تاريخ مستقبلي. يتم عرض alertTitle و alertBody للمستخدم في تنبيه الإشعار المحلي الذي يتم إطلاقه عند بدء النشاط المجدول بالفعل:

if #available(iOS 26.0, *) {
    let startDate = Date().addingTimeInterval(3600) // starts in 1 hour


    do {
        let activity = try Pushwoosh.LiveActivities.schedule(
            attributes: atttribute,
            contentState: initialState,
            at: startDate,
            alertTitle: "Game starting!",
            alertBody: "The match is about to begin"
        )
        self.currentActivity = activity
    } catch {
        print("Schedule Activity Error: \(error.localizedDescription)")
    }
}

يجب أن يكون startDate في المستقبل، وإلا فإن الاستدعاء يطرح خطأ. استدعِ schedule على الخيط الرئيسي أثناء وجود التطبيق في المقدمة. لا يوجد طلب وقت جدولة إلى Pushwoosh: يتعرف الخادم على النشاط بمجرد أن يبدأ بالفعل ويتلقى رمز الدفع الخاص به من خلال نفس مراقب الرمز الذي تم تثبيته بواسطة طريقة setup() (انظر أدناه).

إلغاء نشاط مباشر بواسطة معرف النشاط (Activity ID)

Anchor link to

استخدم cancel(_:activityId:) لإلغاء نشاط مباشر بواسطة معرف النشاط الخاص به دون الاحتفاظ بمرجع إلى مثيل Activity:

if #available(iOS 16.2, *) {
    Pushwoosh.LiveActivities.cancel(FoodDeliveryAttributes.self, activityId: "activity_id")
}

تنهي cancel النشاط على الجهاز على الفور وتخطر خادم Pushwoosh. هذا يختلف عن stopLiveActivity(activityId:)، الذي يخطر الخادم فقط ولا ينهي النشاط على الجهاز مباشرة. تعمل cancel أيضًا مع نشاط مباشر تم جدولته باستخدام schedule ولكنه لم يبدأ بعد — يتم إلغاؤه قبل أن يبدأ.

طريقة Setup()

Anchor link to

يبسط Pushwoosh نقل معرفات الأنشطة من خلال تقديم دالة PushwooshLiveActivities.setup، التي تتعامل مع دورة حياة النشاط المباشر بأكملها داخل التطبيق. تستمع هذه الدالة تلقائيًا إلى تحديثات رموز pushToStart و pushToUpdate. باستخدام هذه الطريقة، لم يعد التطبيق بحاجة إلى تتبع بدء الأنشطة المباشرة يدويًا أو إدارة تحديثات الرموز لتحديثات النشاط.

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

في AppDelegate، تأكد من استيراد PushwooshFramework و PushwooshLiveActivities واستدعاء طريقة setup من وحدة Pushwoosh.LiveActivities.

AppDelegate.swift

if #available(iOS 16.1, *) {
    Pushwoosh.LiveActivities.setup(FoodDeliveryAttributes.self)
}

FoodDeliveryAttributes

import WidgetKit
import SwiftUI
import ActivityKit
import PushwooshFramework
import PushwooshLiveActivities


struct FoodDeliveryAttributes: PushwooshLiveActivityAttributes {
    public struct ContentState: PushwooshLiveActivityContentState {
        var status: String
        var estimatedTime: String
        var emoji: String
        var pushwoosh: PushwooshLiveActivityContentStateData?
    }


    var orderNumber: String
    var pushwoosh: PushwooshLiveActivityAttributeData
}

FoodDeliveryAttributes: يتوافق هذا الهيكل مع بروتوكول PushwooshLiveActivityAttributes. يتم استخدامه لتحديد سمات النشاط المباشر داخل التطبيق.

دليل الترحيل

Anchor link to

بدءًا من الإصدار 6.8.0 من Pushwoosh iOS SDK، قمنا بتحديث بنية SDK. يتم الآن الوصول إلى طرق الأنشطة المباشرة من خلال وحدة PushwooshLiveActivities.

إذا كنت تستخدم إصدارًا من Pushwoosh iOS SDK أقدم من 6.8.0 وكنت تستدعي الطرق المذكورة أدناه، وقمت بالتحديث إلى الإصدار 6.8.0 أو أحدث، فيرجى ملاحظة التغييرات التالية:

static func setup<Attributes: PushwooshLiveActivityAttributes>(_ activityType: Attributes.Type)
static func defaultSetup()
static func defaultStart(_ activityId: String, attributes: [String: Any], content: [String: Any])

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

import PushwooshFramework
import PushwooshLiveActivities
Pushwoosh.LiveActivities.setup(FoodDeliveryAttributes.self)
Pushwoosh.LiveActivities.defaultSetup()
Pushwoosh.LiveActivities.defaultStart("activity_id",
                            attributes: ["key_attribute": "value_attribute"],
                            content: ["key_content": "value_content"])

لقد حافظنا أيضًا على دعم الطرق من خلال Pushwoosh.sharedInstance() كما هو موضح أدناه، ولكن يرجى ملاحظة أن هذه الطرق سيتم إيقافها في الإصدارات المستقبلية.

// Send Live Activity Push To Start Token to Pushwoosh
static func sendPushToStartLiveActivity(token: String)
static func sendPushToStartLiveActivity(token: String, completion: @escaping (Error?) -> Void)


// Start Live Activity Methods with Activity ID
static func startLiveActivity(token: String, activityId: String)
static func startLiveActivity(token: String, activityId: String, completion: @escaping (Error?) -> Void)


// Stop Live Activity Methods
static func stopLiveActivity()
static func stopLiveActivity(completion: @escaping (Error?) -> Void)


static func stopLiveActivity(activityId: String)
static func stopLiveActivity(activityId: String, completion: @escaping (Error?) -> Void)