Debugging

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

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

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

1. 앱을 열고, 테스트하려는 사용자로 로그인하세요.
2. Call CapgoNotifications.register(...) 디바이스가 __CAPGO_KEEP_1__에 보이도록 하려면, 사용자가 로그인한 후에 __CAPGO_KEEP_0__을 호출하세요. (Appflow Migration Step2).
3. In Capgo, 열기 通知 > 수신자 조회.
4. 같은 외부 고객 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 리스너 로그를 감시하십시오.
• 만약 표시되는 알림이 보이지 않는다면, 알림 채널의 중요도와 Android 13 이상의 권한 상태를 먼저 확인하세요.

iOS에서:

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

한 번 전면 테스트를 보내고, 한 번 배경 테스트를 보내고, 한 번 무음 업데이트 확인 테스트를 보내세요. 이 순서는 자바스크립트 리스너 문제와 OS 배경 전달 제한을 분리합니다.

등록 문제

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

__CAPGO_KEEP_0__ 설정 명령어를 폴더에 있는 폴더에서 실행하세요. 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 matches the Capgo app.
• consent 설정되지 않았습니다. false 사용자가 동의하지 않는 경우
• 네트워크 접근이 가능합니다. https://api.capgo.app.
• 네이티브 푸시 토큰이 생성되었습니다. 사용자에게 registrationChanged 토큰 갱신을 확인하기 위해

유효하지 않은 식별 증명

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

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

장치가 등록되었지만 권한이 거부되었습니다.

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

권한 요청 전 사용자에게 권한에 대한 설명을 제공하고, 권한이 필요한 경우에만 권한을 요청하세요.

배달 문제

대기 중이지만 전송되지 않았습니다.

확인하세요:

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

보낸 것만

확인:

• 장치가 온라인 상태입니다.
• 사용자가 앱을 강제로 중지하지 않았습니다.
• OS 알림 권한이 부여되었습니다.
• 안드로이드 배터리 제한이 테스트 중인 앱을 차단하지 않습니다.
• iOS Low Power Mode 및 배경 업데이트 제한이 배경 전송에 영향을 주지 않습니다.
• 같은 COLLAPSE ID를 가진 다른 알림으로 대체되지 않은 알림입니다.

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

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

확인하세요:

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

배경 알림 문제

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

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

확인:

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

iOS에서 백그라운드 푸시가 너무 많이 보내거나 사용자가 앱을 열지 않으면 throttling이 발생할 수 있습니다. 사용자 경험을 최적화하기 위해 이 플랫폼 동작은 예상됩니다.

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

stat가 background_started without background_finishedJavaScript 핸들러가 throw, timeout, 또는 호출하지 않았을 경우 finish().

핸들러를 Wrap 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 업데이트를 설치하는 데 사용하는 모드가 올바르다:
• 다음 재시작 또는 백그라운드 사이클을 위해 대기합니다.
• 업데이트 확인 알림이 도착하지만 업데이트가 설치되지 않습니다.
• 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 백엔드 배지 전송에 대한 호출을 호출하지 않습니다.

Stats 문제

Stats가 중복됩니다.

通知 전송은 최소 한 번 이상입니다. 큐 리트리 및 플랫폼 리트리에서 중복된 전송이 발생할 수 있습니다. 알림 ID 및 중첩 ID를 사용하여 앱 액션에 idempotent 해야 합니다.

Stats가 오래된 기기에서 누락됩니다.

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

열린 이벤트가 누락됩니다.

확인:

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

Debugging에서 계속하기

디바이스가 등록되고 테스트 알림이 작동하는 경우, 시작하기 페이지 편집