언리얼 엔진 SDK - 푸시 알림 지원

문서

푸시 알림 지원

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

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

푸시 알림을 추적해야 하는 이유: 푸시 알림은 리인게이지먼트를 유도하지만 추적을 위해서는 올바른 연동이 필요합니다. Singular는 알림과 상호작용하는 사용자의 어트리뷰션을 올바르게 추적하여 마케팅 캠페인과 참여 전략을 최적화합니다.


구현 가이드

Singular SDK 연동

Singular 언리얼 엔진 SDK 가이드에 설명된 표준 설치 지침에 따라 언리얼 엔진 프로젝트에 Singular SDK를 연동하세요.


푸시 토큰 등록

Singular에 푸시 알림 토큰을 등록하여 앱 삭제 추적 및 푸시 어트리뷰션을 활성화하세요.

C++
// Register push token for uninstall tracking
void UYourGameInstance::OnPushTokenReceived(const FString& Token)
{
    // Pass the FCM or APNs token to Singular
    USingularSDKBPLibrary::SetUninstallToken(Token);
    UE_LOG(LogTemp, Log, TEXT("Push token registered: %s"), *Token);
}

메서드 서명:

static void SetUninstallToken(FString token);

모범 사례: FCM(Android) 또는 APN(iOS)에서 푸시 알림 토큰을 받으면 바로 SetUninstallToken으로 전송하세요. 이렇게 하면 앱 삭제 및 푸시 알림 상호 작용을 적절히 추적할 수 있습니다.


플랫폼별 처리

iOS 푸시 알림 처리

푸시 알림 경로 구성

iOS 구현의 경우 SDK 초기화 중에 푸시 알림 페이로드 구조 내에서 Singular 추적 링크가 위치한 JSON 경로를 구성합니다.

C++
// iOS: Configure push notification link paths in initialization
// Note: This is typically configured through the iOS native bridge
// The Singular iOS SDK automatically handles push tracking when configured

// Example configuration in iOS native code (Objective-C):
// SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" andSecret:@"API_SECRET"];
// config.singularLinksHandler = ^(SingularLinkParams * _Nonnull params) {
//     // Handle deep link from push notification
// };
// [Singular start:config];

종료 상태(앱 실행 중이 아님)

종료된 상태의 iOS 앱에는 수동 작업이 필요하지 않습니다. 앱이 실행 중이 아닌 상태에서 사용자가 알림을 탭하면 Singular iOS 연동이 자동으로 푸시 추적을 처리합니다.

자동 처리: 앱이 실행 중이 아닌 상태에서 사용자가 푸시 알림을 탭하면, Singular는 기본 iOS 연동 계층을 통해 앱 실행 중에 알림 페이로드를 자동으로 캡처합니다.

백그라운드 상태(백그라운드에서 앱 실행 중)

앱이 백그라운드 상태에서 알림을 수신하면 iOS SDK가 자동으로 알림 데이터를 처리합니다. 초기 토큰 등록 외에 추가 C++ 코드가 필요하지 않습니다.

중요: iOS 프로젝트가 푸시 알림 기능으로 올바르게 구성되었는지, 앱 초기화 중에 SetUninstallToken 을 사용하여 APN 토큰이 등록되었는지 확인하세요.


Android 푸시 알림 처리

Firebase 클라우드 메시징 연동

Android 구현의 경우, Firebase 클라우드 메시징(FCM)을 연동하고 추적을 위해 푸시 토큰을 Singular SDK로 전달합니다.

C++
// Android: Register FCM token with Singular
void UYourGameInstance::OnFirebaseTokenReceived(const FString& FcmToken)
{
    // Register the FCM token for uninstall tracking
    USingularSDKBPLibrary::SetUninstallToken(FcmToken);
    UE_LOG(LogTemp, Log, TEXT("FCM token registered with Singular: %s"), *FcmToken);
}

푸시 알림 데이터 처리

사용자가 Singular 추적 링크가 포함된 푸시 알림을 탭할 때, 적절한 어트리뷰션을 위해 알림 데이터가 앱의 딥링크 핸들러로 전달되는지 확인하세요.

C++
// Handle notification tap event
void UYourGameInstance::OnNotificationTapped(const FString& NotificationData)
{
    // Parse notification data for Singular links
    // Example: Extract "sng_link" or custom key from notification payload

    // If notification contains a Singular tracking link, it will be
    // automatically processed by the SDK's deep link handler

    UE_LOG(LogTemp, Log, TEXT("Notification tapped: %s"), *NotificationData);

    // Route user to appropriate content
    ProcessNotificationDeepLink(NotificationData);
}

