@capgo/capacitor-notifications

개요

@capgo/capacitor-notifications Capacitor 앱을 Capgo의 네이티브 알림 파이프라인에 연결합니다. 앱이 Capgo에 서명된 사용자 ID를 등록하면, Capgo이 최신 활성 디바이스 상태를 Cloudflare Analytics Engine에 유지합니다. 이를 통해 Capgo 대시보드나 API에서 알림 전송, 배지 설정, 전송 통계 확인 및 사이런트 Capgo live-update 체크를 실행할 수 있습니다.

이 기능은 Capgo Postgres에 고카디널리티(high-cardinality) 알림 디바이스 테이블이 생성되는 것을 방지하도록 설계되었습니다. Postgres에는 앱 설정, 플랫폼 자격 증명 메타데이터, 캠페인 초안, 스케줄 및 캠페인 집계 레코드와 같은 저카디널리티(low-cardinality) 컨트롤 플레인 데이터만 저장됩니다. 활성 디바이스 상태와 알림 이벤트는 Analytics Engine에 append-only 방식으로 저장되는 행입니다.

플랫폼 지원

플랫폼	지원	참고 사항
iOS	지원	Capgo를 통한 APNs
Android	지원	Capgo를 통한 FCM
웹	아니요	웹 푸시 별도 사용

Capgo가 저장하는 항목

데이터	저장 위치	이유
플랫폼 자격 증명 메타데이터	Capgo Postgres	앱 설정 및 권한 관리에 필요합니다.
플랫폼 전용 비밀 키	Worker 환경	사용자 노출 테이블에 개인 인증 정보를 저장하지 않습니다.
캠페인 초안 및 설정	Capgo Postgres	저카디널리티(Low-cardinality) 컨트롤 플레인 데이터.
활성 디바이스 등록 상태	Cloudflare 분석 엔진	저비용의 Append-only 방식 활성 디바이스 레지스트리.
알림 이벤트	Cloudflare Analytics Engine	대기, 전송, 수신, 오픈, 실패 및 백그라운드 이벤트에 대한 저렴한 통계 정보를 제공합니다.

Identity 모델

Capgo는 사용자 목록을 업로드하거나 디바이스 테이블을 직접 관리할 필요가 없습니다.

• 실제 고객의 사용자 ID는 백엔드에서 관리합니다.
• 백엔드에서 Capgo에 짧은 유효 기간을 가진 identityProof.
• 앱이 다음을 통해 등록합니다 externalId 사용자 인증이 성공한 후 해당 증명을 전달합니다.
• Capgo는 수신자와 네이티브 설치 환경에 대한 결정론적 내부 키를 생성합니다.
• 동일한 대상으로 전송 시 externalId 사용자의 활성 디바이스를 다시 찾아냅니다.

Capgo Postgres에 기기별 알림 데이터를 저장하지 않고도 사용자의 기기를 조회하고, 배지를 설정하며, 타겟 알림 캠페인을 실행할 수 있습니다.

핵심 기능

• 인증된 외부 사용자 ID로 기기를 등록합니다.
• 앱 시작 시 또는 토큰 변경 시 태그, 속성, 동의 여부 및 토큰 상태를 새로고침합니다.
• JavaScript에서 포그라운드 알림을 수신합니다.
• 알림 수신 및 클릭 이벤트를 추적합니다.
• 백그라운드 데이터 알림을 처리합니다.
• 앱 배지를 설정, 삭제 또는 증가시킵니다.
• Android 알림 채널을 생성합니다.
• 단일 알림, 캠페인 알림, 배지 업데이트 및 silent 업데이트 체크를 전송합니다.
• 트리거 @capgo/capacitor-updater silent notification으로부터.

통계

Capgo은(는) notification 이벤트를 Cloudflare Analytics Engine에 기록하여 대시보드 통계 비용을 낮게 유지합니다:

• queued
• sent
• provider_accepted
• received
• opened
• failed
• permission_changed
• background_started
• background_finished

Stats는 운영 신호이며, 수신자별 영구 장부가 아닙니다. Analytics Engine의 데이터 보관 정책에 따라 활성 디바이스는 주기적으로 registration을 갱신해야 합니다.

공개 API

메서드	설명
configure	Capgo app ID, API host 및 updater 통합 동작을 설정합니다.
register	현재 설치된 앱을 외부 고객 user ID로 등록합니다.
setExternalId	로그인 또는 계정 전환 시 외부 고객 user ID를 변경합니다.
setTags	오디언스 타겟팅에 사용되는 태그를 교체합니다.
setBadge	네이티브 앱 배지를 설정합니다.
clearBadge	네이티브 앱 배지를 지웁니다.
incrementBadge	네이티브 앱 배지 숫자를 올립니다.
enableUpdaterIntegration	다음을 통해 silent update-check 처리를 활성화합니다: @capgo/capacitor-updater.
runUpdateCheck	테스트를 위해 updater 통합을 수동으로 실행합니다.
trackReceived	수신된 이벤트를 수동으로 기록합니다.
trackOpened	열림 이벤트를 수동으로 기록합니다.
addListener('notificationReceived')	JavaScript가 활성화된 상태에서 알림이 수신되면 발생합니다.
addListener('notificationOpened')	사용자가 알림을 열면 발생합니다.
addListener('backgroundNotification')	백그라운드 데이터 알림 시 발생하며 다음을 제공합니다: finish().
addListener('registrationChanged')	네이티브 push token이 변경되면 발생합니다.

전송 보장

Native push는 최소 한 번(at-least-once) 전송을 보장합니다. 플랫폼이 중복 메시지를 허용할 경우 캠페인이 재시도되어 기기에 중복 메시지가 전달될 수 있습니다. 업데이트 확인 시에는 collapse ID를 사용하고, 백그라운드 작업은 멱등성(idempotent)을 유지하도록 설계하세요.

iOS 백그라운드 알림은 최선 노력(best-effort) 방식입니다. OS는 배터리 상태, 사용자 행동, 앱 강제 종료 상태 및 시스템 정책에 따라 백그라운드 실행을 제한하거나 건너뛸 수 있습니다. 엄격한 마감 기한이 필요한 작업에 silent notification을 의존하지 마세요.

@capgo/capacitor-notifications에서 계속하기

사용 중이라면 @capgo/capacitor-notifications 푸시 메시징을 계획하려면, 다음을 연결하세요: 시작하기 설정 방법: 디버깅 문제 해결을 위해, @capgo/capacitor-updater 백그라운드 업데이트 확인을 위해, 그리고 Capgo 플러그인 디렉토리 기타 네이티브 플러그인을 위해.