Live Activity 스키마 API

Live Activity 스키마는 앱에 있는 하나의 ActivityAttributes 유형(예: FlightAttributes)에 대한 JSON 스키마로, 활동이 실행되는 동안 변경되는 ContentState 필드와 활동의 전체 수명 동안 고정되는 필드, 즉 카드의 양쪽 절반을 모두 다룹니다. Journey의 Live Activity 요소가 원시 JSON 편집기와 자유 형식 필드 목록 대신 이 스키마로부터 양쪽 절반 모두에 대한 명명된 필드를 빌드할 수 있도록 스키마를 게시합니다. 카드와 그 레이아웃은 여전히 앱 코드에서 빌드됩니다. 스키마는 Journey가 채우는 데이터만 설명합니다.

이 API는 Live Activities를 통합하는 개발자를 위한 것입니다. 활동 자체를 시작하고 업데이트하는 방법에 대해서는 iOS Live Activities API를 참조하세요.

스키마 작성하기

attributesType은 앱에서 ActivityAttributes를 준수하는 Swift 유형의 이름입니다. Pushwoosh는 코드를 읽거나 이름을 검증하지 않습니다. 이는 API가 저장하는 문자열이자 startLiveActivity의 attributes-type 필드에 전달하는 문자열일 뿐입니다.

jsonSchema는 해당 유형의 양쪽 절반을 다음 두 곳에서 다룹니다:

• 항공편의 게이트, 상태 또는 도착 예정 시간(ETA)과 같이 활동이 실행되는 동안 변경되는 ContentState 필드는 스키마의 루트 properties에 들어갑니다.
• 항공편 번호와 같이 활동의 전체 수명 동안 고정되고 시작 시 한 번 설정되는 ActivityAttributes 필드는 자체 properties와 선택적인 required 목록을 가진 별도의 attributes 섹션에 들어갑니다.

attributes 섹션은 선택 사항입니다. 이 섹션이 없으면 ActivityAttributes 필드는 이름이 지정된 필드 대신 Live Activity 요소에서 자유 형식의 필드 이름/값 목록으로 남습니다. 실제 속성 값은 여전히 startLiveActivity의 live_activity.attributes를 통해 전달합니다 — 스키마는 필드의 이름, 유형, 필수 여부만 선언합니다.

예시

struct FlightAttributes: ActivityAttributes {
    struct ContentState: Codable, Hashable {
        var gate: String
        var status: String
        var estimatedTime: String
    }

    var flightNumber: String
}

flightNumber는 ActivityAttributes에 있습니다. gate, status, estimatedTime은 ContentState에 있습니다. attributesType: "FlightAttributes"에 대한 스키마로 양쪽 절반을 모두 게시합니다:

{
  "type": "object",
  "properties": {
    "gate": { "type": "string" },
    "status": { "type": "string" },
    "estimatedTime": { "type": "string" }
  },
  "attributes": {
    "properties": {
      "flightNumber": { "type": "string" }
    },
    "required": ["flightNumber"]
  }
}

attributes 내부의 required는 Live Activity 요소의 시작 단계에서 flightNumber를 필수로 만듭니다. 그곳에서 비워두면 거부됩니다. ContentState 필드에 대한 루트 properties에는 그런 목록이 없습니다. Journey는 gate, status, estimatedTime을 채울 필요가 전혀 없습니다.

게시되면 Journey의 Live Activity 요소는 이 형태를 읽어 원시 content-state 편집기 대신 카드 콘텐츠에서 gate, status, estimatedTime에 대한 명명된 필드를 제공합니다. flightNumber의 경우도 마찬가지로, 자유 형식의 필드 이름/값 목록 대신 카드 속성에서 제공됩니다.

jsonSchema에 적용되는 형식 및 불변성 규칙은 아래 규칙을 참조하고, API를 직접 호출하지 않고 동일한 작업을 수행하려면 이 페이지 끝에 있는 Control Panel에서 스키마 관리하기를 참조하세요.

기본 URL

https://rpc-api.svc-nue.pushwoosh.com

인증

모든 요청에는 서버 API 토큰이 포함된 Authorization 헤더가 있어야 합니다:

Authorization: Api YOUR_API_TOKEN

규칙

• 필드 이름 지정은 비대칭적입니다. 요청은 lowerCamelCase와 프로토콜 이름을 모두 허용합니다. 응답은 항상 snake_case(attributes_type, json_schema) 형식의 프로토콜 필드 이름으로 반환됩니다. 아래 예제에서는 해당 케이싱을 사용합니다.
• 버전은 불변입니다. 게시된 버전은 편집할 수 없습니다. Update 메서드가 없습니다. 동일한 attributesType과 version으로 다시 게시하면 AlreadyExists 오류가 발생하며 실패합니다. 위젯 변경은 항상 새 버전입니다. Create에서 version을 생략하면 해당 attributesType에 대한 다음 사용 가능한 버전이 게시됩니다.
• jsonSchema 형식: "type": "object"를 포함하는 JSON 객체여야 하며, 최대 64KB까지 가능합니다. null, 숫자, 일반 문자열 또는 "type": "object"가 없는 객체는 모두 거부됩니다. Pushwoosh가 빌드하는 양식에는 명명된 필드가 필요하며, 이는 객체 스키마에만 있습니다. 선택적인 attributes 섹션이 있는 경우, 이는 그 자체로 고유한 properties와 선택적으로 attributes.properties에 선언된 필드만 지정하는 required 배열을 가진 객체여야 합니다. 필드 이름은 properties와 attributes.properties 양쪽에 동시에 나타날 수 없습니다.

