라이브 푸시 연동 가이드
자동화로 앱 잠금화면에 진행 상황을 보내고, 취소 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 잠금화면·다이내믹 아일랜드는 고객사 앱의 위젯이 그립니다.
공통
| 노드 칸 | 보내는 키 | 화면 |
|---|---|---|
| 단계 | event | start·update·end. Android 는 end 면 사용자가 알림을 지울 수 있습니다 |
| 대표 메시지 | message | iOS 시스템 알림 본문. Android 에는 나오지 않습니다 |
| dismiss (분) | dismissTime → dismissal-date | end 에만 씁니다. 그 시간이 지나면 두 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.orderId | live_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 는 앞 단계가 실패해도 보냅니다.