Cordova SDK 기본 통합 가이드

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

전제 조건

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

통합 단계

1. Pushwoosh Cordova SDK 종속성 추가

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

cordova plugin add pushwoosh-cordova-plugin

2. Cordova SDK 초기화

index.js 파일의 루트 컴포넌트에서 deviceready 이벤트 핸들러 내에 다음 코드를 추가합니다. 단계를 정확한 순서대로 따르세요:

document.addEventListener('deviceready', function() {
    var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");

    // 1. 초기화 전에 알림 콜백 등록
    document.addEventListener('push-receive', function(event) {
        var notification = event.notification;
        console.log("Push received: " + JSON.stringify(notification));
    });

    document.addEventListener('push-notification', function(event) {
        var notification = event.notification;
        console.log("Push opened: " + JSON.stringify(notification));
    });

    // 2. Pushwoosh 초기화
    pushwoosh.onDeviceReady({
        appid: "__YOUR_APP_ID__",
        projectid: "__YOUR_FCM_SENDER_ID__"
    });

    // 3. 푸시 알림을 수신하도록 기기 등록
    pushwoosh.registerDevice(
        function(status) {
            var pushToken = status.pushToken;
            // 성공적인 등록 처리
        },
        function(status) {
            // 등록 오류 처리
        }
    );
}, false);

여기서:

__YOUR_APP_ID__는 Pushwoosh 제어판의 애플리케이션 코드입니다.
__YOUR_FCM_SENDER_ID__는 Firebase 콘솔의 Firebase 프로젝트 번호입니다.

초기화 순서는 반드시 위에 표시된 정확한 순서를 따라야 합니다:

먼저 이벤트 리스너 등록 (push-receive, push-notification)
그 다음 onDeviceReady() 호출
그 다음 registerDevice() 호출

이 순서를 변경하면 다음과 같은 문제가 발생할 수 있습니다:

onDeviceReady() 이후에 등록된 이벤트 리스너: 푸시 알림을 탭하여 앱이 시작된 경우(콜드 스타트), onDeviceReady()는 즉시 시작 알림 페이로드를 JavaScript로 전달합니다. 이 시점에 리스너가 아직 등록되지 않았다면, 시작 알림은 복구할 방법 없이 손실됩니다.
onDeviceReady() 전에 호출된 registerDevice(): 네이티브 SDK가 아직 앱 ID와 Sender ID로 올바르게 구성되지 않았을 수 있으며, 이로 인해 기기 등록이 조용히 실패하거나 오류를 반환할 수 있습니다.
registerDevice() 이후에 등록된 이벤트 리스너: 리스너가 준비되기 전에 도착하고 처리되는 모든 푸시 알림은 DOM 이벤트로 전달되어 조용히 삭제됩니다. 플러그인에는 재전송 메커니즘이 없기 때문입니다.

플러그인은 JavaScript 측에서 놓친 이벤트를 큐에 넣거나 버퍼링하지 않습니다. document.dispatchEvent()에 의해 발생한 DOM 이벤트는 디스패치 시점에 이미 등록된 리스너에게만 전달됩니다.

3. iOS 네이티브 설정

3.1 Capabilities

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

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

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

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

3.2 Info.plist

Runner/Info.plist에서 __PUSHWOOSH_DEVICE_API_TOKEN__ 키를 Pushwoosh Device API 토큰으로 설정합니다:

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

3.3 메시지 전송 추적

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

네이티브 가이드의 단계에 따라 확장 타겟과 그 안에 필요한 Pushwoosh 코드를 추가하세요.

4. Android 네이티브 설정

4.1 종속성 설치

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

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

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

앱 수준의 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 토큰을 추가합니다:

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

중요: Pushwoosh 제어판에서 토큰이 올바른 앱에 접근할 수 있도록 권한을 부여해야 합니다. 자세히 알아보기

5. 프로젝트 실행

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

확장 통합

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

푸시 알림 이벤트 리스너

Pushwoosh SDK에는 푸시 알림 처리를 위해 설계된 두 개의 이벤트 리스너가 있습니다:

push-receive 이벤트는 앱이 포그라운드에 있을 때 푸시 알림을 수신하면 트리거됩니다.
push-notification 이벤트는 사용자가 알림을 열 때 트리거됩니다.

이러한 이벤트 리스너는 위의 초기화 단계에서 보여준 것처럼 onDeviceReady()를 호출하기 전에 등록되어야 합니다. 필요에 맞게 핸들러 로직을 사용자 정의할 수 있습니다:

// onDeviceReady() 전에 등록
document.addEventListener('push-receive', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push received: " + message);
    // 여기에 사용자 정의 로직 추가
});

document.addEventListener('push-notification', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push accepted: " + message);
    // 여기에 사용자 정의 로직 추가 (예: 특정 화면으로 이동)
});

사용자 구성

개별 사용자 행동과 선호도에 초점을 맞춤으로써 개인화된 콘텐츠를 제공하여 사용자 만족도와 충성도를 높일 수 있습니다.

class Registration {
  afterUserLogin(user) {

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

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

class UpdateUser {
  afterUserUpdateProfile(user) {

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

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

이벤트

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

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

문제 해결

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