Debugging

GitHub

이 플러그인에 대한 설치 단계와 전체 마크다운 가이드를 포함한 설정 지시를 복사하세요.

알림이 등록되지 않거나, 도착하지 않거나, 표시되지 않거나, 또는 Capgo 통계가 업데이트되지 않을 때 사용하는 체크리스트입니다.

디바이스 레코드에서 시작하세요

자연 code 디버깅을 시작하기 전에, Capgo이 디바이스를 볼 수 있는지 확인하세요.

앱을 열고 테스트하려는 사용자로 로그인하세요.
로그인 후에 호출하세요. CapgoNotifications.register(...) appflow_migration_step2
In Capgo, 열기 Notifications > 수신자 조회.
외부 고객 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 그리고 deviceKey 등록 또는 수신자 조회에서.
캠페인 ID 또는 알림 ID.
앱이 전면, 후면, 강제 종료, 또는 새로 설치된 상태였는지 여부.
문제를 재현한 실행에서 장치 로그.

장치 로그 사용

실제 장치 하나를 연결하여 테스트 알림을 보내십시오.

Android:

Android Studio Logcat 열기.
앱 패키지 ID로 필터링.
알림 권한 요청, 네이티브 토큰 갱신, 메시지 수신, JavaScript 리스너 로그를 감시하십시오.
visible 알림이 표시되지 않으면, 알림 채널 중요도와 Android 13 이상의 권한 상태를 먼저 확인하세요.

iOS 에서:

Xcode에서 실제 기기에서 앱을 실행하세요.
Xcode 콘솔 또는 기기 및 시뮬레이터 로그를 열어보세요.
ID 패키지를 필터링하고 CapgoNotifications.
확인 AppDelegate.swift remote 알림이 전달되고 배경 실행 모드 기능이 활성화되어 있는지 확인하세요.

Foreground 테스트 한 번 보냈으면, Background 테스트 한 번 보냈으면, Silent 업데이트 확인 테스트 한 번 보냈으면. 이 순서로 JavaScript 리스너 문제와 OS 배경 전달 제한을 구분할 수 있습니다.

등록 문제

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

__CAPGO_KEEP_0__ 설정을 시작하기 위해 폴더 내에서 명령어를 실행하세요. capacitor.config.*:

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

명령어가 앱 ID를 자동으로 인식하지 못할 경우 명시적으로 입력하세요. 패키지 설치가 실패한 경우 Capgo이 사용자의 npm 계정에 대해 개인 프리뷰 패키지 접근 권한을 활성화했는지 확인한 후 다시 명령어를 실행하세요.

받는 사람 검색 목록에 기기 정보가 나타나지 않습니다.

확인하세요:

register 앱이 인증된 사용자를 가지고 있는지 확인하세요.
externalId 검색한 사용자 ID가 대시보드에 일치하는지 확인하세요.
identityProof 백엔드에서 동일한 사용자 ID를 위한 토큰을 발급했는지 확인하세요. appId 그리고 externalId.
appId 속 configure Capgo 앱과 일치합니다.
consent __CAPGO_KEEP_0__이 설정되지 않았습니다. false __CAPGO_KEEP_0__이 설정되지 않은 경우
장치가 네트워크 접근 권한을 가지고 있습니다. https://api.capgo.app.
네이티브 푸시 토큰이 생성되었습니다. 사용 registrationChanged 토큰 갱신을 확인하기 위해

유효하지 않은 신원 증명

증명은 Capgo 앱 ID와 외부 ID와 결합되어 있습니다. 둘 중 하나의 값이 변경되면 새로운 증명이 생성됩니다.

증명을 영원히 캐시하지 마십시오. 또는 앱 간에 증명을 재사용하지 마십시오. 로그인 후 백엔드에서 증명을 생성하고 앱에 반환한 후 호출하십시오. register.

기기 등록되지만 권한 거부됨

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

OS의 권한 요청 전에 사용자에게 권한 설명 화면을 제공하세요. 사용자가 얻을 수 있는 것을 설명하고, 액션의 의미가 있는 경우에만 권한을 요청하세요.

