Debugging

GitHub

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설치 명령어를 복사할 수 있는 설정 명령어를 복사하세요.

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

기기 기록에서 시작하세요.

native code를 디버깅하기 전에 Capgo이 장치에 접근할 수 있는지 확인하세요.

앱을 열고 테스트하려는 사용자로 로그인하세요.
Call CapgoNotifications.register(...) 로그인 후.
Capgo에서 通知 > 수신자 조회.
외부 고객 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.
앱 패키지 ID 또는 iOS 번들 ID.
장치 플랫폼 및 OS 버전.
앱 버전 및 빌드 번호.
플러그인 버전.
외부 고객 ID.
recipientKey and deviceKey 등록 또는 수신자 조회에서.
캠페인 ID 또는 알림 ID.
앱이 전면, 배경, 강제 종료, 또는 새로 설치되었는지 여부.
문제를 재현한 실행에서 장치 로그.

디바이스 로그 사용

실제 장치를 하나 연결하여 테스트 알림을 보내세요.

안드로이드에서:

Android Studio Logcat을 열어보세요.
앱 패키지 ID로 필터링하세요.
通知 권한 요청, 네이티브 토큰 리프레시, 메시지 수신, 자바 스크립트 리스너 로그를 확인하세요.
visible한通知가 나타나지 않으면, Android 13+ 권한 상태와通知 채널 중요도부터 확인하세요.

iOS에서:

실제 기기에서 Xcode로 앱을 실행하세요.
Xcode 콘솔 또는 장치 및 시뮬레이터 로그를 열어보세요.
앱 번들 ID로 필터링하고 CapgoNotifications.
확인하세요. AppDelegate.swift remote notification을 전달하고 배경 모드 기능이 활성화되어야 합니다.

foreground 테스트 한 번, background 테스트 한 번, silent update-check 테스트 한 번 순서로 테스트를 진행하세요. 이 순서로 JavaScript 리스너 문제와 OS 배경 전달 제한을 분리할 수 있습니다.

등록 문제

CLI 설정이 완료되지 않았습니다.

설정 명령어를 실행할 폴더에서 명령어를 실행하세요. capacitor.config.*:

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

명령어가 앱 ID를 자동으로 인식하지 못할 경우 명령어에 앱 ID를 명시적으로 입력하세요. 패키지 설치가 실패할 경우 패키지 이름을 확인하고 __CAPGO_KEEP_0__ 레지스트리를 확인하세요. @capgo/capacitor-notifications, npm 등록을 확인하세요 https://registry.npmjs.org네트워크 접근 권한을 확인한 후 명령어를 다시 실행하세요.

장치가 수신자 검색 목록에 나타나지 않습니다.

확인:

register 인증된 사용자가 있는 앱이 호출 된 후에 호출됩니다.
externalId 검색한 사용자 ID와 일치합니다.
identityProof 동일한 appId 그리고 externalId.
appId 앱과 일치합니다. configure Capgo 앱과 일치합니다.
consent 사용자가 동의하지 않은 경우 false 장치가 네트워크에 접속되어 있습니다.
장치가 네트워크에 접속되어 있습니다. https://api.capgo.app.
원본 푸시 토큰이 생성되었습니다. 사용 registrationChanged 토큰 갱신을 확인하기 위해

유효하지 않은 신원 증명

Capgo 앱 ID와 외부 ID에 결합된 증명입니다. 둘 중 하나의 값이 변경되면 새로운 증명이 생성되어야 합니다.

한 번의 증명은 영원히 캐시하지 마십시오. 앱을 재사용하지 마십시오. 로그인 후 백엔드에서 증명 생성, 앱으로 반환, 호출 register.

등록된 장치지만 권한이 거부된 경우

플러그인은 사용자가 권한을 거부하더라도 장치 상태를 등록할 수 있습니다. 장치를 볼 수 있지만 보이는 알림은 표시되지 않습니다.

OS의 알림 요청 전에 권한 설명 화면을 사용하십시오. 사용자가 무엇을 받을 것인지 설명한 후 권한을 요청하십시오. 권한이 필요한 동작이 있을 때만 권한을 요청하십시오.

배달 문제

보내지 않은 대기 중

체크:

플랫폼 인증 정보 상태는 configured Capgo.
작업자 환경에는 대시보드에 표시된 정확한 비밀 키 참조가 포함되어 있습니다.
앱의 패키지 ID 또는 번들 ID는 플랫폼 푸시 설정과 일치합니다.
목표 청중은 적어도 하나의 활성 장치로 해결됩니다.
캠페인은 장치가 가지고 있지 않은 태그 또는 세그먼트에 제한되지 않습니다.

보내지 않은 수신

체크:

장치가 온라인 상태입니다.
사용자가 앱을 강제 종료하지 않았습니다.
OS 알림 권한이 승인되었습니다.
안드로이드 배터리 제한이 테스트 중 앱을 차단하지 않습니다.
iOS 저전력 모드 및 배경 반영 설정이 배경 전달을影响하지 않습니다.
같은 콜랩스 ID를 가진 알림이 다른 알림으로 대체되지 않았습니다.

