스위프트의 라이브 활동

스위프트 브레이즈 SDK의 라이브 활동을 구현하는 방법을 알아보세요. 실시간 활동은 잠금 화면에 바로 표시되는 지속적인 대화형 알림으로, 사용자는 디바이스를 잠금 해제하지 않고도 동적인 실시간 업데이트를 받을 수 있습니다.

How it works

실시간 활동은 정적 정보와 업데이트하는 동적 정보의 조합으로 표시됩니다. 예를 들어 배송 상태 추적기를 제공하는 라이브 활동을 만들 수 있습니다. 이 라이브 활동에는 회사 이름이 정적 정보로 표시되며, 배송 기사가 목적지에 가까워질수록 업데이트되는 동적 ‘배송 시간’이 표시됩니다.

개발자는 Braze를 사용하여 라이브 활동 생애주기를 관리하고 Braze REST API를 호출하여 라이브 활동을 업데이트하며 가입한 모든 기기가 가능한 한 빨리 업데이트를 받도록 할 수 있습니다. 또한 Braze를 통해 라이브 활동을 관리하기 때문에 다른 메시징 채널(푸시 알림, 인앱 메시지, 콘텐츠 카드)과 함께 사용하여 채택을 유도할 수 있습니다.

시퀀스 다이어그램

• 라이브 활동 시퀀스 다이어그램

---
config:
  theme: mc
---
sequenceDiagram
  participant Server as Client Server
  participant Device as User Device
  participant App as iOS App / Braze SDK
  participant BrazeAPI as Braze API
  participant APNS as Apple Push Notification Service
  Note over Server, APNS: Launch Option 1<br/>Locally Start Activities
  App ->> App: Register a Live Activity using <br>`launchActivity(pushTokenTag:activity:)`
  App ->> App: Get push token from iOS
  App ->> BrazeAPI: Activity ID & Push token<br>automatically sent to Braze
  Note over Server, APNS: Launch Option 2<br/>Remotely Start Activities
  Device ->> App: Call `registerPushToStart`<br>to collect push tokens early
  App ->> BrazeAPI: Push-to-start tokens sent to Braze
  Server ->> BrazeAPI: POST /messages/live_activity/start
  Note right of BrazeAPI: Payload includes:<br>- push_token<br>- activity_id<br>- external_id<br>- event_name<br>- content_state (optional)
  BrazeAPI ->> APNS: Live activity start request
  APNS ->> Device: APNS sends activity to device
  App ->> App: Get push token from iOS
  App ->> BrazeAPI: Activity ID & Push token<br>automatically sent to Braze
  Note over Server, APNS: Resuming activities upon app launch
  App ->> App: Call `resumeActivities(ofType:)` on each app launch
  Note over Server, APNS: Updating a Live Activity
  loop update a live activity
  Server ->> BrazeAPI: POST /messages/live_activity/update
  Note right of BrazeAPI: Payload includes changes<br>to ContentState (dynamic variables)
  BrazeAPI ->> APNS: Update sent to APNS
  APNS ->> Device: APNS sends update to device
  end
  Note over Server, APNS: Ending a Live Activity
  Server ->> BrazeAPI: POST /messages/live_activity/update
  Note right of BrazeAPI: Activity can be ended via:<br> - User manually dismisses<br>- Times out after 12 hours<br>- `dismissal_date` is now in the past<br>- Setting `end_activity: true`
  APNS ->> Device: Live activity is dismissed

라이브 활동 구현

Prerequisites

이 기능을 사용하려면 먼저 Swift Braze SDK를 통합해야 합니다. 또한 다음을 완료해야 합니다:

• 프로젝트가 iOS 16.1 이상을 대상으로 하는지 확인하세요.
• Xcode 프로젝트의 서명 및 기능 아래에 Push Notification 권한을 추가합니다.
• .p8 키가 알림을 보내는 데 사용되는지 확인합니다. .p12 또는 .pem 같은 이전 파일은 지원되지 않습니다.
• Braze Swift SDK 버전 8.2.0부터 라이브 활동을 원격으로 등록할 수 있습니다. 이 기능을 사용하려면 iOS 17.2 이상이 필요합니다.

