콘텐츠로 건너뛰기
사용자 가이드 사용 방법 가이드 지원 데모 요청 로그인
Pushwoosh.com

iOS Live Activities API

Apple 문서:

Customer Journey Live Activity 포인트가 원시 JSON 편집기 대신 필드 이름에서 content-state 양식을 빌드하도록 하려면, attributes-type에 대한 스키마를 게시하세요. Live Activity Schemas API를 참조하세요.

startLiveActivity

Anchor link to

POST https://api.pushwoosh.com/json/1.3/startLiveActivity

iOS Live Activities를 생성할 수 있습니다.

요청 본문

Anchor link to
매개변수타입필수/선택설명
applicationString필수Pushwoosh 애플리케이션 코드
authString필수Pushwoosh Control Panel의 API 액세스 토큰.
notificationsArray필수메시지 매개변수의 JSON 배열입니다. 자세한 내용은 아래 알림 표를 참조하세요.

알림

Anchor link to

notifications 배열에 사용되는 매개변수:

매개변수타입필수/선택설명
contentString필수*Live Activity를 시작하는 푸시의 알림 본문이며, iOS 16.1 미만 버전의 기기에 표시되는 대체 텍스트입니다.
titleString필수*Live Activity를 시작하는 푸시의 알림 제목입니다.
live_activityObject필수iOS에서 Live Activity를 생성하기 위한 Live Activity 데이터입니다.
live_activity.content-stateObject필수Live Activity 알림의 콘텐츠입니다.
live_activity.attributes-typeString필수Live Activity에서 사용되는 속성의 유형입니다.
live_activity.attributesObject필수Live Activity의 속성입니다.
live_activity_idString필수Live Activity의 고유 식별자입니다. updateLiveActivity를 호출할 때 이 활동을 대상으로 지정하는 데 사용됩니다. 활동 세션당 고유해야 합니다.
filterString선택Pushwoosh 필터(세그먼트)의 이름입니다. 세그먼트 / 필터 이름을 참조하세요. 이 필터와 일치하는 모든 기기에서 Live Activity가 시작됩니다.
devicesArray of Strings선택기기 토큰 목록입니다. 지정된 기기에서만 Live Activity가 시작됩니다.
send_dateString선택Live Activity를 시작하는 푸시를 특정 날짜 및 시간으로 예약합니다. filter 또는 devices 타겟팅과 함께 작동합니다. YYYY-MM-DD HH:mm 형식을 사용하거나, 즉시 시작하려면 now를 사용합니다(이 매개변수를 생략할 경우에도 기본값입니다). 과거 1일 이내 또는 미래 30일 이내여야 하며, 그렇지 않으면 요청이 유효성 검사 오류로 거부됩니다.
timezoneString선택send_date를 해석하는 데 사용되는 시간대입니다. 생략하면 send_date는 UTC로 해석됩니다.
apns_priorityInteger선택이 Live Activity 푸시의 APNs 전송 우선순위를 제어합니다. 10(높은 우선순위, 잠금 화면에서 즉시 렌더링되도록 apns-priority: 10 헤더와 함께 전송) 또는 5(낮은 우선순위, 기기 배터리 절약을 위해 apns-priority: 5와 함께 전송)를 허용합니다. 다른 값은 유효성 검사 오류 없이 5로 처리됩니다. 모든 Live Activity 푸시는 알림 콘텐츠(content/title) 포함 여부와 관계없이 기본적으로 우선순위 5로 설정됩니다. 높은 우선순위 전송을 요청하려면 apns_priority: 10을 명시적으로 설정하세요. 아래의 긴급 푸시 및 전송 우선순위를 참조하세요.

참고: * content 또는 title 중 하나 이상은 비어 있지 않아야 합니다. Pushwoosh는 둘 다 비어 있는 시작 요청을 거부합니다.

요청 예시

Anchor link to
{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1"
      }
    ]
  }
}

응답 예시

Anchor link to
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

참고:

이 문서를 읽고 Pushwoosh iOS SDK를 사용하여 Live Activities 작업에 대해 자세히 알아보세요.

updateLiveActivity

Anchor link to

POST https://api.pushwoosh.com/json/1.3/updateLiveActivity

iOS Live Activities를 업데이트하고 종료할 수 있습니다.

요청 본문

Anchor link to
매개변수타입필수/선택설명
authString필수Pushwoosh Control Panel의 API 액세스 토큰.
applicationString필수Pushwoosh 애플리케이션 코드
notificationsArray필수메시지 매개변수의 JSON 배열입니다. 자세한 내용은 아래 알림 표를 참조하세요.

알림

Anchor link to

notifications 배열에 사용되는 매개변수:

