iOS Live Activities

Live Activities отображают самые актуальные данные вашего приложения на экране блокировки iPhone или iPad и в Dynamic Island. Эта функция позволяет пользователям мгновенно просматривать актуальную информацию и выполнять быстрые действия, связанные с отображаемыми данными.

Вот несколько примеров использования Live Activities:

• Отображение статуса заказа в приложении доставки;
• Предоставление обратного отсчета в реальном времени в приложении для тренировок;
• Отображение информации об отслеживании в приложении такси;
• Отображение игровой статистики и текущих результатов в спортивном приложении;
• Предоставление почасовых прогнозов в погодном приложении.

Вы можете включить Live Activities с помощью Wavesend iOS SDK, как описано ниже. Для управления Live Activities и обновления их контента используйте метод /updateLiveActivity.

Настройка

Важно

Live Activities в Wavesend поддерживают только конфигурацию на основе токенов. Конфигурация на основе сертификатов не поддерживается.

Добавьте Widget Extension

1. Создайте новый target

Перейдите в File > New > Target и выберите Widget Extension.

2. Конфигурация Widget Extension Введите название, обязательно выберите Include Live Activity и нажмите Finish.

Конфигурация Info.plist

Найдите файл Info.plist в основном target, вставьте ключ “Supports Live Activities” и установите его значение на YES.

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

Включение Live Activities из приложения

Чтобы включить Live Activities, добавьте их код в существующее расширение виджета или создайте новое, если в вашем приложении его еще нет. Live Activities используют функциональность SwiftUI и WidgetKit для своего пользовательского интерфейса. ActivityKit управляет жизненным циклом каждого Live Activity: его API используется для запроса, обновления и завершения Live Activity, а также для получения push-уведомлений ActivityKit. Вы можете узнать больше о Live Activities в документации 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()
}

2. Создайте файл LiveActivityManager.swift для управления Live Activities

import Foundation
import ActivityKit
import UIKit
import WavesendFramework
import WavesendLiveActivities

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 wavesendData = WavesendLiveActivityAttributeData(activityId: "activity_id")
            let atttribute = FoodDeliveryAttributes(orderNumber: "1234567", wavesend: wavesendData)
            let initialState = FoodDeliveryAttributes.ContentState(
                status: "Preparing your meal",
                estimatedTime: "25 min",
                emoji: "👨‍🍳",
                wavesend: 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 Wavesend
                    Wavesend.LiveActivities.startLiveActivity(
                        token: pushTokenString,
                        activityId: "activity_id"
                    )
                }
            }
        } catch {
            print("Start Activity Error: \(error.localizedDescription)")
        }
    }
}

3. Вот и все, теперь мы запускаем проект и нажимаем кнопку ‘Start Live Activity’. Затем переходим на экран блокировки и видим созданный Live Activity.

Запуск Live Activity с помощью удаленного push-уведомления

1. Чтобы инициировать Live Activity через удаленное push-уведомление, вам необходимо отправить токен pushToStartTokenUpdates в Wavesend.

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 Wavesend
                try await Wavesend.LiveActivities.sendPushToStartLiveActivity(token: token)
            }
        }
    }
}

2. Инициируйте Live Activity с помощью удаленного push-уведомления

Tip

Следуйте нашей документации по API Wavesend для получения инструкций и примеров по созданию запроса для удаленного запуска Live Activity.

Управление Live Activities

Wavesend iOS SDK предоставляет следующие методы для работы с Live Activities:

// Send Live Activity Push To Start Token to Wavesend
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)

Вы также можете обновлять live activities по сегментам, используя параметр Activity ID. При создании activity вам необходимо передать в метод уникальный параметр Activity ID, который будет релевантен для определенного сегмента пользователей.

Например, N пользователей подписались на одно и то же событие в live Activity. Необходимо, чтобы параметр Activity ID был уникальным для всех этих N пользователей.

Когда вы закончите работу с Live Activity, используйте эти методы:

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

Note

Вы можете управлять iOS Live Activities через API Wavesend.

Метод Setup()

Wavesend упрощает передачу ID activity, представляя функцию WavesendLiveActivities.setup, которая обрабатывает весь жизненный цикл Live Activity в приложении. Эта функция автоматически прослушивает обновления токенов как pushToStart, так и pushToUpdate. Используя этот метод, приложению больше не нужно вручную отслеживать запуск Live Activities или управлять обновлениями токенов для обновлений activity.

Мы рекомендуем использовать этот метод, поскольку он берет на себя все управление токенами, что уменьшает количество кода, которое вам нужно поддерживать. Это упрощает интеграцию и обеспечивает более плавную и эффективную работу вашего приложения.

В AppDelegate убедитесь, что вы импортировали WavesendFramework и WavesendLiveActivities и вызвали метод setup из модуля Wavesend.LiveActivities.

AppDelegate.swift

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

FoodDeliveryAttributes

import WidgetKit
import SwiftUI
import ActivityKit
import WavesendFramework
import WavesendLiveActivities

struct FoodDeliveryAttributes: WavesendLiveActivityAttributes {
    public struct ContentState: WavesendLiveActivityContentState {
        var status: String
        var estimatedTime: String
        var emoji: String
        var wavesend: WavesendLiveActivityContentStateData?
    }

    var orderNumber: String
    var wavesend: WavesendLiveActivityAttributeData
}

FoodDeliveryAttributes: Эта структура соответствует протоколу WavesendLiveActivityAttributes. Она используется для определения атрибутов live activity в приложении.

Note

Вы можете управлять Live Activities и обновлять их контент, используя метод /updateLiveActivity API Wavesend. Для получения дополнительной информации, пожалуйста, прочтите это руководство

Руководство по миграции

Начиная с версии 6.8.0 Wavesend iOS SDK, мы обновили структуру SDK. Теперь доступ к методам Live Activities осуществляется через модуль WavesendLiveActivities.

Если вы использовали версию Wavesend iOS SDK ранее 6.8.0, вызывали перечисленные ниже методы и обновились до версии 6.8.0 или более поздней, обратите внимание на следующие изменения:

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

Теперь для доступа к этим методам следует использовать модуль LiveActivity.

import WavesendFramework
import WavesendLiveActivities

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

Мы также сохранили поддержку методов через Wavesend.sharedInstance(), как указано ниже, но обратите внимание, что эти методы будут объявлены устаревшими в будущих релизах.

// Send Live Activity Push To Start Token to Wavesend
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)