1단계: 활동 만들기

먼저, iOS 애플리케이션에서 라이브 활동을 설정하려면 Apple 설명서의 라이브 활동으로 라이브 데이터 표시를 따라야 합니다. 이 작업의 일환으로 Info.plist에서 YES로 설정된 NSSupportsLiveActivities를 포함해야 합니다.

라이브 활동의 정확한 성격은 비즈니스 사례에 따라 다르므로 활동 개체를 설정하고 초기화해야 합니다. 또한 다음을 정의해야 합니다.

• ActivityAttributes: 이 프로토콜은 라이브 활동에 표시되는 정적(변경되지 않음) 및 동적(변경됨) 콘텐츠를 정의합니다.
• ActivityAttributes.ContentState: 이 유형은 활동이 진행되는 동안 업데이트될 동적 데이터를 정의합니다.

또한 SwiftUI를 사용하여 지원되는 기기에서 잠금 화면과 Dynamic Island의 UI 프레젠테이션을 생성할 수 있습니다.

이러한 제약 조건은 Braze와는 별개이므로 라이브 활동에 대한 Apple의 전제 조건 및 제한 사항을 숙지하고 있어야 합니다.

예시

Superb Owl 프로그램에 대한 사용자 업데이트를 제공하는 라이브 활동을 생성한다고 가정합니다. 이 프로그램에서는 서로 경쟁하는 두 명의 야생동물 구조대원에게 각자 데리고 있는 올빼미에 대한 점수를 부여합니다. 이 예제에서는 SportsActivityAttributes라는 구조를 생성했지만 ActivityAttributes를 직접 구현하여 사용할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#if canImport(ActivityKit)
  import ActivityKit
#endif

@available(iOS 16.1, *)
struct SportsActivityAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String
}

2단계: 활동 시작

먼저, 활동을 등록하는 방법을 선택합니다:

• 원격: 사용 registerPushToStart 메서드를 사용하여 사용자 라이프사이클 초기에 푸시-투-스타트 토큰이 필요하기 전에 활동을 시작한 다음 /messages/live_activity/start 엔드포인트를 사용하여 활동을 시작하세요.
• 로컬: 라이브 활동의 인스턴스를 생성한 다음, 브레이즈가 관리할 푸시 토큰을 생성하려면 launchActivity 메서드를 사용하여 Braze가 관리할 푸시 토큰을 생성합니다.

• remote
• local

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

@available(iOS 16.1, *)
// 1. Add the `BrazeLiveActivityAttributes` conformance to your `ActivityAttributes` struct.
struct SportsActivityAttributes: ActivityAttributes, BrazeLiveActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String

  // 2. Add the `String?` property to represent the activity ID.
  var brazeActivityId: String?
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

class LiveActivityManager {

  @available(iOS 17.2, *)
  func registerActivityType() {
    // This method returns a Swift background task.
    // You may keep a reference to this task if you need to cancel it wherever appropriate, or ignore the return value if you wish.
    let pushToStartObserver: Task = Self.braze?.liveActivities.registerPushToStart(
      forType: Activity<SportsActivityAttributes>.self,
      name: "SportsActivityAttributes"
    )
  }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

class LiveActivityManager {
  
  @available(iOS 16.2, *)
  func createActivity() {
    let activityAttributes = SportsActivityAttributes(gameName: "Superb Owl", gameNumber: "Game 1")
    let contentState = SportsActivityAttributes.ContentState(teamOneScore: "0", teamTwoScore: "0")
    let activityContent = ActivityContent(state: contentState, staleDate: nil)
    if let activity = try? Activity.request(attributes: activityAttributes,
                                            content: activityContent,
      // Setting your pushType as .token allows the Activity to generate push tokens for the server to watch.
                                            pushType: .token) {
      // Register your Live Activity with Braze using the pushTokenTag.
      // This method returns a Swift background task.
      // You may keep a reference to this task if you need to cancel it wherever appropriate, or ignore the return value if you wish.
      let liveActivityObserver: Task = AppDelegate.braze?.liveActivities.launchActivity(pushTokenTag: "sports-game-2024-03-15",
                                                                                        activity: activity)
    }
  }
  
}

3단계: 활동 추적 재개

앱 실행 시 Braze가 라이브 활동을 추적하게 하려면 다음을 수행합니다.

1. AppDelegate 파일을 엽니다.
2. ActivityKit 모듈을 사용할 수 있는 경우 가져옵니다.
3. 전화 resumeActivities(ofType:) 에서 application(_:didFinishLaunchingWithOptions:) 으로 전화하여 신청서에 등록한 모든 ActivityAttributes 유형에 대해 문의하세요.

이를 통해 Braze는 모든 활성 라이브 활동에 대한 푸시 토큰 업데이트를 추적하는 작업을 재개할 수 있습니다. 사용자가 자신의 기기에서 라이브 활동을 명시적으로 삭제한 경우, 해당 활동은 제거된 것으로 간주되며 Braze는 더 이상 해당 활동을 추적하지 않습니다.

예시

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import UIKit
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

