라이브 푸시 연동 가이드

자동화로 앱 잠금화면에 진행 상황을 보내고, 취소 API로 대기 중이거나 노출 중인 건을 마감합니다.

참고시작 방법
서버 API로 발송을 시작하지 않습니다. 앱이 이벤트를 보내면 자동화 캔버스의 발송 노드(채널: 라이브 푸시)가 start·update·end 를 보냅니다. 연락처가 연결된 이벤트만 처리합니다. 앱에서 SDK 로 사용자를 식별한 뒤 이벤트를 보내세요.

1. 앱에서 보낼 이벤트

예약마다 고유한 live_push_id 를 앱이 핑거푸시 SDK 에 등록한 값과 같게 보냅니다. 50byte 까지 쓸 수 있습니다.

JavaScript
track('reservation_created', {
  live_push_id: 'R-1',
  visit_at: '2026-11-15T10:00:00+09:00'
});

2. 캔버스 구성 예시

입장 1시간 전에 시작하고 입장 시각에 끝내는 흐름입니다.

트리거 → 대기(이벤트 속성의 시각 visit_at, 60분 전) → 발송(start) → 대기(visit_at, 0분 전) → 발송(end)

  • 예약 ID 는 이벤트 속성 live_push_id 로 고정입니다. 라이브 푸시 노드를 넣으면 트리거의 묶음 키가 자동으로 live_push_id 로 지정됩니다.
  • 모든 경로에 end 발송 노드가 있어야 규칙을 켤 수 있습니다.
  • 같은 사람의 다른 예약은 따로 진행합니다. 같은 ID 가 진행 중이면 새로 시작하지 않습니다.
  • 쿨다운·1인당 최대 발송·일일 한도는 라이브 푸시 규칙에 적용되지 않습니다.
  • 정보성으로 나가며 광고 수신동의와 야간 광고 제한을 적용하지 않습니다. 앱 푸시 수신거부면 건너뜁니다.
  • 단계마다 앱 푸시 단가로 과금됩니다.

3. 시각 값

경우동작
시간대가 있는 값그대로 읽습니다
시간대가 없는 값조직 시간대로 읽습니다
값이 없음, 날짜만 있음, 형식 오류보내지 않고 사유를 남깁니다
이벤트 시점에서 달력 한 달보다 멂보내지 않고 사유를 남깁니다
시작 시각만 지남바로 시작합니다
입장 시각까지 지남보내지 않고 사유를 남깁니다

4. 예약 취소 API

POST /api/v1/service/messaging/live-push/cancel

콜센터·웹에서 일어난 취소를 고객 서버가 알립니다. 전 요금제에서 호출할 수 있고, 메시징 애드온 조직은 Pro 미만이어도 API 키를 발급할 수 있습니다. 허용 IP 규칙은 다른 Service API 와 같습니다.

cURL
curl -X POST https://api.fingerpush.link/api/v1/service/messaging/live-push/cancel \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"live_push_id":"R-1"}'
JSON
{ "cancelled": 1, "ended": 0 }
필드설명
cancelled이번 호출로 마감한 건수
ended그중 이미 노출 중이어서 end 까지 보낸 건수. 캔버스에 적은 취소 문구가 있으면 그 문구로 보냅니다(종료 노드의 '취소로 끝낼 때', 단계별로 다르게 하려면 시작·갱신 노드의 '이 단계 뒤에 취소되면')
  • 맞는 예약이 없어도 200 과 cancelled: 0 입니다. 다시 호출해도 안전합니다.
  • live_push_id 가 없으면 400 입니다.
  • 최근 32일 안에 시작한 대기 건만 찾습니다.

5. 화면에 나오는 값

발송 노드는 공통 칸과 Android·iOS 칸으로 나뉩니다. 트리거에서 고른 앱의 OS 칸만 켜지고, 꺼진 OS 의 값은 보내지 않습니다. 키 이름은 핑거푸시 SDK 기준입니다. Android 알림은 SDK 가 그리고, iOS 잠금화면·다이내믹 아일랜드는 고객사 앱의 위젯이 그립니다.

공통

노드 칸보내는 키화면
단계eventstart·update·end. Android 는 end 면 사용자가 알림을 지울 수 있습니다
대표 메시지messageiOS 시스템 알림 본문. Android 에는 나오지 않습니다
dismiss (분)dismissTime → dismissal-dateend 에만 씁니다. 그 시간이 지나면 두 OS 모두 사라집니다. 비우면 1분입니다

Android

