푸시 알림 지원

푸시 알림을 통해 사용자 상호작용을 추적하여 리인게이지먼트 캠페인과 어트리뷰션 전환을 정확하게 측정할 수 있도록 Firebase 클라우드 메시징(FCM)을 Singular SDK와 연동하세요.

아래 구현 가이드라인에 따라 알림 데이터가 적절한 어트리뷰션을 위해 Singular SDK에 올바르게 전달되도록 하세요.

구현 가이드

Singular SDK 연동

Singular Cordova SDK 가이드에 설명된 대로 표준 설치 지침을 사용하여 Cordova 프로젝트에 Singular SDK를 연동하세요.

Firebase 클라우드 메시징 설정

@havesource/cordova-plugin-push 같은 플러그인을 사용하여 Cordova 프로젝트에서 푸시 알림을 구성하고 플랫폼별 연동을 위해 Firebase의 설정 가이드를 따르세요.

iOS 구성

Firebase에 iOS 앱을 등록하고 Xcode에서 푸시 알림 기능을 구성하세요.

1. iOS 앱 등록하기: Firebase 콘솔 프로젝트에서 iOS 앱을 만듭니다.
2. 구성 파일 추가: GoogleService-Info.plist 을 다운로드하여 iOS 플랫폼 폴더에 포함시킵니다.
3. 기능 활성화: 기능 활성화: Xcode 프로젝트 설정에서 푸시 알림 기능을 활성화합니다.
4. 백그라운드 모드를 활성화합니다: 백그라운드 모드 활성화: 백그라운드 모드를 활성화하고 원격 알림을 확인합니다.

Android 구성

Firebase에 Android 앱을 등록하고 프로젝트에 구성 파일을 추가합니다.

1. Android 앱 등록하기: Firebase 콘솔 프로젝트에서 Android 앱을 만듭니다.
2. 구성 파일 추가: google-services.json 을 다운로드하여 platforms/android/app/에 배치합니다.
3. 종속성 확인: Firebase 플러그인이 제대로 설치되어 있고 메시징 권한이 부여되었는지 확인합니다.

푸시 링크 경로 구성

적절한 어트리뷰션 추적을 위해 푸시 알림 페이로드 구조 내에서 Singular 추적 링크가 위치하는 JSON 경로를 정의합니다.

알림 데이터 구조에서 Singular 링크의 키 경로를 지정하는 문자열 배열을 전달하여 푸시 링크 경로를 구성합니다. 각 경로는 키의 중첩 구조를 나타내는 배열입니다.

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure paths where Singular links appear in push payload
config.withPushNotificationsLinkPaths([
  ['sng_link'],                              // Top-level key
  ['path', 'to', 'url'],                     // Nested path
  ['rootObj', 'nestedObj', 'singularLink']   // Deep nested path
]);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

경로 구성 예시:

• 단순 키: 페이로드의 최상위 키에 ['sng_link'] 사용
• 중첩된 키: 중첩된 JSON 구조를 횡단하려면 ['rootObj', 'nestedObj', 'key'] 사용
• 다중 경로: 여러 경로 배열을 정의하여 Singular 링크에 대해 가능한 여러 위치를 확인합니다.

전체 메서드 문서에 대한 자세한 내용은 withPushNotificationsLinkPaths 참조를 참조하세요.

플랫폼별 처리

사용자가 푸시 알림과 상호 작용할 때 앱 상태에 따라 알림 데이터를 Singular SDK에 전달하도록 플랫폼별 코드를 구성합니다.

iOS 푸시 알림 처리

종료된 상태의 앱

앱이 종료된 상태에서 열릴 때 자동 푸시 추적을 위해 실행 옵션을 Singular SDK에 전달하도록 iOS 앱디렉티브를 구성하세요.

AppDelegate.m 내의 네이티브 iOS 코드에서 다음 메서드를 didFinishLaunchingWithOptions 으로 호출합니다:

// Import at the top of the file
#import <SingularCordovaSdk/SingularCordovaSdk.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // Pass launch options to Singular for push tracking
    [SingularCordovaSdk setLaunchOptions:launchOptions];
    
    // Your other initialization code
    return YES;
}