  static var braze: Braze? = nil

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    
    if #available(iOS 16.1, *) {
      Self.braze?.liveActivities.resumeActivities(
        ofType: Activity<SportsActivityAttributes>.self
      )
    }

    return true
  }
}

4단계: 활동 업데이트

/messages/live_activity/update 엔드포인트에서는 Braze REST API를 통해 전달되는 푸시 알림으로 라이브 활동을 업데이트할 수 있습니다. 이 엔드포인트를 사용하여 라이브 활동의 ContentState 을 업데이트합니다.

ContentState 을 업데이트하면 실시간 활동 위젯에 새 정보가 표시됩니다. 다음은 전반전이 끝난 후 Superb Owl 프로그램의 현황입니다.

자세한 내용은 /messages/live_activity/update 엔드포인트 문서를 참조하세요.

5단계: 활동 종료

라이브 활동이 활성화되면 사용자의 잠금 화면과 Dynamic Island에 모두 표시됩니다. 라이브 활동을 종료하고 사용자 UI에서 제거하는 몇 가지 방법이 있습니다.

• 사용자 해고: 사용자는 수동으로 실시간 활동을 해제할 수 있습니다.
• 제한 시간: 기본 시간(8시간)이 지나면 iOS는 사용자의 Dynamic Island에서 라이브 활동을 제거합니다. 기본 시간(12시간)이 지나면 iOS는 사용자의 잠금 화면에서 라이브 활동을 제거합니다.
• 해제 날짜: 제한 시간 이전에 사용자의 UI에서 라이브 활동을 제거할 날짜 및 시간을 지정할 수 있습니다. 활동의 /messages/live_activity/update 엔드포인트에 대한 요청에서 dismissal_date 매개변수를 사용하거나 활동의 ActivityUIDismissalPolicy에서 정의합니다.
• 활동 종료: /messages/live_activity/update 엔드포인트에 대한 요청에서 end_activity를 true로 설정하여 라이브 활동을 즉시 종료할 수 있습니다.

자세한 내용은 /messages/live_activity/update 엔드포인트 문서를 참조하세요.

자주 묻는 질문(FAQ)

기능 및 지원

어떤 플랫폼에서 라이브 활동을 지원하나요?

라이브 활동은 현재 iOS에만 적용되는 기능입니다. 라이브 활동 문서에서는 Braze Swift SDK를 통해 라이브 활동을 관리하기 위한 전제 조건을 다룹니다.

React Native 앱이 라이브 활동을 지원하나요?

예. React Native SDK 3.0.0 이상에서 Braze Swift SDK를 통해 라이브 활동을 지원합니다. 즉, Braze Swift SDK에 직접 React Native iOS 코드를 작성해야 합니다.

Apple에서 제공하는 라이브 활동 기능은 JavaScript로 변환할 수 없는 언어(예: Swift 동시성, 제네릭, SwiftUI)를 사용하기 때문에 라이브 활동을 위한 React Native 전용 JavaScript 편의 API가 없습니다.

Braze는 캠페인 또는 캔버스 단계로 라이브 활동을 지원하나요?

아니요, 현재 이 기능은 지원되지 않습니다.

푸시 알림 및 실시간 활동