노드 칸보내는 키화면
제목content-state.liveNotiTitle알림 제목
본문content-state.liveNotiMessage알림 본문
짧은 문구content-state.shortText상태바 칩 (Android 16 이상)
전체·현재 단계totalSegment, currentSegment진행 막대. 전체 N 이면 N-1 칸을 그리고 현재 M 이면 M-1 칸을 채웁니다
  • 알림 화면은 SDK 가 그립니다. 앱은 아이콘과 색만 정합니다.
  • 예약마다 다른 notificationId 로 등록하세요. 같으면 두 예약의 알림이 하나로 덮어써집니다.
  • Android 15 이하에서는 상태바 칩이 없고 일반 진행 막대가 나옵니다.

iOS

iOS 칸은 핑거푸시 SDK 샘플 위젯 OrderLiveActivityAttributes 의 키입니다. 앱 위젯을 이 타입과 같게 두세요.

노드 칸보내는 키샘플 위젯 화면
알림 제목발송 파라미터 prv_title시스템 알림 제목. 비우면 Android 제목을 씁니다
가게명attributes.storeName위젯 제목 줄. start 에만 보냅니다
주문 내용attributes.orderItems다이내믹 아일랜드(펼침). start 에만 보냅니다
상태content-state.status상태 배지·아이콘·색. preparing·delivering·completed·cancelled 중 하나
상태 문구content-state.statusMessage위젯 본문 줄
남은 시간(분)content-state.estimatedMinutes"약 N분 예상", 다이내믹 아일랜드의 "N분". 숫자로 보냅니다
담당자 이름content-state.deliveryPersonName다이내믹 아일랜드(펼침)
stale (분)staleTime → stale-date그 시각이 지나면 위젯의 isStale 이 참이 됩니다
추가 키(고급)attributes·content-state 의 나머지 키앱 위젯이 선언한 키로 읽습니다
(자동)attributes.orderIdlive_push_id 값으로 start 에 자동으로 채웁니다
Swift
// 핑거푸시 SDK 샘플 위젯과 같은 타입. 앱 타겟과 위젯 확장에 같은 파일을 넣습니다.
enum OrderStatus: String, Codable, Hashable {
    case preparing  = "preparing"
    case onTheWay   = "delivering"
    case delivered  = "completed"
    case cancelled  = "cancelled"
}

struct OrderLiveActivityAttributes: ActivityAttributes {
    public struct ContentState: Codable, Hashable {
        var status: OrderStatus
        var statusMessage: String
        var estimatedMinutes: Int?
        var deliveryPersonName: String?
    }
    var orderId: String
    var storeName: String
    var orderItems: String
}
  • 위젯 타입 이름은 ActivityConfiguration, registerLiveActivityPushToStart, observeLiveActivityUpdate 세 곳에서 같아야 합니다. 다르면 start 는 전달돼도 위젯이 뜨지 않고 update·end 가 닿지 않습니다.
  • 상태 값은 SDK 코드 기준입니다. SDK 문서의 onTheWay·delivered 는 코드의 rawValue 와 다릅니다.
  • 추가 키로 위젯 타입에 선언하지 않은 키를 보내면 디코딩에 실패할 수 있습니다. 전용 칸과 같은 키는 추가 키에 넣을 수 없습니다.
  • 위젯 모양은 앱이 정합니다. 진행 막대를 그리려면 앱이 상태 값으로 그리면 됩니다.

취소 화면

취소로 끝날 때도 event 는 end 입니다. '취소로 끝낼 때'·'이 단계 뒤에 취소되면' 칸에 적은 값으로 바꿔 보냅니다.

  • iOS 상태는 취소 칸에서 고르지 않으면 cancelled 로 보냅니다. 샘플 위젯은 빨간 "주문 취소" 배지로 그립니다.
  • 트리거에 iOS 앱이 있으면 종료 노드의 '취소로 끝낼 때' 상태 문구를 꼭 적어야 합니다. 정상 종료 문구가 취소 배지와 함께 보이지 않게 하기 위해서입니다.
  • Android 는 문구와 진행 막대만 바뀝니다. 아이콘과 색은 정상 종료와 같습니다.

6. 제약

  • 예약 시각 변경은 지원하지 않습니다. 취소한 뒤 앱에서 새 이벤트를 보내세요.
  • 앱 이벤트로 취소할 때는 트리거의 발송 취소 이벤트에 등록합니다. 이벤트에 ID 값이 없으면 그 사람의 대기 건을 모두 취소합니다.
  • end 는 앞 단계가 실패해도 보냅니다.