백그라운드 또는 포그라운드에서 앱 실행

앱이 백그라운드 또는 포그라운드 상태에서 알림을 수신할 때 handlePushNotification() 메서드를 사용하여 푸시 데이터를 SDK에 전달합니다.

푸시 알림이 처리되는 자바Script 코드에서 다음 메서드를 호출합니다:

// Handle push notification when app is in background or foreground
document.addEventListener('deviceready', initializePushHandling, false);

function initializePushHandling() {
  // Initialize push plugin
  var push = PushNotification.init({
    android: {},
    ios: {
      alert: true,
      badge: true,
      sound: true
    }
  });
  
  // Handle notification when app is in foreground or background
  push.on('notification', function(data) {
    console.log('Push notification received:', data);
    
    // Pass notification data to Singular
    cordova.plugins.SingularCordovaSdk.handlePushNotification(data.additionalData);
    
    // Your custom notification handling logic
    handleNotificationNavigation(data);
  });
}

function handleNotificationNavigation(data) {
  // Navigate to appropriate screen based on notification data
  if (data.additionalData && data.additionalData.route) {
    console.log('Navigating to:', data.additionalData.route);
    // Your navigation logic
  }
}

전체 메서드 설명서는 handlePushNotification 참조를 참조하세요.

안드로이드 푸시 알림 처리

종료된 상태의 앱

종료된 상태의 안드로이드 앱에는 아무런 조치가 필요하지 않습니다. 사용자가 알림을 탭하면 코르도바 브릿지 계층이 이 시나리오를 자동으로 처리합니다.

백그라운드 또는 포그라운드의 앱

앱이 백그라운드 또는 포그라운드 상태일 때 알림 인텐트를 Singular SDK에 전달하도록 Android 메인 액티비티를 구성하세요.

기본 Cordova 활동(예: MainActivity.java)에서 onNewIntent 을 재정의합니다:

// Add imports at the top
import android.content.Intent;
import singular_cordova_sdk.SingularCordovaSdk;

// Add to MainActivity class
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    
    // Pass intent to Singular for push tracking
    SingularCordovaSdk.handleNewIntent(intent);
}

또한 위의 iOS 백그라운드/포그라운드 처리에 대해 표시된 것과 동일한 접근 방식을 사용하여 자바Script 코드에서 푸시 메시지 처리를 구현하세요.

유효성 검사 가이드

Singular SDK의 시작 세션 호출을 검사하고 어트리뷰션 데이터를 모니터링하여 푸시 알림 추적이 올바르게 작동하는지 확인합니다.

시작 세션에서 페이로드 확인

API 호출 파라미터 확인

시작 세션 API 호출을 검사하여 푸시 알림 링크가 Singular에 올바르게 전달되었는지 확인합니다.

Singular SDK는 사용자가 알림을 탭할 때 시작 세션 요청의 singular_link 파라미터 아래에 푸시 알림 페이로드를 포함합니다.

세션 시작 요청 예시:

https://sdk-api-v1.singular.net/api/v1/start?
a=<SDK-Key>
&singular_link=https://singularassist2.sng.link/C4nw9/r1m0?_dl=singular%3A%2F%2Ftest&_smtype=3
&i=net.singular.singularsampleapp
&install_time=1740905507036
&s=1740905574084
&sdk=Singular/v12.6.2
&singular_install_id=2dc5dfc2-a2a8-484a-aad1-fed6cb7a3023
&u=75f7b911-5a77-597d-8892-56f5e0e210ff

고급 구성

복잡한 알림 시나리오를 위해 ESP 도메인 구성 및 동적 딥링크 라우팅을 포함한 고급 푸시 알림 기능을 구현하세요.

ESP 도메인 구성

외부 도메인 구성

이메일 서비스 제공업체(ESP) 또는 기타 타사 도메인 내에서 Singular 링크를 래핑하는 경우 외부 도메인을 구성합니다.

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure ESP domains for wrapped Singular links
config.withESPDomains(['sl.esp.link', 'custom.domain.com']);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

전체 메서드 문서에 대한 자세한 내용은 ESPDomains 참조를 참조하세요.

동적 딥 링크 라우팅