실시간 활동이 활성화되어 있는 동안 푸시 알림이 전송되면 어떻게 되나요?

실시간 활동과 푸시 알림은 서로 다른 화면 공간을 차지하며 사용자 화면에서 충돌하지 않습니다.

라이브 활동이 푸시 메시지 기능을 활용하는 경우, 라이브 활동을 수신하려면 푸시 알림을 사용 설정해야 하나요?

라이브 활동은 푸시 알림을 통해 업데이트를 받지만, 다른 사용자 설정에 의해 제어됩니다. 사용자는 라이브 활동을 옵트인할 수 있지만 푸시 알림을 옵트아웃할 수 있습니다. 반대의 경우도 마찬가지입니다.

실시간 활동 업데이트 토큰은 8시간 후에 만료됩니다.

라이브 활동에 푸시 프라이머가 필요한가요?

푸시 프라이머는 사용자가 앱에서 푸시 알림을 옵트인하라는 프롬프트를 표시하는 모범 사례입니다. 그러나 라이브 활동을 선택하라는 시스템 프롬프트는 표시되지 않습니다. 기본적으로 사용자는 iOS 16.1 이상에서 해당 앱을 설치할 때 개별 앱의 실시간 활동에 옵트인합니다. 이 권한은 앱별로 디바이스 설정에서 비활성화하거나 다시 활성화할 수 있습니다.

기술 주제 및 문제 해결

실시간 활동에 오류가 있는지 어떻게 알 수 있나요?

모든 라이브 활동 오류는 Braze 대시보드의 메시지 활동 로그에 기록됩니다. 이는 ‘LiveActivity 오류’를 기준으로 필터링할 수 있습니다.

푸시 시작 알림을 보낸 후에도 내 실시간 활동을 받지 못한 이유는 무엇인가요?

먼저 페이로드에 엔드포인트에 설명된 모든 필수 필드가 포함되어 있는지 확인합니다. messages/live_activity/start 엔드포인트에 설명된 모든 필수 필드가 포함되어 있는지 확인합니다. activity_attributes 및 content_state 필드는 프로젝트 코드에 정의된 속성과 일치해야 합니다. 페이로드가 정확하다고 확신하는 경우, APN에 의해 속도 제한이 적용될 수 있습니다. 이 제한은 Braze가 아닌 Apple에서 부과합니다.

푸시 투 스타트 알림이 장치에 성공적으로 도착했지만 속도 제한으로 인해 표시되지 않았는지 확인하려면 Mac의 콘솔 앱을 사용하여 프로젝트를 디버그할 수 있습니다. 원하는 디바이스의 기록 프로세스를 첨부한 다음 검색창에서 process:liveactivitiesd 으로 로그를 필터링합니다.

푸시 투 스타트로 라이브 활동을 시작한 후 새 업데이트가 수신되지 않는 이유는 무엇인가요?

위에서 설명한 지침을 올바르게 구현했는지 확인합니다. ActivityAttributes 에는 BrazeLiveActivityAttributes 프로토콜 준수와 brazeActivityId 속성이 모두 포함되어야 합니다.

라이브 활동 푸시-투-스타트 알림을 받은 후, Braze URL의 /push_token_tag 엔드포인트로 나가는 네트워크 요청이 표시되는지, "tag" 필드 아래에 올바른 활동 ID가 포함되어 있는지 다시 한 번 확인합니다.

live_activity/update 엔드포인트를 사용하려고 할 때 액세스 거부됨 응답을 받습니다. 왜인가요?

사용하는 API 키에 올바른 권한을 부여해야 다양한 Braze API 엔드포인트에 액세스할 수 있습니다. 이전에 생성한 API 키를 사용하는 경우 해당 권한을 업데이트하지 않았을 수 있습니다. API 키 보안 개요를 다시 한 번 살펴보세요.

messages/send 엔드포인트는 messages/live_activity/update 엔드포인트와 공유 비율을 제한하나요?

기본적으로 messages/live_activity/update 엔드포인트의 사용량 제한은 여러 엔드포인트에 걸쳐 워크스페이스당 매시간 250,000건의 요청입니다. 자세한 내용은 API 요금 한도를 참조하세요.