매개변수타입필수/선택설명
live_activityObject필수iOS에서 Live Activity를 업데이트하기 위한 Live Activity 데이터입니다.
live_activity.eventString필수이벤트 유형을 지정합니다. Live Activity를 업데이트하려면 "update"를, 닫으려면 "end"를 사용합니다.
live_activity.content-stateObject필수콘텐츠를 업데이트하기 위해 Live Activity에 데이터를 전달하는 데 사용되는 키-값 쌍을 가진 객체입니다.
live_activity.dismissal-dateInteger선택Live Activity가 종료되어야 하는 시간(초)입니다. end에서는 이 필드를 생략하면 iOS가 자체적으로 제거할 때까지 카드가 마지막 content-state를 계속 표시합니다 — 아래 참고 사항을 확인하세요. 대신 과거 날짜를 설정하면 이 업데이트가 도착하는 즉시 카드가 제거됩니다.
live_activity_idString필수업데이트할 Live Activity의 고유 식별자입니다. startLiveActivity에서 사용된 live_activity_id와 일치해야 합니다. 업데이트는 이 활동이 시작된 모든 기기로 전송됩니다.
live_activity.relevance-scoreInteger선택iOS 시스템에 어떤 Live Activity가 다른 것보다 높은 우선순위를 갖는지 알려줍니다. 1부터 무한대까지의 값을 허용합니다(100까지의 값을 권장합니다).
live_activity.stale-dateInteger선택Live Activity가 오래되거나 만료되는 날짜를 나타내는 시간(초)입니다.
apns_priorityInteger선택이 Live Activity 푸시의 APNs 전송 우선순위를 제어합니다. 10(높은 우선순위, 잠금 화면에서 즉시 렌더링되도록 apns-priority: 10 헤더와 함께 전송) 또는 5(낮은 우선순위, 기기 배터리 절약을 위해 apns-priority: 5와 함께 전송)를 허용합니다. 다른 값은 유효성 검사 오류 없이 5로 처리됩니다. 모든 Live Activity 푸시는 알림 콘텐츠(content/title) 포함 여부와 관계없이 기본적으로 우선순위 5로 설정됩니다. 높은 우선순위 전송을 요청하려면 apns_priority: 10을 명시적으로 설정하세요. 아래의 긴급 푸시 및 전송 우선순위를 참조하세요.
contentString선택이 업데이트의 알림 본문입니다. 일반적인 경우는 content-state 전용 업데이트로, content, title, subtitle을 설정하지 않으며 알림을 전혀 포함하지 않습니다.
titleString선택이 업데이트의 알림 제목입니다. content, title 또는 subtitle을 설정하면 알림이 트리거되고 ios_sound가 재생됩니다. 세 가지 중 아무것도 설정되지 않으면 업데이트는 조용히 유지되며, 이는 content-state 전용 업데이트의 기본값입니다.
subtitleString선택이 업데이트의 알림 부제목입니다. 위의 content/title과 동일한 알림 트리거 역할을 합니다.
ios_soundString선택앱의 메인 번들에 있는 사운드 파일 이름입니다. 이는 최상위 수준의 aps.sound가 아닌 content/title/subtitle과 함께 aps.alert 내부에 포함되며, ActivityKit은 Live Activities에 대해 이를 무시하므로 이 업데이트가 세 가지 중 하나 이상을 설정할 때만 재생됩니다. iOS는 또한 자체적으로 Live Activity 알림의 빈도를 제한합니다. 동일한 페이로드가 한 번은 소리와 함께 도착하고 다음에는 소리 없이 도착하는 것이 기기와 시뮬레이터 모두에서 관찰되었습니다.

참고: relevance-score는 동일한 기기에서 여러 활성 Live Activities의 표시 순서에만 영향을 미칩니다. 전송 긴급성에는 영향을 주지 않습니다. 업데이트가 얼마나 긴급하게 전송되어야 하는지를 제어하려면 apns_priority를 사용하세요.

요청 예시

Anchor link to
{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "title": "Live Activity Update",
        "live_activity": {
          "event": "update",
          "content-state": {
            "status": "second 66",
            "estimatedTime": "66 min",
            "emoji": "👨‍"
          },
          "relevance-score": 60
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY"
      }
    ]
  }
}

응답 예시

Anchor link to
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

이 문서를 읽고 Pushwoosh iOS SDK를 사용하여 Live Activities 작업에 대해 자세히 알아보세요.

긴급 푸시 및 전송 우선순위

Anchor link to

기본적으로 Apple은 배터리를 절약하기 위해 Live Activity 업데이트를 낮은 우선순위(apns-priority: 5)로 전송합니다. 기기가 잠겨 있을 때, 낮은 우선순위 업데이트는 백그라운드에서 처리되며 사용자가 기기를 잠금 해제한 후에만 잠금 화면에 표시됩니다. 이미 잠금 해제된 기기에서는 즉시 렌더링됩니다. 위에서 설명한 apns_priority 매개변수를 사용하여 높은 우선순위(apns-priority: 10) 전송을 요청하면 잠금 해제 없이 잠금 화면에서 즉시 업데이트가 렌더링됩니다.

apns_priority: 10을 사용할 수 있더라도 Apple은 사용 빈도를 제한합니다.

기기당 여러 활동

Anchor link to

startLiveActivity를 다른 live_activity_id 값으로 여러 번 호출하여 동일한 기기에서 여러 Live Activities를 시작할 수 있습니다.

예를 들어, filter: FILTER_NAME_1을 사용하여 FIRST_LIVE_ACTIVITY와 filter: FILTER_NAME_2를 사용하여 SECOND_LIVE_ACTIVITY라는 두 가지 활동을 시작하면, 두 필터에 모두 일치하는 기기는 두 활동을 동시에 실행하게 됩니다.

그 중 하나를 업데이트하려면 해당 live_activity_id를 updateLiveActivity에 전달합니다. 업데이트는 해당 활동이 생성된 모든 기기로 전송됩니다. 다른 활동은 영향을 받지 않습니다.

relevance-score 매개변수는 동일한 기기에서 여러 Live Activities가 활성화되어 있을 때 표시 우선순위를 제어합니다. 화면 공간이 제한되거나 활동이 그룹화된 경우, 더 높은 값을 가진 활동이 더 높은 우선순위로 표시됩니다.