디버깅

GitHub

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

알림이 등록되지 않거나, 도착하지 않거나, 표시되지 않거나, Capgo 통계가 업데이트되지 않는 경우 이 체크리스트를 사용하세요.

디바이스 레코드부터 확인하기

네이티브 code를 디버깅하기 전에, Capgo에서 해당 디바이스가 보이는지 먼저 확인하세요.

앱을 열고 테스트하려는 사용자로 로그인합니다.
호출하세요 CapgoNotifications.register(...) 로그인 후.
Capgo에서 다음을 엽니다. 알림 > 수신자 조회.
동일한 외부 고객 ID(external customer ID)로 검색합니다.

다음 정보를 포함한 활성 디바이스가 최소 하나는 보여야 합니다:

recipientKey
deviceKey
플랫폼 android 또는 ios
권한 상태
앱 버전
플러그인 버전
태그와 속성

조회에서 디바이스가 반환되지 않으면 전송 경로에서 해당 사용자를 대상으로 지정할 수 없습니다.

임시 디버그 리스너 추가

테스트 중 임시 리스너를 추가하세요. 배포 전에 불필요한 로그를 제거하세요.

await CapgoNotifications.addListener('registrationChanged', (token) => {
  console.log('[CapgoNotifications] registrationChanged', token.value.slice(0, 12))
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('[CapgoNotifications] notificationReceived', notification.id, notification.data)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('[CapgoNotifications] notificationOpened', event.notification.id, event.actionId)
})

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  console.log('[CapgoNotifications] backgroundNotification', event.notification.id, event.notification.data)
  await event.finish()
})

이 정보 수집하기

팀원 또는 Capgo 지원팀과 디버깅할 때 다음 정보를 수집하세요:

Capgo 앱 ID.
App package ID 또는 iOS bundle ID.
디바이스 플랫폼 및 OS 버전.
App 버전 및 빌드 번호.
Plugin 버전.
외부 고객 ID.
recipientKey 및 deviceKey 등록 또는 수신자 조회에서 확인한 값.
캠페인 ID 또는 알림 ID.
앱이 포그라운드, 백그라운드, 강제 종료, 신규 설치 중 어느 상태였는지.
문제가 재현된 실행의 디바이스 로그.

디바이스 로그 활용하기

테스트 알림을 보낼 때 실제 디바이스를 연결해 두세요.

Android의 경우:

Android Studio의 Logcat을 엽니다.
앱 패키지 ID로 필터링하세요.
알림 권한 요청, 네이티브 토큰 갱신, 메시지 수신 및 JavaScript 리스너 로그를 확인하세요.
알림이 화면에 보이지 않는다면, 알림 채널 중요도와 Android 13 이상 버전의 권한 상태를 먼저 확인하세요.

iOS의 경우:

실제 디바이스에서 Xcode를 통해 앱을 실행하세요.
Xcode 콘솔을 열거나 기기 및 시뮬레이터 로그입니다.
Bundle ID로 필터링하고 CapgoNotifications.
확인 AppDelegate.swift 원격 알림(remote notifications)이 전달되는지, 그리고 background mode capability가 활성화되어 있는지 확인하세요.

먼저 foreground 테스트를 한 번, 그다음 background 테스트를 한 번, 마지막으로 silent update-check 테스트를 한 번 진행하세요. 이 순서대로 테스트해야 JavaScript 리스너 문제와 OS의 background delivery 제한 문제를 구분할 수 있습니다.

Registration 문제

CLI 설정이 완료되지 않음

다음 파일이 포함된 폴더에서 setup 명령어를 실행하세요: capacitor.config.*:

npx @capgo/cli@latest notifications setup com.example.app

명령어가 앱 ID를 자동으로 추론하지 못하면 위와 같이 명시적으로 전달하세요. 패키지 설치에 실패하면 패키지 이름이 @capgo/capacitor-notifications맞는지 확인하고, npm 레지스트리가 https://registry.npmjs.org정상인지 확인한 뒤 네트워크 연결을 확인하고 명령어를 다시 실행하세요.

수신자 조회에서 디바이스가 나타나지 않는 경우

확인 사항:

register 앱에 인증된 사용자가 생긴 후 호출되는지 확인하세요.
externalId 대시보드에서 검색한 사용자 ID와 일치하는지 확인하세요.
identityProof 백엔드에서 동일한 사용자 ID로 발급했는지, appId 및 externalId.
appId 에서 configure Capgo 앱과 일치하는지 확인하세요.
consent …로 설정되지 않았습니다. false 사용자가 수신 거부하지 않은 한.
기기에서 다음 주소로 네트워크 접속이 가능합니다: https://api.capgo.app.
네이티브 푸시 토큰이 생성되었습니다. registrationChanged 토큰 갱신을 확인하세요.

