Live Activity

Live Activity는 실시간으로 업데이트되는 카드로, 사용자가 앱을 열지 않고도 진행 상황(항공편 상태, 배송, 이동 등)을 볼 수 있습니다. iOS에서는 잠금 화면과 Dynamic Island에 표시되는 작은 카드입니다. Android 16 이상에서는 같은 종류의 카드가 진행률 표시줄이 있는 진행 중 알림으로 표시됩니다.

journey에서 Live Activity 요소를 사용하여 iOS, Android 또는 둘 다에서 해당 카드를 시작, 업데이트 또는 종료하세요.

각 요소는 하나의 작업을 수행합니다:

• Start: 카드를 생성합니다.
• Update: 기존 카드를 변경합니다.
• End: 카드를 닫습니다.

나중에 동일한 카드를 변경하거나 닫으려면 Live Activity 요소를 하나 더 추가하고 Card created by로 카드를 생성한 요소를 다시 가리키세요.

사용 사례 예시

사용자가 앱을 열지 않고도 계속 변하는 상태를 봐야 할 때마다 이 요소를 사용하세요.

• 항공편 상태: 체크인 후 카드를 표시합니다. 비행 중 게이트, 상태, 시간을 최신 상태로 유지합니다. 착륙 후 카드를 제거합니다.
• 음식 배달: 주문 시 카드를 표시합니다. 배달 중 배달원 이름, 도착 예정 시간, 거리를 최신 상태로 유지합니다. 배달 완료 시 카드를 제거합니다.
• 차량 호출: 이동을 요청할 때 카드를 표시합니다. 기사가 접근하는 동안 기사, 도착 예정 시간, 차량 번호를 최신 상태로 유지합니다. 이동이 완료되면 카드를 제거합니다.
• 주문 또는 예약: 주문 또는 예약이 확인되면 카드를 표시합니다. 진행됨에 따라 상태를 최신 상태로 유지합니다. 완료되거나 방문이 끝나면 카드를 제거합니다.
• 라이브 이벤트: 이벤트가 시작되면 카드를 표시합니다. 진행되는 동안 점수, 기간, 일정을 최신 상태로 유지합니다. 이벤트가 끝나면 카드를 제거합니다.

팁

전체 journey 예시는 잠금 화면에 항공편 상태를 표시하는 방법 및 잠금 화면에 배송 진행 상황을 표시하는 방법을 참조하세요.

전제 조건

이 요소를 설정하기 전에 각 플랫폼에 필요한 사항을 확인하세요.

iOS 카드의 경우:

• iOS Live Activity 지원: 앱이 Live Activities를 지원해야 합니다. iOS SDK Live Activities 가이드를 참조하세요.
• 게시된 위젯 스키마: 개발팀에 Applications → Configure → Live Activity schemas에서 앱의 Live Activity 유형과 일치하는 스키마를 게시하도록 요청하세요. API를 통해 게시할 수도 있습니다. 스키마에 포함되어야 할 내용은 스키마 작성을 참조하세요.
• 목록의 위젯: 스키마가 게시된 후, 이 요소의 Widget에서 선택하세요. Widget 목록이 비어 있으면 스키마가 아직 게시되지 않은 것입니다.

Android 알림의 경우:

• Android Live Updates 지원: 앱에 SDK 6.11+ 및 pushwoosh-liveupdates 모듈이 필요합니다. Android에는 스키마가 필요하지 않습니다. Android 개발자에게 모듈이 빌드에 포함되어 있는지 확인을 요청하세요.

요소 설정

1. Live Activity 요소를 캔버스로 드래그합니다.

   

2. 요소를 더블클릭하여 설정을 엽니다.

3. Step name에 이름을 입력합니다.

4. Action에서 다음 중 하나를 선택합니다:

   • Start: Live Activity 카드를 생성합니다.
   • Update: 기존 카드의 내용을 변경합니다.
   • End: 카드를 닫습니다.

5. Platforms에서 iOS Live Activity, Android Live Updates 또는 둘 다를 켭니다. 최소 하나의 플랫폼은 켜져 있어야 하므로 마지막 플랫폼은 끌 수 없습니다. Update 및 End에서 Platforms는 연결된 Start 요소의 플랫폼을 표시하며 읽기 전용입니다.

   

6. Start에서만 카드 키를 설정하여 이후의 Update 및 End 단계가 이 카드를 찾을 수 있도록 합니다:

   • Card key: event에서 카드를 식별하는 이벤트(예: journey 진입 이벤트)를 선택합니다.
   • Card key: attribute에서 키를 여행자별로 고유하게 만드는 속성을 선택합니다. Card key: event를 설정하면 이 항목은 필수가 됩니다. 설정하지 않으면 이벤트 선택은 효과가 없으며, 두 필드를 모두 비워둔 것과 동일합니다: 여행자당 하나의 카드가 기본 사용자 ID로 주소가 지정됩니다.

   

