Capacitor SDK 기본 통합 가이드

이 섹션에서는 Pushwoosh Capacitor SDK를 애플리케이션에 통합하는 방법에 대한 정보를 제공합니다.

전제 조건

Pushwoosh Capacitor SDK를 앱에 통합하려면 다음이 필요합니다:

요구 사항

• Pushwoosh 계정.
• 계정에 설정된 Pushwoosh 프로젝트.
• iOS 통합의 경우:
  • 푸시 알림을 보내도록 구성된 iOS 플랫폼. 가장 간단한 접근 방식으로 토큰 기반 인증 구성을 사용하는 것을 권장합니다.
  • 시뮬레이터로 푸시를 보내려면 게이트웨이를 Sandbox로 설정하십시오.
  • Swift Package Manager로 플러그인을 추가하려면: Capacitor 7 또는 8. CocoaPods 프로젝트를 Swift Package Manager로 마이그레이션하려면: @capacitor/cli 7.4.0 이상.
• Android 통합의 경우:
  • 구성된 Android 플랫폼
  • Firebase 프로젝트의 google-services.json 파일 및 package name.
  • Android 애플리케이션에 연결된 Firebase 프로젝트. 필요한 경우 Firebase 설정 가이드를 따르십시오.
• 애플리케이션의 Pushwoosh 제어판에서 Pushwoosh Application Code 및 Pushwoosh Device API Token.

통합 단계

1. Pushwoosh Capacitor SDK 종속성 추가

Pushwoosh Capacitor SDK 종속성을 프로젝트에 추가합니다:

npm install pushwoosh-capacitor-plugin

Capacitor 구성을 동기화합니다:

npx cap sync

1.1 iOS 패키지 관리자 선택

npx cap sync는 Capacitor 프로젝트가 사용하는 패키지 관리자(Swift Package Manager 또는 CocoaPods)로 플러그인의 iOS 부분을 설치합니다. 두 방식 모두 동일한 버전의 네이티브 Pushwoosh SDK와 Inbox UI를 제공합니다. Swift Package Manager는 Capacitor 7과 Capacitor 8에서 지원됩니다.

기존 프로젝트는 원래의 패키지 관리자를 유지합니다. ios/App/CapApp-SPM이 있으면 Capacitor CLI는 Swift Package Manager를 사용하고, 없으면 CocoaPods를 사용합니다. 새 iOS 플랫폼의 경우:

Capacitor 8

Capacitor 8은 기본적으로 Swift Package Manager 프로젝트를 생성합니다:

npx cap add ios

대신 CocoaPods를 사용하려면 npx cap add ios --packagemanager CocoaPods를 실행합니다.

Capacitor 7

Capacitor 7은 기본적으로 CocoaPods 프로젝트를 생성합니다. Swift Package Manager를 사용하려면 다음을 실행합니다:

npx cap add ios --packagemanager SPM

이 명령은 프로젝트를 생성한 다음 pod install 실행을 시도하다가 ENOENT ... Podfile 오류와 함께 중지됩니다. 프로젝트는 올바르게 생성됩니다. 다음 명령으로 설정을 완료합니다:

npx cap sync ios

Swift Package Manager를 사용하면 Capacitor CLI가 플러그인을 ios/App/CapApp-SPM에 추가하고, 플러그인이 Pushwoosh iOS SDK와 Inbox UI를 가져옵니다. Pushwoosh SDK를 pod로든 다른 버전의 패키지로든 앱에 다시 추가하지 마십시오.

CocoaPods 지원 중단

CocoaPods trunk는 2026년 12월 2일에 읽기 전용으로 전환되며, Pushwoosh는 iOS SDK를 Swift Package Manager로 이전합니다. 이 날짜 이후의 플러그인 릴리스는 Swift 패키지만 사용합니다. 그때까지 CocoaPods 프로젝트의 pod install과 Xcode 빌드에서 이에 대한 경고가 표시됩니다. 이 경고는 빌드에 영향을 주지 않습니다.

기존 CocoaPods 프로젝트를 마이그레이션하려면 npx cap spm-migration-assistant를 실행한 다음, 명령이 링크하는 수동 Xcode 단계를 따르십시오. 이 명령에는 @capacitor/cli 7.4.0 이상이 필요합니다.

2. Capacitor SDK 초기화

메인 JavaScript 파일에서 Pushwoosh SDK를 가져와 초기화합니다:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// SDK 초기화
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// 푸시 알림 등록
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // 성공적인 등록 처리
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // 등록 오류 처리
    });

여기서:

• __YOUR_APP_CODE__는 Pushwoosh 제어판의 애플리케이션 코드입니다.

3. iOS 네이티브 설정

3.1 기능

프로젝트에서 푸시 알림을 활성화하려면 특정 기능을 추가해야 합니다.

Signing & Capabilities 섹션에서 다음 기능을 추가합니다:

• Push Notifications
• Background Modes. 이 기능을 추가한 후 Remote notifications 확인란을 선택합니다.

Time Sensitive Notifications (iOS 15+)를 사용하려는 경우 Time Sensitive Notifications 기능도 추가합니다.

3.2 Info.plist