유효하지 않은 Identity Proof

Proof는 Capgo 앱 ID와 외부 ID에 바인딩됩니다. 둘 중 하나라도 변경되면 새 Proof를 발급하세요.

하나의 proof를 영구적으로 캐싱하거나 여러 앱에서 재사용하지 마세요. 로그인 후 백엔드에서 proof를 생성(mint)하여 앱으로 반환한 뒤, 다음을 호출하세요. register.

기기는 등록되었지만 권한이 거부됨

사용자가 권한을 거부해도 플러그인은 기기 상태를 등록할 수 있습니다. 기기는 여전히 확인할 수 있지만, 알림은 표시되지 않습니다.

OS 권한 요청 팝업이 뜨기 전에 권한 안내 화면을 먼저 보여주세요. 사용자에게 어떤 이점이 있는지 설명한 뒤, 실제 동작이 필요한 시점에 권한을 요청하는 것이 좋습니다.

전송 문제

대기 중이나 전송되지 않음

확인 사항:

플랫폼 자격 증명 상태가 configured Capgo에서
Worker 환경에 대시보드에 표시된 것과 동일한 Secret 참조가 포함되어 있습니다.
앱의 Package ID 또는 Bundle ID가 플랫폼 푸시 설정과 일치합니다.
대상 타겟이 최소 하나 이상의 활성 디바이스로 확인됩니다.
캠페인이 디바이스에 없는 태그나 세그먼트로 제한되어 있지 않습니다.

전송되었으나 수신되지 않음

확인 사항:

기기가 온라인 상태입니다.
사용자가 앱을 강제 종료하지 않았습니다.
OS 알림 권한이 허용되었습니다.
테스트 중 Android 배터리 제한이 앱을 차단하지 않습니다.
iOS 저전력 모드 및 백그라운드 새로고침 제한이 백그라운드 전달에 영향을 주지 않습니다.
동일한 collapse ID를 가진 다른 알림에 의해 교체되지 않았습니다.

Native push 플랫폼은 알림을 수락한 후에도 전달을 지연, 제한, 병합 또는 누락할 수 있습니다. 프로바이더의 수락(accepted) 통계는 기기에 표시되었다는 증거가 아니라 “전달을 위해 수락됨”으로 간주해야 합니다.

수신되었으나 표시되지 않음

확인 사항:

앱이 포그라운드 상태가 아니었습니다. 포그라운드 알림은 보통 JavaScript로 전달되어 앱이 어떤 UI를 보여줄지 결정할 수 있게 합니다.
Android 알림 채널의 중요도가 알림을 표시하기에 충분히 높습니다.
Android 13 이상의 알림 권한이 허용되었습니다.
iOS의 집중 모드, 알림 요약 또는 앱별 알림 설정이 알림을 숨기고 있지 않습니다.
테스트 중 배지 삭제 또는 앱 실행 로직이 전달된 알림을 제거하지 않고 있습니다.

백그라운드 알림 문제

백그라운드 콜백이 실행되지 않음

백그라운드 알림은 최선형(best-effort) 방식으로 동작합니다. OS에 의해 생략될 수 있습니다.

확인 사항:

iOS의 Background Modes > Remote notifications가 활성화되어 있습니다.
iOS는 AppDelegate.swift 원격 알림을 다음으로 전달합니다: CapgoNotificationsRemoteNotification.
iOS 백그라운드 동작은 실제 기기에서 테스트해야 합니다.
사용자가 앱을 강제 종료하지 않았습니다.
백그라운드 핸들러가 호출됩니다. finish().
콜백 내 작업은 짧고, 네트워크 환경에서 안전하며, 멱등성을 유지해야 합니다.

iOS에서는 알림을 너무 많이 보내거나, 실행 시간이 너무 길거나, 사용자가 앱을 거의 열지 않는 경우 백그라운드 푸시가 제한될 수 있습니다. 이는 플랫폼의 정상적인 동작입니다.

백그라운드가 시작되었으나 완료되지 않음

통계에 다음과 같이 표시되면 background_started 없이 background_finished, JavaScript 핸들러에서 오류가 발생했거나, 타임아웃되었거나, 호출되지 않았을 가능성이 높습니다. finish().

핸들러를 다음으로 감싸세요: try/finally:

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  try {
    await doShortBackgroundWork(event.notification.data)
  } finally {
    await event.finish()
  }
})