Update와 End를 올바른 카드에 연결

Action이 Update 또는 End인 경우, Card created by를 사용하여 이 카드를 생성한 정확한 Start 요소를 가리키세요. 그렇지 않으면 Update 또는 End가 해당 카드에 도달하지 못합니다.

1. Card created by에서 해당 Start 요소의 Step name(예: Order card start)을 선택합니다.

Card created by를 선택하면 **Card key (from the start element)**에 해당 Start의 Card key: event 및 Card key: attribute 값이 표시됩니다. 읽기 전용이며 이것이 가리키는 카드를 확인해 줍니다.

참고

예시: Start의 이름은 Order card start입니다. Update 및 End에서 Card created by에 Order card start를 선택하세요. 그러면 두 단계 모두 동일한 주문 카드를 변경하거나 닫습니다.

카드 언어 선택

Card language는 iOS 카드와 Android 알림 모두에 적용됩니다.

Card language를 default 또는 특정 언어 코드로 설정합니다. default 아래의 콘텐츠는 별도로 입력하지 않은 모든 언어에 대한 대체 항목입니다.

iOS 카드 설정

Android Live Updates만 켜져 있으면 이 섹션을 건너뛰세요.

위젯 및 스키마 버전 선택

1. Widget에서 이 카드에 대해 게시된 Live Activity 유형을 선택합니다. 아래의 콘텐츠 필드는 이 선택에 따라 결정됩니다. Update 또는 End에서 Widget은 읽기 전용이며 Card created by 요소로부터 상속됩니다.

2. Schema version에서 해당 위젯 스키마의 게시된 버전 중 사용할 버전을 선택합니다. Card content 필드는 이 버전에서 가져옵니다. Update 및 End에서 Schema version은 여전히 선택 가능합니다. 연결된 Start가 사용한 것과 다른, 동일하게 상속된 위젯의 게시된 버전을 선택할 수 있습니다.

   

카드의 고정 속성 설정(Start 전용)

Start에서 Card attributes 아래에, 항공편 번호나 주문 ID처럼 카드의 전체 수명 동안 고정되어 한 번 설정되고 다시는 변경되지 않는 필드를 추가하세요. 이는 아래의 Card content 필드와는 별개입니다. 그 값들은 Update에서 변경될 수 있습니다.

정확한 Field name 목록을 iOS 개발자에게 문의하세요. 이 이름들은 카드의 전체 수명 동안 고정됩니다(앱의 ActivityAttributes). 변경되는 Card content 이름(앱의 ContentState)은 사용하지 마세요.

1. Add attribute를 클릭합니다.
2. 필요한 각 속성에 대해 Field name과 Value를 설정합니다.

Update와 End는 속성을 설정하지 않습니다. 이 카드에 대해 Start가 설정한 내용은 고정된 상태로 유지됩니다.

주의

카드 속성은 앱의 ActivityAttributes 타입이 예상하는 대로 필드별로 정확히 전송됩니다. 이름을 잘못 입력하거나 비워두면 기기의 디코더가 전체 페이로드를 거부합니다. 실제 테스트에서 flightNumber가 있는 Start는 카드를 열었지만, 속성이 없는 Start는 잠금 화면에 표시할 내용 없이 봉투만 전달했습니다.

카드 콘텐츠 입력

Card content 아래에서 각 필드에 리터럴 값 또는 개인화 자리 표시자를 입력합니다. 선택한 스키마 버전의 각 속성마다 하나의 필드가 나타납니다.

Update 및 End의 사전 입력

Update 또는 End에서 현재 Card language에 대한 Card content가 비어 있는 경우(방금 추가한 언어 포함), 설정을 열면 Pushwoosh가 연결된 Start 요소로부터 필드를 미리 채웁니다:

• 해당 언어에 콘텐츠가 있는 경우 Start와 동일한 언어.
• 그렇지 않으면 Start의 default 콘텐츠.
• Start에 둘 다 없으면 필드를 비워 두고 직접 입력하세요.

미리 채워진 값은 편집 가능한 상태로 유지됩니다. 편집 내용을 유지하고 싶을 때만 Apply를 클릭하세요. 요소를 여는 것만으로는 실행 중인 journey가 변경되지 않습니다.

Update 또는 End에서 비워 둔 필드는 전송되지 않습니다. 그 필드에 카드가 무엇을 표시할지는 앱에 달려 있습니다. 이전 값을 유지하거나, 지우거나, 다른 동작을 할 수 있습니다. 앱이 이를 어떻게 처리하는지 개발팀에 문의하세요.

End에서 Card content는 선택 사항입니다. 입력한 필드는 카드가 닫히기 전에 표시되는 마지막 값이 됩니다.