ios/App/App/Info.plist에서 __PUSHWOOSH_DEVICE_API_TOKEN__ 키를 Pushwoosh Device API Token으로 설정합니다:

info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

3.3 메시지 전송 추적

프로젝트에 Notification Service Extension 타겟을 추가해야 합니다. 이는 정확한 전송 추적 및 iOS의 Rich Media와 같은 기능에 필수적입니다.

네이티브 가이드의 단계에 따라 확장 타겟과 그 안에 필요한 Pushwoosh 코드를 추가하십시오. 패키지 관리자에 따라 확장 타겟에 Pushwoosh SDK를 추가합니다:

• CocoaPods: 네이티브 가이드의 Notification Service Extension 종속성 (CocoaPods만 해당) 단계를 따릅니다. ios/App/Podfile에서 확장 타겟에 버전 없이 pod 'PushwooshXCFramework'를 추가하여 플러그인이 사용하는 버전으로 확인되도록 한 다음 npx cap sync ios를 실행합니다.

• Swift Package Manager: 네이티브 가이드의 CocoaPods 종속성 단계를 건너뜁니다. 확장 타겟은 플러그인의 종속성을 상속하지 않으므로 Xcode에서 직접 확장 타겟에 SDK를 추가합니다:

  1. 확장 타겟 > General > Frameworks and Libraries를 엽니다.
  2. Pushwoosh-XCFramework 패키지의 PushwooshFramework 제품을 추가합니다. Package.resolved에 이미 있는 버전을 사용합니다.

  CocoaPods에서 마이그레이션한 경우 앱에 SDK가 두 번 포함되지 않도록 확장이 더 이상 PushwooshXCFramework를 pod로 가져오지 않는지 확인합니다.

그런 다음 확장 코드에서 import PushwooshFramework를 추가합니다. App 타겟은 플러그인을 통해 Pushwoosh SDK를 받으므로 추가 작업이 필요하지 않습니다.

4. Android 네이티브 설정

4.1 종속성 설치

필요한 종속성과 플러그인이 Gradle 스크립트에 추가되었는지 확인합니다:

프로젝트 수준의 build.gradle 종속성에 Google Services Gradle 플러그인을 추가합니다:

android/build.gradle

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

앱 수준의 build.gradle 파일에 플러그인을 적용합니다:

app/build.gradle

apply plugin: 'com.google.gms.google-services'

4.2 Firebase 구성 파일 추가

google-services.json 파일을 프로젝트 디렉토리의 android/app 폴더에 넣습니다.

4.3 Pushwoosh 메타데이터 추가

main/AndroidManifest.xml의 <application> 태그 안에 Pushwoosh Device API Token을 추가합니다:

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

중요: Pushwoosh 제어판에서 토큰이 올바른 앱에 접근할 수 있도록 하십시오. 자세히 알아보기

5. 프로젝트 실행

1. 프로젝트를 빌드하고 실행합니다.
2. Pushwoosh 제어판으로 이동하여 푸시 알림을 보냅니다.
3. 앱에서 알림을 볼 수 있어야 합니다.

확장 통합

이 단계에서는 이미 SDK를 통합했으며 푸시 알림을 보내고 받을 수 있습니다. 이제 핵심 기능을 살펴보겠습니다.

푸시 알림 이벤트 리스너

Pushwoosh Capacitor SDK에는 푸시 알림을 처리하기 위한 두 가지 콜백 메서드가 있습니다:

• pushReceivedCallback은 푸시 알림을 수신했을 때 트리거됩니다.
• pushOpenedCallback은 사용자가 알림을 열었을 때 트리거됩니다.

SDK 초기화 직후에 이러한 콜백을 설정해야 합니다:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// 푸시 수신 콜백 설정
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // 수신된 알림 처리
    }
});

// 푸시 열림 콜백 설정
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // 열린 알림 처리
    }
});

사용자 구성

개별 사용자 행동 및 선호도에 집중함으로써 개인화된 콘텐츠를 제공하여 사용자 만족도와 충성도를 높일 수 있습니다.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {
  async afterUserLogin(user) {

    // 사용자 ID 설정
    Pushwoosh.setUserId(user.getId);

    // Pushwoosh에 대한 추가 사용자 정보를 태그로 설정
    await Pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

태그

태그는 사용자나 장치에 할당된 키-값 쌍으로, 선호도나 행동과 같은 속성을 기반으로 세분화하여 타겟 메시징을 가능하게 합니다.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class UpdateUser {
 async afterUserUpdateProfile(user) {

    // 선호 카테고리 목록 설정
    await Pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // 결제 정보 설정
    await Pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

이벤트

이벤트는 앱 내에서 특정 사용자 행동이나 발생을 추적하여 행동을 분석하고 해당 메시지나 작업을 트리거할 수 있는 것입니다.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {

  // 로그인 이벤트 추적
  afterUserLogin(user) {
    Pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // 구매 이벤트 추적
  afterUserPurchase(product) {
    Pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

문제 해결

푸시가 전달되지 않으면 전송 오류에서 사용 중인 플랫폼의 오류 코드를 찾아 의미와 해결 방법을 확인하십시오.

통합 과정에서 문제가 발생하면 지원 및 커뮤니티 섹션을 참조하십시오.