디버깅

GitHub

설치

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

기기 기록에서 시작하세요

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

앱을 열고 __CAPGO_KEEP_1__으로 로그인하세요.
로그인 후 CapgoNotifications.register(...) __CAPGO_KEEP_0__에서 열어보세요.
Capgo에서 열어보세요. Notifications > 수신자 조회.
같은 외부 고객 ID로 검색하세요.

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

recipientKey
deviceKey
플랫폼 android 또는 ios
페이지/영역: Consulting 서비스 페이지. 역할: 섹션 서브 타이틀 또는 태그 라인. 본문 키: consulting_faq_subtitle. 보존: Capgo 제품/브랜드 및 개발자 용어.
권한 상태
앱 버전
플러그인 버전

태그 및 속성

조회 결과가 장치가 없으면, 보낸 경로가 그 사용자를 대상으로 할 수 없습니다.

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

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로 필터링.
알림 권한 요청, 네이티브 토큰 갱신, 메시지 수신, 자바 스크립트 리스너 로그를 감시하십시오.
visible 알림이 나타나지 않으면, 알림 채널 중요도 및 Android 13+ 권한 상태를 먼저 검사하십시오.

iOS에서:

Xcode에서 실제 기기에서 앱을 실행하세요.
Xcode 콘솔 또는 기기 및 시뮬레이터 로그.
애플리케이션 ID로 필터링하고 CapgoNotifications.
확인 AppDelegate.swift 전경 테스트를 한 번 보내고, 배경 테스트를 한 번 보내고, 무음 업데이트 확인 테스트를 한 번 보내세요. 이 순서는 자바스크립트 리스너 문제와 OS 배경 전달 제한을 구분합니다.

등록 문제

CLI 설치가 완료되지 않았습니다.

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

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

페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: 페이지 에이전트/[슬러그].astro. 메시지 키 `agents_page_copy_label` (에이전트 페이지 복사 레이블). @capgo/capacitor-notifications명령어에서 앱 ID를 암시적으로 추론할 수 없다면 명시적으로 전달하세요. 패키지 설치가 실패하면 패키지 이름을 확인하세요. npm 레지스트리가 올바른지 확인하세요. https://registry.npmjs.org네트워크 접근이 가능하다면 명령어를 다시 실행하세요.

수신자 검색 목록에 기기 표시되지 않음

확인하세요:

register 앱이 인증된 사용자를 가지고 있는 후에 호출됩니다.
externalId 사용자 ID가 수신자 검색 목록에 일치하는지 확인하세요.
identityProof 백엔드에서 동일한 것으로 생성되었습니다. appId 그리고 externalId.
appId in configure Capgo 앱과 일치합니다.
consent 사용자가 동의하지 않은 경우 false 네트워크 접근이 있습니다.
네이티브 푸시 토큰이 생성되었습니다. 사용자에게 토큰 갱신을 확인하세요. https://api.capgo.app.
인증 정보가 유효하지 않습니다. registrationChanged 인증 정보는 __CAPGO_KEEP_0__ 앱 ID와 외부 ID와 결합되어 있습니다. 둘 중 하나의 값이 변경되면 새로운 인증 정보를 생성하세요.

The proof is bound to the __CAPGO_KEEP_0__ app ID and external ID. If either value changes, mint a new proof.

증명은 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합니다.

iOS에서 배경 푸시가 너무 많이 보내거나 사용자가 앱을 거의 열지 않거나 시간이 너무 많이 걸리면 푸시가 제한될 수 있습니다. 이는 예상되는 플랫폼 동작입니다.

배경 시작되지만 완료되지 않음

배경 시작되지만 완료되지 않음 background_started stat가 background_finished없다면 finish().

JavaScript 핸들러가 예외를 발생시키거나 시간 초과되거나 호출되지 않았을 가능성이 있습니다. try/finally:

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

클립보드 복사

silent 업데이트 확인 문제

확인:

@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

알림 전송은 최소한 한번 이상입니다. 큐 리트리 및 플랫폼 리트리 등으로 중복된 전송이 발생할 수 있습니다. 알림 ID 및 중첩 ID를 사용하여 앱 액션에 대해 idempotent 하게 하십시오.

오래된 기기에서 Stats가 누락되어 있습니다

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

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

확인하십시오

通知에는 안정적인 id.
notificationOpened 앱 시작 시 리스너가 등록됩니다.
code는 플러그인이 native open flow를 대체하기 전에 앱이 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'

Foreground 테스트 보내기:

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" }
    }
  }'

페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).

일반적인 원인	증상
가능한 원인	`register` 장치가 조회에서 누락됨
호출되지 않음, 증명 불일치, 동의 거부, 앱 ID 불일치.	권한이 거부됨
OS 프롬프트 거부되거나 아직 요청되지 않았습니다.	플랫폼 인증 정보가 누락되거나 비활성화되었습니다.
보낸 통계는 받은 통계가 없습니다.	디바이스가 오프라인 상태, OS가 속도 제한을 걸었거나, 앱이 강제 종료되거나, 토큰이 유효하지 않습니다.
전경 알림이 로그되지만 배너는 없습니다.	앱이 전경화되어야 하며, 자신의 내 앱 UI를 보여야 합니다.
iOS에서 배경이 실행되지 않습니다.	필요한 기능이 누락되거나, AppDelegate 전달이 누락되거나, 앱이 강제 종료되거나, OS 속도 제한이 걸렸습니다.
업데이트 체크는 아무것도 하지 않습니다.	업데이터 통합이 비활성화되거나, 최신 배포본이 없거나, 채널이 잘못되거나, 설치 모드가 잘못 이해되었습니다.
배지 초기화	앱 시작 시 code 배지 또는 로컬 및 백엔드 배지 쓰기 경쟁을 초기화합니다.

디버깅에서 계속 진행하세요.

디바이스가 등록되고 테스트 알림이 작동하는 경우 시작하기 배포 앱에 배지, 캠페인 타겟팅 및 무음 업데이트 확인을 연결하세요.

context: Capgo 마케팅 웹사이트. 역할: 웹사이트 복사 문장. 표시되는 곳: component doc/SignupCta.astro, component Hero.astro. 메시지 키 `hero_subtitle_v2` (Hero Subtitle V2). 무료로 시작하세요