디버깅

GitHub

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 지시를 복사합니다.

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

기기 기록으로 시작하세요

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

앱을 열고 테스트하려는 사용자로 로그인하세요.
로그인 후 __CAPGO_KEEP_0__에서 CapgoNotifications.register(...) 通知 > 수신자 조회
In Capgo, open 콜.
로그인 후

You should see at least one active device with: __CAPGO_KEEP_0__

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

사용자에게 해당하는 디바이스가 없으면, send path를 사용할 수 없습니다.

임시 디버그 리스너 추가

테스트 중에는 임시 리스너를 추가하고, 배포 전에는 노이즈가 많은 로그를 제거하세요.

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.
앱이 전면, 후면, 강제 종료, 또는 새로 설치된 상태였는지 여부.
실행 중인 문제를 재현한 실행의 장치 로그.

Device Logs를 사용하세요.

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

Android:

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

iOS:

Xcode에서 실제 장치에서 앱을 실행하세요.
Open the Xcode console or 장치 및 시뮬레이터 로그.
__CAPGO_KEEP_0__ ID를 사용하여 필터링하고 CapgoNotifications.
확인 AppDelegate.swift 배경 모드 기능이 활성화된 것을 확인하고,

foreground test를 먼저 한 후 background test, silent update-check test 순서로 테스트를 진행하세요. 이 순서는 JavaScript listener 문제와 OS 배경 전달 제한을 분리합니다.

등록 문제

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

설정 명령어를 __CAPGO_KEEP_0__가 포함된 폴더에서 실행하세요. capacitor.config.*:

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

명령어에서 앱 ID를 명시적으로 지정하십시오. 패키지 설치가 실패한 경우 Capgo가 npm 계정의 개인 미리보기 패키지 접근을 활성화했는지 확인한 후 명령어를 다시 실행하십시오.

기기 검색자에서 기기가 나타나지 않습니다.

확인하기

register 앱이 인증된 사용자를 가지고 있는 경우에 호출됩니다.
externalId 검색한 사용자 ID와 일치합니다.
identityProof 백엔드에서 동일한 __CAPGO_KEEP_0__ 앱으로 생성되었습니다. appId 그리고 externalId.
appId __CAPGO_KEEP_0__ 앱과 일치합니다. configure Capgo 앱과 일치합니다.
consent __CAPGO_KEEP_0__이 설정되지 않았습니다. false 사용자가 옵트아웃하지 않은 경우.
__CAPGO_KEEP_0__이 네트워크 접근을 지원합니다. https://api.capgo.app.
자연스러운 푸시 토큰이 생성되었습니다. 사용자는 registrationChanged 토큰 갱신을 확인하기 위해

인증 증명서가 유효하지 않습니다.

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

증명서를 영원히 캐시하지 마세요. 또는 앱 간에 증명서를 재사용하지 마세요. 백엔드에서 로그인 후 증명서를 생성하고 앱으로 반환한 후 register.

__CAPGO_KEEP_0__이 등록되었지만 권한이 거부되었습니다.

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

__CAPGO_KEEP_0__

사용자에게 권한 설명 화면을 OS 프롬프트 이전에 사용하세요. 사용자가 무엇을 받을지 설명하고, 액션의 의미가 있는 경우에만 권한을 요청하세요.

배달 문제

플랫폼 인증 정보 상태는

__CAPGO_KEEP_0__ configured in Capgo.
앱의 패키지 ID 또는 번들 ID가 플랫폼 푸시 설정과 일치합니다.
목표 аудiences는 적어도 하나의 활성 장치로 연결됩니다.
캠페인은 장치가 갖지 않는 태그 또는 세그먼트에 제한되지 않습니다.
The campaign is not limited to a tag or segment the device does not have.

받은 편지지만 받지 못한 편지

체크:

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

자연스러운 푸시 플랫폼은 알림을 수락하고 나중에 지연, 속도 제한, 집합, 또는 배달을 취소할 수 있습니다. 제공자 수락 통계를 ‘배달 준비’로 간주하십시오. 이는 장치가 알림을 표시했다는 증거가 아닙니다.

받은 편지지만 표시되지 않은 편지

Check:

앱이 전면에 표시되지 않았습니다. 일반적으로 JavaScript에서 전면 알림을 받고, 앱이 표시할 UI를 결정할 수 있습니다.
Android 알림 채널 중요도가 충분히 높아 알림을 표시할 수 있습니다.
Android 13 이상의 알림 권한이 승인되었습니다.
iOS Focus, 알림 요약, 또는 앱별 알림 설정이 알림을 숨기지 않습니다.
배지 클리어링 또는 앱 열기 로직이 테스트 중에 전달된 알림을 제거하지 않습니다.