엔드포인트

메서드	경로	설명
GET	/api/live_activity_schemas	애플리케이션의 스키마 목록 조회
GET	/api/live_activity_schemas/{attributesType}/{version}	단일 스키마 버전 가져오기
POST	/api/live_activity_schemas	새 스키마 버전 게시
DELETE	/api/live_activity_schemas/{attributesType}/{version}	스키마 버전 삭제

목록 조회

애플리케이션이 스키마를 게시한 모든 attributesType을 모든 버전과 함께 최신 버전부터 순서대로 나열합니다.

GET /api/live_activity_schemas

쿼리 파라미터

파라미터	유형	필수	설명
application	string	예	스키마를 조회할 애플리케이션 코드.
attributesType	string	아니요	목록을 하나의 ActivityAttributes 유형으로 제한합니다.

응답 예시

{
  "schemas": [
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 2,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}",
      "created": "2026-09-01T10:00:00Z",
      "updated": "2026-09-01T10:00:00Z"
    },
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 1,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}}}",
      "created": "2026-08-15T10:00:00Z",
      "updated": "2026-08-15T10:00:00Z"
    }
  ]
}

가져오기

단일 스키마 버전을 반환합니다.

GET /api/live_activity_schemas/{attributesType}/{version}

경로 파라미터

파라미터	유형	필수	설명
attributesType	string	예	ActivityAttributes 유형의 이름.
version	integer	예	스키마 버전.

쿼리 파라미터

파라미터	유형	필수	설명
application	string	예	스키마가 속한 애플리케이션 코드.

응답

위의 목록 조회에 표시된 스키마 객체인 { "schema": { ... } }를 반환합니다.

생성

attributesType에 대한 새 스키마 버전을 게시합니다. 할당된 버전을 포함하여 생성된 스키마를 반환합니다.

POST /api/live_activity_schemas

요청 본문

파라미터	유형	필수	설명
application	string	예	스키마를 게시할 애플리케이션 코드.
attributesType	string	예	앱에 선언된 ActivityAttributes 유형의 이름.
jsonSchema	string	예	ContentState와 attributes 모두의 JSON 스키마입니다. 위의 스키마 작성을 참조하세요.
version	integer	아니요	게시할 버전. 이 attributesType에 대한 다음 사용 가능한 버전을 얻으려면 생략하세요.

요청 예시

{
  "application": "XXXXX-XXXXX",
  "attributesType": "FlightAttributes",
  "jsonSchema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}"
}

응답

생성된 스키마 객체인 { "schema": { ... } }를 반환합니다.

주의

이미 존재하는 attributesType/version 쌍을 게시하면 AlreadyExists 오류가 발생하며 실패합니다. 버전은 불변이므로 덮어쓸 방법이 없습니다. 대신 version 없이 게시하여 다음 버전을 받으세요.

삭제

단일 스키마 버전을 영구적으로 삭제합니다.

DELETE /api/live_activity_schemas/{attributesType}/{version}

경로 파라미터

파라미터	유형	필수	설명
attributesType	string	예	ActivityAttributes 유형의 이름.
version	integer	예	삭제할 스키마 버전.

쿼리 파라미터

파라미터	유형	필수	설명
application	string	예	스키마가 속한 애플리케이션 코드.

응답

성공 시 빈 객체를 반환합니다.

위험

이 작업은 되돌릴 수 없습니다. 삭제된 버전에 대해 빌드된 Journey의 Live Activity 요소는 이미 저장된 콘텐츠 및 속성 값을 유지합니다. 다만 이후로는 둘 다에 대한 양식 힌트를 잃습니다: 콘텐츠는 원시 JSON 편집기로, 속성은 자유 형식의 필드 이름/값 목록으로 대체됩니다.

오류 응답

HTTP 상태	의미
400 Bad Request	잘못된 인수: 필수 필드가 누락되었거나, jsonSchema가 위의 형식 규칙을 따르지 않거나(잘못된 attributes 섹션 포함), jsonSchema가 64KB를 초과합니다.
401 Unauthorized	Authorization 헤더가 누락되었거나 유효하지 않습니다.
403 Forbidden	애플리케이션이 호출자의 계정에 속하지 않습니다.
404 Not Found	애플리케이션 또는 attributesType/version 쌍을 찾을 수 없습니다.
409 Conflict	이미 존재하는 attributesType/version 쌍으로 Create가 호출되었습니다(전송 시 AlreadyExists).
500 Internal Server Error	예기치 않은 서버 측 오류.

Control Panel에서 스키마 관리하기

Control Panel은 API를 직접 호출하지 않고도 API와 동일한 작업을 제공합니다: 유형별 버전 목록 조회, 새 버전 게시, 버전의 JSON 보기, 버전 삭제(삭제는 영구적이므로 확인 메시지 포함). 클릭 경로는 iOS Live Activity 스키마 구성을 참조하세요.