시작하기

@capgo/capacitor-notifications 는 iOS 및 Android 네이티브 푸시 알림을 위한 퍼스트파티 Capgo 플러그인입니다. Capgo 대시보드, 공개 API, Analytics Engine 디바이스 레지스트리, 캠페인 통계, 배지 업데이트, silent Live Update 확인을 위해 만들어졌습니다.

요구 사항

• Capgo에 이미 추가된 Capacitor 앱.
• Capgo 앱의 Notifications 탭에 접근할 수 있는 권한.
• 백엔드 proof minting 및 API 전송을 위한 쓰기 권한이 있는 Capgo API 키.
• 앱의 iOS 및/또는 Android 플랫폼 푸시 권한.
• @capgo/capacitor-updater silent push 업데이트 확인을 원하는 경우.

빠른 시작

import { CapacitorNotifications } from '@capgo/capacitor-notifications';
await CapacitorNotifications.register({ customerUserId: 'signed-id' });

자주 하는 실수

• 백엔드에서 생성한 서명된 customerUserId 값을 사용하세요.
• 등록하기 전에 알림 권한을 요청해야 합니다.
• 대시보드에서 Capgo 자격 증명을 확인하세요.

1. Capgo 플랫폼 자격 증명 설정

Capgo에서 앱을 연 다음, 알림.

지원할 각 플랫폼마다 플랫폼 credential 항목을 하나씩 추가하세요:

• Android - 앱 패키지 ID와 Android 푸시 프로젝트 메타데이터.
• iOS - bundle ID, team ID, key ID와 이에 맞는 iOS 푸시 키 메타데이터.

Capgo은 플랫폼이 구성된 것으로 표시되기 전에 API worker에 반드시 있어야 하는 정확한 환경 secret 이름을 보여줍니다. 대시보드는 메타데이터와 예상 secret 참조를 저장합니다. private credential 자체는 worker 환경에 남습니다.

2. 설치

가장 빠르게 설정하려면 앱 프로젝트에서 Capgo CLI 명령을 실행하세요:

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

이 명령은 notification 패키지를 설치하고, Capacitor 플러그인 설정을 저장하며, 작은 헬퍼 파일을 생성하고, Capacitor sync를 실행합니다. 모든 파일을 수동으로 연결할 필요가 없다면 새 앱에는 이 방식을 사용하세요.

수동 설치:

bun add @capgo/capacitor-notifications @capgo/capacitor-updater
bunx cap sync

silent Capgo update check를 사용하지 않는다면, 다음 항목은 생략할 수 있습니다: @capgo/capacitor-updater.

3. 플러그인 설정

앱이 시작될 때 플러그인을 한 번만 설정하세요.

import { CapgoNotifications } from '@capgo/capacitor-notifications'

await CapgoNotifications.configure({
  appId: 'com.example.app',
  autoUpdater: true,
  updateInstallMode: 'next',
})

사용 updateInstallMode: 'next' 업데이트를 다운로드한 뒤 다음 재시작 또는 백그라운드 사이클에서 설치하려면 다음을 사용하세요. updateInstallMode: 'set' 업데이터가 안전하게 수행할 수 있는 즉시 Capgo가 업데이트를 설치하도록 하려면 이 옵션을 사용하세요.

4. Identity Proof 발급

Capgo API 키를 모바일 앱에 넣지 마세요. 백엔드는 Capgo에 identityProof 자체 사용자 인증이 성공한 후 요청해야 합니다.

curl -X POST 'https://api.capgo.app/notifications/recipients/proof' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

이를 identityProof 자체 세션 응답과 함께 앱으로 반환하세요.

5. 디바이스 등록

로그인한 고객 사용자가 누구인지 확인한 후에만 등록하세요.

const registration = await CapgoNotifications.register({
  externalId: 'customer-user-123',
  identityProof,
  tags: ['paid', 'beta'],
  attributes: {
    plan: 'team',
    locale: 'en-US',
  },
  consent: true,
})

console.log(registration.recipientKey, registration.deviceKey)

호출하세요 register 다음 상황에서 다시 실행됩니다:

• 앱이 시작될 때.
• 네이티브 푸시 토큰이 변경될 때.
• 로그인된 사용자가 변경될 때.
• 태그, 속성 또는 동의 설정이 변경될 때.
• 앱의 등록 정보가 오랫동안 갱신되지 않았을 때.

6. 이벤트 리스너 추가

앱 시작 시 리스너를 등록하여 foreground, opened, background 이벤트를 JavaScript에서 감지할 수 있도록 합니다.

await CapgoNotifications.addListener('registrationChanged', () => {
  void CapgoNotifications.register({
    externalId: currentUser.id,
    identityProof: currentUser.capgoNotificationProof,
    tags: currentUser.notificationTags,
    consent: currentUser.pushConsent,
  })
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('Notification received', notification)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('Notification opened', event.notification.id)
})

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