void UYourGameInstance::ProcessNotificationDeepLink(const FString& LinkData)
{
    // Your custom deep link routing logic
    if (LinkData.Contains(TEXT("article")))
    {
        // Navigate to article
        OpenArticleScreen();
    }
    else if (LinkData.Contains(TEXT("promotion")))
    {
        // Navigate to promotion
        OpenPromotionScreen();
    }
}

모범 사례: Singular 추적 링크(어트리뷰션용)와 앱의 사용자 지정 딥링크 데이터(특정 콘텐츠로 사용자를 라우팅하기 위한)를 모두 포함하도록 푸시 알림 페이로드를 구성하세요.


유효성 검사 가이드

푸시 토큰 등록 확인

앱 초기화 중 SDK 로그를 확인하여 푸시 알림 토큰이 Singular에 올바르게 등록되었는지 확인하세요.

C++
// Enable SDK logging to verify token registration
bool Success = USingularSDKBPLibrary::Initialize(
    TEXT("YOUR_SDK_KEY"),
    TEXT("YOUR_SDK_SECRET"),
    60,                      // Session timeout
    TEXT(""),                // Custom user ID
    true,                    // Enable SKAdNetwork
    false,                   // Manual SKAN management
    0,                       // Wait for tracking authorization
    false,                   // OAID collection
    true,                    // Enable logging for debugging
    5,                       // Verbose log level
    false,                   // Clipboard attribution
    TEXT(""),                // Facebook App ID
    TEXT("")                 // Custom SDID
);

// After receiving push token
FString PushToken = GetPushNotificationToken();
USingularSDKBPLibrary::SetUninstallToken(PushToken);

// Check logs for confirmation:
// "Push token registered successfully" or similar message

디버깅 팁: 개발 중에 상세 로깅(로그 레벨 5)을 활성화하면 푸시 토큰 등록 및 알림 처리에 대한 자세한 정보를 확인할 수 있습니다. 성능을 위해 프로덕션 빌드에서는 상세 로깅을 비활성화하세요.


대시보드에서 어트리뷰션 확인

Singular 대시보드를 사용하여 푸시 알림 상호 작용이 올바르게 추적되고 있는지 확인할 수 있습니다.

  • 리인게이지먼트 캠페인: 대시보드에서 리인게이지먼트 섹션을 확인하여 푸시 알림 캠페인 성과를 확인하세요.
  • 사용자 수준 데이터: 사용자 수준 데이터를 내보내 푸시 알림 터치포인트가 올바른 어트리뷰션으로 기록되고 있는지 확인합니다.
  • 전환 이벤트: 푸시 알림 탭 후 트리거된 이벤트가 올바른 캠페인에 어트리뷰션되었는지 확인합니다.

고급 구성

사용자 지정 알림 페이로드 구조

사용자 지정 데이터와 함께 Singular 추적 파라미터를 포함하도록 푸시 알림 페이로드를 구조화하세요.

권장 페이로드 구조(JSON):

{
  "notification": {
    "title": "Special Offer!",
    "body": "Get 50% off today only"
  },
  "data": {
    "sng_link": "https://yourapp.sng.link/Abc12?_dl=myapp://promo",
    "campaign_id": "summer_sale_2025",
    "promo_code": "SAVE50",
    "deep_link": "myapp://promo/summer"
  }
}

핵심 요소:

  • sng_link: 어트리뷰션을 위한 Singular 추적 링크(푸시 추적에 필요).
  • campaign_id: 참조용 내부 캠페인 식별자입니다.
  • deep_link: 콘텐츠 라우팅을 위한 앱의 커스텀 딥링크입니다.
  • 커스텀 데이터: 앱에 필요한 모든 추가 데이터(프로모션 코드, 사용자 세그먼트 등).

참고: Singular SDK는 "sng_link" 키에서 추적 링크를 자동으로 추출하고 처리합니다. 이 키가 모든 푸시 알림 캠페인에서 일관되게 사용되는지 확인하세요.


딥링크 라우팅 구현

중앙 집중식 딥링크 핸들러를 구현하여 사용자가 푸시 알림을 탭할 때 특정 콘텐츠로 라우팅합니다.