전송 우선순위 및 타이밍 설정

1. Delivery priority에서 iOS가 이 업데이트를 언제 전달해야 하는지 선택합니다:

   • Immediate: iOS가 즉시 전달하며 전화를 깨울 수 있습니다(소리를 설정한 경우 재생도 함).
   • Quiet: iOS가 다른 업데이트와 함께 나중에 전달할 수 있으며 즉시 전화를 깨우지 않습니다.
   • Default (batched): iOS가 자체 기본 일괄 전달을 사용하며 즉시 전화를 깨우지 않습니다.

2. Sound에서 목록의 소리를 선택합니다. 개발팀이 iOS 앱 번들에 소리 파일을 추가합니다. 사용자 지정 push 소리를 참조하세요. 소리는 배너와 마찬가지로 Alert title 또는 Alert text와 함께일 때만 재생됩니다.

3. 이 요소에 설정한 Action(Start, Update, End)에 따라 다음 중 하나를 입력합니다:

   • Start 또는 Update: 카드의 데이터가 신선해 보여야 하는 시간을 분 단위로 Stale after, min에 설정합니다. 그 시간이 끝나면 iOS는 숫자를 오래된 것으로 흐리게 표시합니다. 카드는 잠금 화면에 남아 있습니다. 숫자가 계속 최신으로 보이게 하려면 시간이 끝나기 전에 다른 Update를 보내세요.
   • End: iOS가 제거하기 전까지 닫힌 카드가 잠금 화면에 남아 있는 시간을 Dismiss after, min에 설정합니다. 0으로 두면 iOS가 최대 4시간 이내에 자체적으로 제거할 때까지 카드가 최종 Card content를 계속 표시합니다.

4. 선택적으로 Relevance score를 1에서 100 사이의 숫자로 설정합니다. 한 사람이 동시에 앱에서 둘 이상의 활성 Live Activity를 가지고 있을 때, iOS는 점수가 더 높은 것을 먼저 표시합니다. 선호도를 설정하지 않으려면 0으로 두세요. Pushwoosh는 0 점수를 Apple에 전혀 전송하지 않습니다. 전체 내용은 기기당 여러 활동을 참조하세요.

Android 알림 입력

Android 알림의 제목, 텍스트, 진행률 표시줄, 헤더 시간을 입력합니다. 이 섹션은 Android Live Updates가 켜져 있을 때만 나타납니다. iOS 카드와 동일한 Card language를 사용합니다.

1. Android용으로 입력하는 모든 언어에 대해 Notification title을 설정합니다. Start 및 Update에서는 해당 언어마다 제목이 있어야 journey를 실행할 수 있습니다. 제목이 없는 언어는 양식에 알림 메시지가 표시됩니다.

2. Notification text를 설정합니다.

   

