Debugging

GitHub

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

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

디바이스 기록에서 시작하세요

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

앱을 열고 테스트하려는 사용자로 로그인하세요.
Call CapgoNotifications.register(...) context: Capgo UI의 더 긴 문자열에서 HTML 텍스트 조각 (부모 키 `appflow_migration_step2`). 페이지/영역: Appflow 비교/이동 마케팅 복사본. 역할: 웹사이트 복사본 문장. 페이지: ionic-appflow.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지하세요. 메시지 키 `appflow_migration_step2` (Appflow Migration Step2).
Capgo에서 열기 通知 > 수신자 조회.
외부 고객 ID와 같은 검색

적어도 하나의 활성 장치가 다음과 같이 표시되어야 합니다:

recipientKey
deviceKey
플랫폼 android 또는 ios
다른 플러그인과 비교할 때, __CAPGO_KEEP_0__은
권한 상태
앱 버전
플러그인 버전

태그 및 속성

수신자 조회가 장치가 없으면, 보낼 경로가 해당 사용자를 대상으로 할 수 없습니다.

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

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()
})

정보 수집

When debugging with your team or Capgo support, collect:

Capgo 앱 ID.
앱 패키지 ID 또는 iOS 번들 ID.
디바이스 플랫폼 및 OS 버전.
앱 버전 및 빌드 번호.
플러그인 버전.
외부 고객 ID.
recipientKey 그리고 deviceKey 등록 또는 수신자 검색에서.
캠페인 ID 또는 알림 ID.
앱이 전면, 배경, 강제 종료, 또는 새로 설치된 경우 여부.
문제를 재현한 실행의 장치 로그.

장치 로그 사용

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

Android:

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

On iOS:

Xcode에서 실제 기기에서 앱을 실행하세요.
Xcode 콘솔 또는 Devices and Simulators 로그를 필터링하세요.
Bundle ID를 확인하세요. CapgoNotifications.
확인 AppDelegate.swift remote 알림이 전송되고 배경 실행 모드 기능이 활성화되어 있는지 확인하세요.

foreground 테스트를 먼저 보내고, 그 다음 background 테스트를 보내고, 그 다음 silent 업데이트 확인 테스트를 보내세요. 이 순서는 JavaScript 리스너 문제와 OS 배경 전달 제한을 구분합니다.

등록 문제

CLI Setup Did Not Finish

__CAPGO_KEEP_0__ Setup Did Not Finish capacitor.config.*:

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

명령어를 실행할 때 앱 ID를 명시적으로 지정해야 하는 경우, 위와 같이 지정하십시오. 패키지 설치가 실패하는 경우, Capgo이 npm 계정의 비공개 프리뷰 패키지 접근을 활성화했는지 확인한 후 명령어를 다시 실행하십시오.

Device Does Not Appear In Recipient Lookup

확인하십시오:

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는 그들을 건너뛸 수 있습니다.

확인:

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

On 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 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 calls against backend badge sends.

통계 문제

통계가 중복됩니다.

알림 전송은 최소 한번 이상입니다. 큐 리트리 및 플랫폼 리트리 등으로 중복 전송이 발생할 수 있습니다. 알림 ID 및 중첩 ID를 사용하여 앱 동작이 중복되지 않도록 하세요.

기존 기기에서 통계가 누락됩니다.

분석 엔진 레지스트리는 활성 기기만을 위한 것입니다, 영구 데이터베이스가 아닙니다. 플러그인은 앱 시작, 토큰 갱신, 외부 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` 호출되지 않음, 증명 불일치, 동의 거부, 앱 ID 불일치.
권한이 거부됨	OS 명령 프롬프트가 거부되거나 아직 요청되지 않았습니다.
대기 중이지만 전송된 통계가 없습니다	플랫폼 인증 정보가 누락되거나 비활성화되었습니다.
보내졌으나 수신 통계가 없습니다	장치가 오프라인 상태, OS가 속도 제한을 걸었거나, 앱이 강제 종료되거나, 토큰이 유효하지 않습니다.
전경 알림 로그가 있지만 배너는 없습니다	앱이 전경화되어야 하며, 자신의 내부 UI를 보여주어야 합니다.
iOS에서 백그라운드가 절대 실행되지 않습니다	미리 설치된 기능이 없거나, AppDelegate 전달이 없거나, 앱을 강제 종료하거나, OS 속도 제한이 걸렸습니다.
업데이트 확인이 아무런 일도 하지 않습니다	업데이터 통합이 비활성화되거나, 최신 버전이 없거나, 채널이 잘못되거나, 설치 모드가 잘못 이해되었습니다.
배지 초기화	앱 시작 시 code 배지 또는 로컬 및 백엔드 배지 쓰기 경쟁을 초기화합니다.

Debugging에서 계속 진행하세요

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