Singular 알림에서 여러 작업 수행

동적 리디렉션 오버라이드를 사용하여 하나의 Singular 추적 링크를 구성하여 Singular 알림에서 여러 딥링크 대상을 구현할 수 있습니다.

사용 사례 예시: 여러 액션 옵션이 포함된 속보 알림

• 최신 뉴스 읽기: newsapp://article?id=12345
• 인기 토픽: newsapp://trending
• 스포츠: newsapp://sports

여러 개의 추적 링크를 만드는 대신 하나의 Singular 링크를 사용하고 사용자 선택에 따라 리디렉션을 동적으로 재정의하세요. 구현에 대한 자세한 내용은 Singular 추적 링크에서 리디렉션 재정의하기를 참조하세요.

// Handle multiple deep link options from single notification
function handleNotificationWithActions(notificationData) {
  // Extract action selection from notification data
  var selectedAction = notificationData.action;
  var singularLink = notificationData.sng_link;
  
  // Route based on action
  switch (selectedAction) {
    case 'read_news':
      navigateToArticle(notificationData.article_id);
      break;
    case 'trending':
      navigateToTrending();
      break;
    case 'sports':
      navigateToSports();
      break;
    default:
      navigateToHome();
  }
  
  // Pass notification to Singular for attribution
  cordova.plugins.SingularCordovaSdk.handlePushNotification(notificationData);
}

function navigateToArticle(articleId) {
  console.log('Navigating to article:', articleId);
  // Your navigation logic
}

function navigateToTrending() {
  console.log('Navigating to trending');
  // Your navigation logic
}

function navigateToSports() {
  console.log('Navigating to sports');
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

중요 고려 사항

푸시 알림 추적을 Singular SDK와 연동할 때 주요 구현 세부 사항 및 제한 사항을 이해하세요.

구현 참고 사항

주요 동작 및 제한 사항

• 콜백 핸들러 없음: withSingularLink 과 달리 푸시 알림 기능은 페이로드 콜백을 제공하지 않습니다. 알림 데이터를 기반으로 사용자를 앱 내의 특정 콘텐츠로 라우팅하려면 자체 딥링킹 로직을 구현해야 합니다.
• 어트리뷰션 흐름: 사용자가 알림을 탭하면 Singular는 페이로드를 검색하여 Singular.init(config) 에 의해 트리거된 시작 세션 이벤트에 포함합니다. 백엔드는 이 데이터를 처리하여 푸시 알림 터치포인트를 어트리뷰션하고 리인게이지먼트 추적을 등록합니다.
• 도메인 제한: 링크 관리 페이지의 Singular 링크 도메인(sng.link)만 기본적으로 허용됩니다. withESPDomains() 을 사용하여 래핑된 링크에 대해 명시적으로 ESP 도메인을 구성하세요.
• 플랫폼 차이점: iOS는 종료 상태 처리를 위해 앱디렉티브 구성이 필요하지만, 안드로이드는 종료 상태 시나리오의 경우 브리지 모듈을 통해 자동으로 처리합니다.
• 경로 구성: SDK는 withPushNotificationsLinkPaths() 에 정의된 경로를 사용하여 Singular 링크를 검색합니다. 적절한 링크 추출을 위해 알림 페이로드 구조가 구성된 경로와 일치하는지 확인하세요.

테스트 권장 사항

1. 모든 앱 상태를 테스트합니다: 앱이 종료된 상태, 백그라운드 상태, 포그라운드 상태일 때 푸시 트래킹이 올바르게 작동하는지 확인합니다.
2. 페이로드 구조 검증: 알림 페이로드가 구성된 경로에 Singular 링크를 포함하는지 확인합니다.
3. 세션 호출 시작 확인: 네트워크 모니터링 도구를 사용하여 시작 세션 요청에 singular_link 파라미터가 나타나는지 확인합니다.
4. 어트리뷰션 모니터링: Singular SDK 콘솔에서 푸시 알림이 캠페인 데이터에 올바르게 어트리뷰션되었는지 확인합니다.
5. 딥링킹 테스트: 다양한 알림 유형을 탭할 때 사용자가 의도한 콘텐츠로 올바르게 이동하는지 확인합니다.