항상 호출하세요 finish() 작업 완료 후 백그라운드 알림을 처리합니다. 작업은 짧고 멱등성(idempotent)을 유지해야 합니다.

7. iOS 설정

Xcode에서 앱 타겟을 열고 다음을 활성화하세요:

• 푸시 알림
• Background Modes > 원격 알림(Remote notifications)

다음에서 원격 알림을 전달하세요: ios/App/App/AppDelegate.swift:

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    NotificationCenter.default.post(name: Notification.Name("CapgoNotificationsRemoteNotification"), object: userInfo)
    completionHandler(.newData)
}

그런 다음 실행하세요:

bunx cap sync ios

백그라운드 알림을 테스트할 때는 실제 iOS 기기를 사용하세요. 시뮬레이터는 UI 작업에는 유용하지만, 프로덕션 백그라운드 푸시 동작을 반영하지는 않습니다.

8. Android 설정

실행:

bunx cap sync android

다음 사항을 확인하세요:

• Capgo에 Android 플랫폼 자격 증명이 설정되어 있는지 확인합니다.
• 앱 패키지 ID가 플랫폼 푸시 설정에 사용된 패키지 ID와 일치하는지 확인합니다.
• 알림이 표시되기 전에 Android 13+ 알림 권한을 요청하는지 확인합니다.
• 앱에 브랜드 이미지와 일치하는 알림 아이콘 및 채널 전략이 있는지 확인합니다.
• 실제 기기 또는 Google Play services가 설치된 에뮬레이터에서 테스트합니다.

앱 시작 시 기본 Android 채널을 생성합니다:

await CapgoNotifications.configure({ appId: 'com.example.app' })

await CapgoNotifications.register({
  externalId: currentUser.id,
  identityProof: currentUser.capgoNotificationProof,
  consent: true,
})

이 플러그인은 Android 푸시 메시징 서비스를 선언합니다. 앱 백업, 데이터 추출, 네트워크 보안, 알림 아이콘 정책은 호스트 앱에 그대로 두세요.

9. 테스트 알림 전송

사용 Notifications > 테스트 전송 Capgo에서 실행하거나, 백엔드에서 공개 API을 호출하세요:

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": "Hello from Capgo",
      "body": "This is a test notification.",
      "data": { "screen": "inbox" }
    }
  }'

캠페인은 대시보드에서 생성하거나, 다음을 호출하세요: /notifications/campaigns, 그런 다음 외부 ID, 태그, 세그먼트 또는 브로드캐스트 대상으로 전송하세요.

10. 배지 설정

await CapgoNotifications.setBadge(4)
await CapgoNotifications.incrementBadge()
await CapgoNotifications.clearBadge()

백엔드에서:

curl -X POST 'https://api.capgo.app/notifications/badge' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "badge": 4
  }'

11. Silent Update 확인 활성화

Silent update checks를 통해 이 플러그인을 다음 항목과 연결합니다: @capgo/capacitor-updater.

앱에서:

await CapgoNotifications.enableUpdaterIntegration({
  enabled: true,
  installMode: 'next',
})

Capgo에서 다음을 활성화하세요: 사용자에게 업데이트 푸시 앱의 Notifications 설정에서 활성화합니다. 그 다음 대시보드나 API에서 업데이트 체크를 전송하세요:

curl -X POST 'https://api.capgo.app/notifications/update-check' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "installMode": "next"
  }'

알림은 무음이고 collapse ID를 사용하므로, 플랫폼이 collapse 동작을 지원하면 반복되는 업데이트 확인 알림이 서로 대체됩니다.

검증 체크리스트

• Capgo 수신자 조회에서 앱이 예상되는 대상으로 나타납니다. externalId.
• 권한 상태는 granted 또는 사용자가 알림 권한을 허용했습니다.
• 등록된 플랫폼은 android 또는 ios.
• registrationChanged 토큰 갱신 후 발생합니다.
• 포그라운드 테스트에서 로그를 기록합니다. notificationReceived.
• 알림 로그 확인하기 notificationOpened.
• 대시보드 통계에는 대기 및 전송된 이벤트가 표시되며, 기기에서 보고하면 수신/열람 상태로 업데이트됩니다.
• Silent update 체크 로그 결과는 runUpdateCheck 또는 updater 통합 환경에서 확인 가능합니다.

시작하기 다음 단계

설정이 제대로 작동하지 않으면 디버깅 앱의 code를 변경하기 전에 사용하세요. 대부분의 오류는 identity proof 불일치, 플랫폼 자격 증명 설정, OS 권한 상태, 백그라운드 스로틀링 또는 앱/패키지 ID 불일치로 인해 발생합니다.