3. 진행률 표시줄을 설정합니다:

   • Progress: 표시줄이 위치할 지점을 세그먼트 길이와 같은 단위로, 숫자 또는 {name} 형식의 자리 표시자(선택적으로 {name|format} 또는 {name|format|default})로 입력합니다.
   • Segments: 표시줄의 색상 구간마다 Add segment를 클릭하고, 각 구간에 16진수 Color(#RRGGBB 또는 #AARRGGBB)와 Length를 설정합니다. 세그먼트 길이의 합이 전체 표시줄이 됩니다.
   • Animate the bar without a known end: 켜면 Progress 값 대신 움직이는 표시줄을 보여줍니다.
   • Hide the progress bar: 켜면 표시줄 없이 카드를 보여줍니다.

   

4. 헤더 시간을 설정합니다:

   • Header time: 카드 헤더 시계가 표시할 시점을 초 단위(밀리초 아님) Unix 타임스탬프 또는 자리 표시자로 입력합니다. 예를 들어 1735689600은 2025-01-01 00:00 UTC를 의미합니다. 이 항목과 Header time after, min이 모두 설정되면 Header time이 사용됩니다.
   • Header time after, min: 전송 후 몇 분 뒤의 시간을 헤더에 표시할지 설정합니다.
   • Run the header time as a timer: 켜면 Header time을 고정 값 대신 흐르는 시계로 표시합니다. 이 옵션을 켜면 Count down to the header time이 나타납니다.
   • Count down to the header time: 켜면 전송 시점부터 카운트업하는 대신 Header time까지 카운트다운합니다.
   • Hide the header time: 켜면 헤더 시간 없이 카드를 보여줍니다.

   

위의 모든 필드에는 자리 표시자를 넣을 수 있으며, iOS Card content 필드와 같은 방식으로 journey 이벤트에서 또는 이벤트 속성으로 개인화하여 값이 채워집니다.

일부 Android 기기에서는 알림이 표시되지 않습니다

• Android 15 이하 또는 pushwoosh-liveupdates 모듈이 없는 앱: Pushwoosh는 업데이트를 전송하지만 기기에는 아무것도 나타나지 않으며, 대신 일반 push가 표시되지도 않습니다.
• Huawei 및 Baidu 기기: Android Live Updates를 받지 않습니다. 업데이트는 Firebase Cloud Messaging(FCM)을 통해 등록된 기기에만 전송됩니다.

알림을 탭하면 일반 push와 마찬가지로 앱이 열립니다.

알림 배너 설정

이 섹션은 iOS Live Activity가 켜져 있을 때만 적용됩니다. Android Live Updates만 켜져 있으면 이 필드는 숨겨지며 아무것도 전송되지 않습니다.

세 가지 작업(Start, Update, End) 모두에 대해:

1. Alert title에서 잠금 화면에 표시되는 배너 제목을 설정합니다.
2. Alert text에서 배너 텍스트를 설정합니다.

주의

Alert title과 Alert text가 모두 비어 있으면 카드는 여전히 시작, 업데이트, 종료되지만 잠금 화면에는 배너가 표시되지 않고 소리도 재생되지 않습니다. 이 작업이 잠긴 화면에 나타나야 할 때는 둘 중 최소 하나를 입력하세요.

카드를 받을 기기 선택

주소 지정은 Start에서 한 번 설정됩니다. 두 스위치를 모두 꺼두면 여행자가 journey에 진입한 기기로 카드가 전송됩니다. 한 스위치를 켜면 다른 스위치는 꺼집니다:

• Send to all devices of this user: 진입에 사용한 기기뿐만 아니라 해당 여행자의 User ID로 등록된 모든 기기로 전송합니다.
• Send to the last active device only: 모든 기기나 진입 기기 대신, 해당 User ID가 가장 최근에 사용한 단일 기기로 전송합니다.

팁

동일한 사람이 journey에 진입한 iPhone과 다른 iPhone에서 보고 있을 수 있는 경우 Send to the last active device only를 켜세요.

Update 및 End에서는 **Delivery (from the start element)**를 확인하세요. 이는 연결된 Start의 주소 지정 모드를 나타냅니다. 업데이트는 동일한 카드에만 도달할 수 있으므로 동일한 방식으로 전송됩니다.

참고

journey가 실행되기 시작하면 두 스위치 모두 즉시 잠기며, 이는 Start에서도 마찬가지입니다. 이후에 주소 지정을 변경하려면 먼저 journey를 일시 중지하세요.

콘텐츠 개인화

Alert title, Alert text, Card content 또는 Android의 Notification title, Notification text, Progress, Header time의 자리 표시자가 기기 태그가 아닌 journey 이벤트 또는 API 기반 진입에서 값을 가져와야 할 때 이를 사용하세요.

1. Overwrite personalization 아래에서 Personalise message with event attributes를 켭니다.
2. 다시 매핑하려는 각 자리 표시자 옆의 Overwrite placeholder 상자를 선택합니다.
3. 해당 자리 표시자를 이벤트 속성에 매핑합니다.

요소 저장

Apply를 클릭하여 요소 설정을 저장합니다. Apply는 이 요소를 journey에 저장합니다. 카드가 기기에 나타났는지는 확인해 주지 않습니다. journey가 실행된 후, 이 단계에서 Total entries와 이탈을 확인하고, 켠 플랫폼에 따라 테스트용 iPhone, Android 16 이상 테스트 기기 또는 둘 다에서 카드를 확인하세요.

제한 사항

• 요소 통계: 이 단계에서 Total entries, Delivery 행(주소 지정 모드), 이탈(No recipient for the card, Live Activity send failed)을 확인하세요. No recipient for the card는 해당 모드에서 메시징이 활성화된 플랫폼의 기기를 찾지 못했음을 보여주는 것이지, 기기에 Live Activity 토큰이 없었다는 의미가 아닙니다. 이 단계는 기기가 카드를 표시했는지 또는 사용자가 카드를 열었는지는 보고하지 않습니다.
• 소리는 모든 업데이트에서 보장되지 않습니다: iOS는 자체적으로 Live Activity 알림의 속도를 제한합니다. 동일한 업데이트가 한 번은 소리를 재생하고 다음 번에는 조용히 도착할 수 있습니다.
• 테스트 중 연속된 많은 Start 작업: 짧은 시간 내에 동일한 사람에게 약 10회의 Start 작업을 보내면(예: journey를 테스트하는 동안), Apple이 새 카드를 표시하지 않게 되고 오류를 반환하지 않을 수 있습니다. journey에서는 해당 사람이 여전히 전달된 것처럼 보일 수 있습니다. 테스트 실행 사이에 간격을 두세요.