시작하기

@capgo/capacitor-notifications Capgo는 iOS 및 Android 원시 푸시 알림을 위한 첫 번째 파티 플러그인입니다. Capgo의 대시보드, 공개 API, 분석 엔진 장치 등록, 캠페인 통계, 배지 업데이트 및 무음 라이브 업데이트 확인을 위해 설계되었습니다.

요구 사항

• Capacitor 앱이 이미 Capgo에 추가되어야 합니다.
• Capgo 앱의 알림 탭에 접근할 수 있어야 합니다.
• Capgo API 키가 백엔드 증명 인쇄 및 API 전송에 쓰기 권한이 있어야 합니다.
• iOS 및/또는 Android 플랫폼 푸시 권한이 앱에 있어야 합니다.
• @capgo/capacitor-updater 무음 푸시 업데이트 확인을 원한다면.

1. Capgo 플랫폼 인증 정보를 설정하세요.

Capgo 앱을 열고 通知.

각 플랫폼을 지원하려면 플랫폼별로 하나씩 인증 정보를 추가하세요.

• Android 안드로이드
• iOS iOS

Capgo shows the exact environment secret name that must exist in the API worker before the platform is marked configured. The dashboard stores metadata and the expected secret reference. The private credential itself stays in the worker environment.

2. 설치

가장 빠른 설정을 위해 앱 프로젝트에서 Capgo CLI을 실행하세요.

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

The command installs the notification package, saves the Capacitor plugin config, creates a small helper file, and runs Capacitor sync. Use this path for new apps unless you need to wire every file manually.

__CAPGO_KEEP_0__ 패키지를 설치하고 __CAPGO_KEEP_0__ 플러그인 설정을 저장하고 작은 헬퍼 파일을 생성하고 __CAPGO_KEEP_1__ 동기화를 실행합니다. 새로운 앱에 대해 이 경로를 사용하거나 파일을 수동으로 연결해야 하는 경우를 제외합니다.

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

silent 업데이트 확인을 하지 않는 경우, Capgo 생략 가능합니다. @capgo/capacitor-updater.

silent __CAPGO_KEEP_0__ 업데이트 확인을 사용하지 않는 경우 __CAPGO_KEEP_0__를 생략할 수 있습니다.

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

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

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

다운로드 updateInstallMode: 'next' 업데이트를 다운로드하고 다음 재시작 또는 백그라운드 사이클에서 설치합니다. updateInstallMode: 'set' 업데이트를 설치할 때만 Capgo을 즉시 설치할 수 있는 updater가 안전하게 할 수 있는 때를 원할 때.

4. 신분증명 생성

애플리케이션에 사용하는 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. 장치 등록

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. 이벤트 리스너 추가

앱 시작 시 리스너를 등록하여 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에서 앱 대상を開고 다음을 활성화하십시오:

• 푸시 알림
• 배경 모드 > 원격 알림

원격 알림을 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. 안드로이드 설정

실행:

bunx cap sync android

그런 다음 확인:

• Capgo에서 Android 플랫폼 인증서가 구성되어 있습니다.
• 앱 패키지 ID는 플랫폼 푸시 설정에 사용된 패키지 ID와 일치합니다.
• 안드로이드 13 이상 알림 권한이 요청되기 전에 표시되는 알림을 기대하지 마십시오.
• 앱에는 알림 아이콘과 브랜드와 일치하는 채널 전략이 있습니다.
• Google Play 서비스가 있는 실제 장치 또는 에뮬레이터에서 테스트합니다.

앱이 시작될 때 기본 안드로이드 채널을 생성하세요:

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

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

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

9. 테스트 알림을 보내세요

사용 Notifications > 테스트 전송 in 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()

컨텍스트: Capgo 마케팅 웹사이트. 역할: UI 레이블. 위치: 페이지 agent/[slug].astro. 메시지 키 `agents_page_copy_label` (Agent 페이지 복사 레이블).

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. 무음 업데이트 확인 @capgo/capacitor-updater.

앱 내에서:

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

Capgo에서 활성화 사용자에게 업데이트를 푸시합니다 앱의 알림 설정에서 활성화 한 다음 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"
  }'

알림은 무음이고, 재귀 콜백 ID를 사용하여 플랫폼이 콜백 동작을 지원할 때 업데이트를 확인하는 반복적인 요청을 대체합니다.

유효성 검사 목록

• Capgo에서 예상되는 수신자 목록에 앱이 표시됩니다. externalId.
• 권한이 있습니다 granted 권한이 있습니다
• 등록된 플랫폼은 android 또는 ios.
• registrationChanged 업데이트가 완료되면
• 앞면 테스트 로그 notificationReceived.
• 通知를 열면 로그 notificationOpened.
• 대시보드 통계는 큐드되고 전송된 이벤트를 보여주고, 장치가 그들을 보고하면 받은/열린 이벤트를 보여줍니다.
• silent 업데이트 체크 로그는 runUpdateCheck 업데이트 통합자

Getting Started에서 계속

설정이 작동하지 않으면 디버깅 앱을 변경하기 전에 code. 대부분의 실패는 인증 증명 불일치, 플랫폼 자격 증명 설정, OS 권한 상태, 배경 속도 제한, 또는 앱/패키지 ID 불일치로 인해 발생합니다.