Silent Update Check 문제

업데이트 확인 알림은 오지만 업데이트가 설치되지 않는 경우

확인 사항:

@capgo/capacitor-updater 가 설치 및 구성되었습니다.
autoUpdater 이며 true 또는 enableUpdaterIntegration 호출되었습니다.
앱의 알림(Notifications) 설정에서 푸시 업데이트 확인이 허용되어 있어야 합니다.
대상 기기가 예상한 채널에 속해 있어야 합니다.
Capgo에 더 최신 버전의 번들이 있습니다.
업데이트 설치 모드가 올바르게 설정되었습니다: next 다음 재시작 또는 백그라운드 사이클을 위해 대기하거나, set 업데이터가 안전하게 수행할 수 있는 즉시 설치합니다.

앱이 열려 있는 동안 수동으로 확인하려면:

const result = await CapgoNotifications.runUpdateCheck({
  enabled: true,
  installMode: 'next',
})

console.log(result)

수동 확인 결과가 unavailable라면, 먼저 업데이터 플러그인 설정을 점검하세요.

배지 문제

확인 사항:

수신자 조회 시 대상이 올바른 기기로 지정됩니다.
테스트 중인 런처 또는 홈 화면에서 플랫폼이 앱 배지를 지원합니다.
사용자가 OS 알림 설정에서 배지를 비활성화하지 않았습니다.
앱 시작 시 배지가 즉시 초기화되지 않습니다.
로컬 호출과 백엔드 배지 전송 간의 setBadge 레이스 컨디션이 발생하지 않습니다.

통계 문제

통계 데이터 중복 표시

알림 전송은 최소 한 번(at-least-once) 전달을 보장합니다. 큐 재시도나 플랫폼 재시도로 인해 전송이 중복될 수 있습니다. 앱 액션이 멱등성(idempotent)을 유지해야 한다면 notification ID와 collapse ID를 사용하세요.

오래된 기기의 통계가 누락됨

Analytics Engine 레지스트리는 영구 데이터베이스가 아니라 활성 기기를 위한 것입니다. 플러그인은 앱 시작, 토큰 갱신, 외부 ID 변경 시, 그리고 활성 기기 유지 기간이 만료되기 전에 주기적으로 등록을 갱신해야 합니다.

Open 이벤트가 누락됨

확인 사항:

알림에 안정적인 id.
notificationOpened 리스너가 앱 시작 시 등록됩니다.
플러그인이 감지하기 전에 앱이 네이티브 open flow를 커스텀 code로 대체하고 있습니다.
사용자가 앱을 직접 실행하지 않고 알림을 실제로 탭했습니다.

API 디버그 명령

수신자 조회:

curl -X POST 'https://api.capgo.app/notifications/recipients/lookup' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

읽음 통계 확인:

curl 'https://api.capgo.app/notifications/stats?app_id=com.example.app&days=7' \
  -H 'x-api-key: CAPGO_API_KEY'

포그라운드 테스트 전송:

curl -X POST 'https://api.capgo.app/notifications/send' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "payload": {
      "title": "Capgo test",
      "body": "Open this notification to test events.",
      "data": { "debug": "true" }
    }
  }'

주요 원인

증상	예상 원인
디바이스 조회 결과 없음	`register` 호출되지 않음, proof 불일치, 동의값 false, app ID 불일치.
권한 거부됨	OS prompt가 거부되었거나 아직 요청되지 않음.
대기열에는 있지만 전송 통계 없음	플랫폼 인증 정보가 없거나 비활성화됨.
전송됐지만 수신 통계 없음	디바이스 오프라인, OS 스로틀링, 앱 강제 종료 또는 토큰 무효.
포그라운드 알림 로그는 있으나 배너가 뜨지 않음	앱이 포그라운드 상태이므로 자체 인앱 UI를 표시해야 합니다.
iOS에서는 백그라운드 실행이 지원되지 않습니다.	권한 누락, AppDelegate 포워딩 누락, 앱 강제 종료 또는 OS 스로틀링.
업데이트 확인 시 아무런 동작이 없음	Updater 통합 비활성화, 최신 번들 없음, 잘못된 채널 또는 설치 모드 설정 오류.
배지(Badge)가 초기화됨	앱 시작 시 code가 배지를 삭제하거나 로컬/백엔드 배지 쓰기 경합 발생.

디버깅에서 계속하기

기기 등록 및 테스트 알림이 정상 작동하면, 다음을 사용하여 시작하기 배지 연동, 캠페인 타겟팅, silent update 체크를 프로덕션 앱에 적용하세요.