배경 알림 문제

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

배경 알림은 최적의 시도가 아닙니다. OS는 그들을 건너뛸 수 있습니다.

Check:

iOS는 Background Modes > Remote notifications 이용 가능합니다.
iOS AppDelegate.swift 원격 알림을 CapgoNotificationsRemoteNotification.
iOS 백그라운드 동작을 테스트하려면 실제 기기를 사용하세요.
사용자가 앱을 강제 종료하지 않았습니다.
백그라운드 핸들러가 호출됩니다. finish().
콜백 내에서 작업은 짧고 네트워크 안전하며 idempotent합니다.

iOS에서 백그라운드 푸시가 너무 많이 보내거나 사용자가 앱을 거의 열지 않으면, 또는 사용자에게 앱을 열지 않도록 요청할 때, 푸시가 제한될 수 있습니다. 이는 플랫폼의 예상 동작입니다.

백그라운드 시작되지만 완료되지 않았습니다.

If statistics show background_started without background_finished, the JavaScript handler likely threw, timed out, or did not call finish().

Wrap the handler in try/finally:

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

silent update check 문제

update check notification이 도착했지만 업데이트가 설치되지 않습니다.

Check:

@capgo/capacitor-updater is installed and configured.
autoUpdater is installed and configured. true or enableUpdaterIntegration was called.
앱의 알림 설정은 푸시 업데이트를 확인합니다.
기대하는 채널에 속한 대상 기기는 있습니다.
Capgo에 있는 최신 배포본이 앱에 있습니다.
업데이트 설치 모드가 올바릅니다: next 다음 재시작 또는 백그라운드 사이클을 위해 대기합니다. set 업데이터가 안전하게 업데이트를 설치할 수 있는 즉시 설치합니다.

앱이 열려 있는 동안 수동 확인을 실행하세요.

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

console.log(result)

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

Badge Problems

확인:

__CAPGO_KEEP_0__은 수신자 조회에서 올바른 장치로 결론지어집니다.
__CAPGO_KEEP_0__은 런처 또는 홈 스크린을 테스트하는 앱 배지에 대한 지원을 제공합니다.
__CAPGO_KEEP_0__은 OS 알림 설정에서 배지를 비활성화하지 않았습니다.
__CAPGO_KEEP_0__은 앱이 시작 시 바로 배지를 지웁니다.
__CAPGO_KEEP_0__은 로컬에서 백엔드 배지 전송에 대한 호출을 경쟁하지 않습니다. setBadge calls against backend badge sends.

Stats Problems

섹션 제목 “문제”입니다.

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

오래된 기기용 통계가 누락되었습니다

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

열린 이벤트가 누락되었습니다

확인:

알림에는 안정적인 id.
notificationOpened 리스너는 앱 시작 시 등록됩니다.
앱은 플러그인이 알 수 있는 전에 네이티브 오픈 플로우를 커스텀 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` __CAPGO_KEEP_0__
권한이 거부됨	OS 프롬프트가 거부되거나 아직 요청되지 않았습니다.
대기 중이지만 전송된 통계가 없습니다.	플랫폼 인증 정보가 누락되거나 비활성화되었습니다.
전송된 통계가 있지만 수신된 통계가 없습니다.	장치가 오프라인 상태, OS가 제한을 걸었거나 앱이 강제 종료되거나 토큰이 유효하지 않습니다.
전경 알림 로그가 있지만 배너가 없습니다.	앱이 전면화되어 자신의 내부 UI를 보여야 합니다.
iOS에서 배경이 실행되지 않습니다.	미리 보기 기능이 없거나 AppDelegate 전달이 실패하거나 앱을 강제 종료하거나 OS가 앱을 제한합니다.
업데이트 확인이 아무런 효과가 없습니다.	업데이트 통합이 비활성화되었습니다. 최신 버전이 없거나 채널이 잘못되거나 설치 모드가 잘못되었습니다.
배지 초기화	앱이 시작될 때 code 배지 또는 로컬 및 백엔드 배지 쓰기 경쟁을 초기화합니다.

Debugging에서 계속하기

등록이 완료되고 테스트 알림이 작동한 후 Getting Started 을 사용하여 배지, 캠페인 타겟팅 및 무음 업데이트 확인을 프로덕션 앱에 연결하세요.