원시 푸시 플랫폼은 알림을 수락하고 여전히 지연, 제한, 집계, 또는 전달을 취소할 수 있습니다. 제공자 수락 통계를 “전달 준비”로 간주하십시오. 이는 장치가 표시한 것을 증명하는 것이 아닙니다.

받은 알림이 표시되지 않았습니다.

확인하세요:

앱이 전면 상태가 아닙니다. 전면 알림은 일반적으로 자바스크립트로 전달되어 앱이 표시할 UI를 결정할 수 있습니다.
안드로이드 알림 채널 중요도가 알림을 표시하기에 충분합니다.
안드로이드 13 이상의 알림 권한이 부여되었습니다.
iOS의 초점, 알림 요약, 또는 앱 당 알림 설정이 알림을 숨기지 않습니다.
배경 알림 제거 로직 또는 앱 열기 논리가 테스트 중에 전달된 알림을 제거하지 않습니다.

배경 알림 문제

배경 콜백이 실행되지 않습니다.

배경 알림은 최선의 시도입니다. OS는 그들을 건너뛸 수 있습니다.

확인:

iOS에서 배경 모드 > Remote notifications 활성화되어 있습니다.
iOS AppDelegate.swift remote notifications을 전달합니다. CapgoNotificationsRemoteNotification.
실제 기기에서 iOS 백그라운드 동작을 테스트합니다.
사용자가 앱을 강제 종료하지 않았습니다.
백그라운드 핸들러가 호출합니다. finish().
백그라운드 작업은 짧고 네트워크 안전하며 idempotent합니다.

iOS에서 백그라운드 푸시가 너무 많이 보냈거나 사용자가 앱을 열지 않으면 throttled될 수 있습니다. 사용자 동작에 따라 플랫폼에서 예상되는 동작입니다.

백그라운드 시작되지만 완료되지 않음

백그라운드 시작되지만 완료되지 않음 background_started stat이 표시되면 background_finished없다면 finish().

핸들러를 wrapping 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 설치되어 구성되어 있습니다.
업데이트 체크 알림이 오지만 업데이트가 설치되지 않습니다.
기대하는 채널에 속한 기기입니다.
Capgo 에서 최신 버전의 패키지를 사용할 수 있습니다.
업데이트 모드는 올바릅니다: next 다음 재시작 또는 백그라운드 사이클을 기다리거나 set 업데이터가 안전하게 업데이트를 할 수 있는 즉시 설치합니다.

앱이 열려 있는 동안 수동 체크를 실행하세요:

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

console.log(result)

수동 체크가 반환하면 unavailable업데이터 플러그인 설정을 먼저 확인하세요.

배지 문제

확인:

대상은 수신자 검색에서 올바른 장치로 해결됩니다.
플랫폼은 런처 또는 홈 화면이 테스트되는 앱 배지 지원합니다.
사용자는 OS 알림 설정에서 배지를 비활성화하지 않았습니다.
앱은 시작 시 배지를 즉시 삭제하지 않습니다.
당신은 로컬 호출과 백엔드 배지 전송을 경쟁하지 않습니다. setBadge Stats 문제

제목: "Stats 문제"

제목: "Stats가 중복되는 경우"

오래된 장치에 대한 Stats가 누락됩니다.

Stats Look Duplicated

Analytics Engine 레지스트리는 활성 장치에만 해당되며 영구 데이터베이스가 아닙니다. 플러그인은 앱 시작, 토큰 갱신, 외부 ID 변경, 그리고 활성 장치 보존 기간 전 주기적으로 등록을 갱신해야 합니다.

이벤트를 열람할 수 없는 경우

확인:

通知에는 안정적인 id.
notificationOpened listener는 앱 시작 시 등록됩니다.
앱이 native open flow를 custom 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` 호출되지 않음, 증명 불일치, 동의 거부, 앱 ID 불일치.
권한 거부	OS에서 요청되지 않았거나 거부되었습니다.
대기 중이지만 전송된 통계가 없습니다.	플랫폼 인증 정보가 없거나 비활성화되었습니다.
전송되었지만 수신된 통계가 없습니다.	장치가 오프라인 상태, OS가 속도 제한, 앱이 강제 종료되거나 토큰이 유효하지 않습니다.
전경 알림 로그가 있지만 배너가 없습니다.	앱이 전경화되어 자신의 내부 UI를 표시해야 합니다.
iOS에서 배경이 실행되지 않습니다.	미리 설치된 기능이 없거나 AppDelegate 전달이 없거나 앱이 강제 종료되거나 OS 속도 제한이 걸렸습니다.
업데이트 확인이 아무것도 하지 않습니다.	업데이트 통합이 비활성화되었습니다. 최신 버전이 없습니다. 채널이 틀렸거나 설치 모드가 이해되지 않았습니다.
배지 초기화	앱 시작 시 code 배지 또는 로컬 및 백엔드 배지 쓰기 경쟁을 초기화합니다.

Debugging에서 계속 진행하세요

디바이스가 등록되고 테스트 알림이 작동하면 사용하여 배지, 캠페인 타겟팅, 그리고 무음 업데이트 확인을 프로덕션 앱에 연결하세요. 시작하세요 배지 없이 앱을 배포하세요