C++
// Centralized deep link handler
class UDeepLinkHandler : public UObject
{
public:
    void HandleDeepLink(const FString& DeepLink)
    {
        // Parse the deep link URL
        if (DeepLink.StartsWith(TEXT("myapp://article/")))
        {
            FString ArticleId = ExtractArticleId(DeepLink);
            NavigateToArticle(ArticleId);
        }
        else if (DeepLink.StartsWith(TEXT("myapp://promo/")))
        {
            FString PromoId = ExtractPromoId(DeepLink);
            NavigateToPromotion(PromoId);
        }
        else if (DeepLink.StartsWith(TEXT("myapp://profile")))
        {
            NavigateToUserProfile();
        }
        else
        {
            // Default: Navigate to home screen
            NavigateToHome();
        }
    }

private:
    FString ExtractArticleId(const FString& Url)
    {
        // Extract article ID from URL
        FString ArticleId;
        Url.Split(TEXT("article/"), nullptr, &ArticleId);
        return ArticleId;
    }

    FString ExtractPromoId(const FString& Url)
    {
        // Extract promo ID from URL
        FString PromoId;
        Url.Split(TEXT("promo/"), nullptr, &PromoId);
        return PromoId;
    }

    void NavigateToArticle(const FString& ArticleId)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to article: %s"), *ArticleId);
        // Your navigation logic
    }

    void NavigateToPromotion(const FString& PromoId)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to promotion: %s"), *PromoId);
        // Your navigation logic
    }

    void NavigateToUserProfile()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to user profile"));
        // Your navigation logic
    }

    void NavigateToHome()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to home screen"));
        // Your navigation logic
    }
};

중요 고려 사항

구현 참고 사항

  • 토큰 등록 타이밍: 푸시 토큰을 FCM 또는 APN에서 사용할 수 있게 되는 즉시 Singular에 등록하세요(SDK 초기화 중 또는 직후가 가장 이상적).
  • 어트리뷰션 흐름: 사용자가 Singular 링크가 포함된 알림을 탭하면 세션 시작 이벤트 중에 SDK가 자동으로 어트리뷰션 데이터를 처리합니다. 어트리뷰션 추적을 위해 수동 처리가 필요하지 않습니다.
  • 딥링크 처리: Singular는 어트리뷰션을 자동으로 처리하지만, 사용자를 올바른 인앱 콘텐츠로 안내하려면 사용자 지정 딥링크 라우팅 로직을 구현해야 합니다.
  • 페이로드 일관성: 모든 푸시 알림 캠페인에서 일관된 키 이름(예: "sng_link")을 사용하여 안정적인 추적을 보장합니다.
  • 플랫폼 차이: iOS와 Android는 시스템 수준에서 푸시 알림을 다르게 처리합니다. 구현 시 플랫폼별 동작을 고려해야 합니다.
  • 추적 제거: 푸시 토큰은 앱 삭제 추적에도 사용됩니다. Singular는 무음 푸시 알림을 전송하여 제거된 앱을 감지하여 귀중한 리텐션 인사이트를 제공합니다.

프로덕션 체크리스트: 푸시 알림 캠페인을 시작하기 전에 (1) 푸시 토큰이 성공적으로 등록되었는지, (2) 알림 페이로드에 Singular 추적 링크가 포함되어 있는지, (3) 딥링크 라우팅이 올바르게 작동하는지, (4) 어트리뷰션 데이터가 Singular 대시보드에 나타나는지 확인합니다.


개인정보 보호 및 권한

푸시 알림을 구현할 때 플랫폼 요구사항 및 사용자 개인정보 보호 규정을 준수해야 합니다.

  • iOS 권한: 사용자는 푸시 알림을 수신할 수 있는 권한을 부여해야 합니다. 앱이 처음 실행될 때 즉시가 아니라 앱 흐름의 적절한 시점에 권한을 요청하세요.
  • 안드로이드 권한: Android 13(API 레벨 33)부터 앱은 알림을 전송하기 위해 POST_NOTIFICATIONS 권한을 요청해야 합니다.
  • 사용자 동의: 마케팅 커뮤니케이션 수신에 대한 사용자 기본 설정을 존중해야 합니다. 앱 설정에 명확한 수신 거부 메커니즘을 제공하세요.
  • 데이터 개인정보 보호: 푸시 알림 페이로드에 개인 식별 정보(PII)를 포함하지 마세요. 사용자 ID 또는 기타 비PII 식별자를 사용합니다.

성공: 이러한 구현 단계를 따르면 이제 언리얼 엔진 앱이 Singular와 푸시 알림 상호작용을 추적하여 캠페인 성과 인사이트를 개선하고 정확한 리인게이지 어트리뷰션을 보장할 수 있습니다.