배달 문제

보관 중이지만 전송되지 않음

체크:

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

보낸 건 받은 건 아님

확인:

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

원본 푸시 플랫폼은 알림을 수락할 수 있지만 나중에 지연, 제한, 집계, 또는 배달을 취소할 수 있습니다. 제공자 수락 통계를 '배달 준비'로 처리하십시오. 이는 장치가 알림을 표시했다는 증명이 아닙니다.

받은 알림이 표시되지 않음

확인:

앱이 전면에 표시되지 않았습니다. 전면 알림은 일반적으로 JavaScript로 전달되어 앱이 표시할 UI를 결정할 수 있도록 합니다.
Android 알림 채널 중요도가 표시 알림을 표시하기에 충분합니다.
Android 13 이상 알림 권한이 부여되었습니다.
iOS 초점, 알림 요약, 또는 앱별 알림 설정이 알림을 숨기지 않습니다.
배지 지우기 또는 앱 열기 논리가 테스트 중에 배달된 알림을 제거하지 않습니다.

배경 알림 문제

배경 콜백이 실행되지 않음

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

Check:

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

iOS에서 백그라운드 푸시가 너무 많이 보냈거나 사용자가 앱을 거의 열지 않거나 시간이 너무 많이 걸렸을 때, 푸시가 제한될 수 있습니다. 이는 기기 운영 체제의 예상 동작입니다.

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

stat가 표시되면 background_started 없다면 background_finishedJavaScript 핸들러가 예외를 발생시키거나 시간이 초과되거나 호출되지 않았을 가능성이 있습니다. finish().

핸들러를 Wrap 하세요 try/finally:

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

silent 업데이트 체크 문제

silent 업데이트 체크 알림이 도착했지만 업데이트가 설치되지 않음

확인:

@capgo/capacitor-updater 설치 및 설정이 완료되었습니다.
autoUpdater 또는 true 또는 enableUpdaterIntegration 또는
또는
또는
The app has a newer bundle available in Capgo.
또는 next 또는 set 또는

또는

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

console.log(result)

수동 확인이 반환하는 경우 unavailable, 업데이트 플러그인 설정을 먼저 확인하세요.

배지 문제

확인:

수신자 검색에서 올바른 기기를 참조하는 대상이 되는지 확인합니다.
테스트 중인 런처 또는 홈 스크린의 배지를 지원하는 플랫폼이 있는지 확인합니다.
사용자가 OS 알림 설정에서 배지를 비활성화하지 않았는지 확인합니다.
앱이 시작 시 바로 배지를 지우지 않는지 확인합니다.
당신은 로컬 호출과 백엔드 배지 전송을 경쟁하지 않는지 확인합니다. setBadge 배지 문제

통계 문제

통계가 중복되는 문제

알림 전송은 최소 한번 이상입니다. 큐 리트리 및 플랫폼 리트리 등으로 중복된 전송이 발생할 수 있습니다. 알림 ID 및 중첩 ID를 사용하여 앱 동작이 idempotent 해야 합니다.

기존 기기에서 통계가 누락되는 문제

분석 엔진 레지스트리는 활성 기기만을 위한 것입니다. 영구 데이터베이스가 아닙니다. 플러그인은 앱 시작, 토큰 갱신, 외부 ID 변경, 활성 기기 보존 기간 전까지 주기적으로 등록을 갱신해야 합니다.

열린 이벤트가 누락되는 문제

확인하세요:

안정적인 id.
notificationOpened 리스너는 앱 시작 시 등록됩니다.
앱은 플러그인이 이를 볼 수 있도록 커스텀 code를 native open flow와 교체하지 않습니다.
사용자가 실제로 알림을 탭했으며 앱을 수동으로 열지 않았습니다.

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에서 계속 진행하세요

기기 등록 후 테스트 알림이 작동하면 사용 시작하기 배지, 캠페인 타겟팅 및 무음 업데이트 확인을 프로덕션 앱에 통합하는 방법을 알아보세요.