푸시 알림 지원

Firebase Cloud Messaging(FCM)을 Singular SDK와 연동하여 푸시 알림과의 유저 상호작용을 추적하고, 리인게이지먼트 캠페인을 측정하며 전환을 정확하게 어트리뷰션하세요.

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

구현 가이드

FCM 알림 처리

FirebaseMessagingService에서 onMessageReceived() 메서드를 오버라이드하여 푸시 메시지가 도착할 때 알림 데이터를 캡처하세요.

override fun onMessageReceived(message: RemoteMessage) {
    super.onMessageReceived(message)
    var title = ""
    var body = ""

    message.notification?.let {
        Log.d("singular-app", it.toString())
        title = it.title ?: ""
        body = it.body ?: ""
    }

    val data: Map<String, String> = message.data
    if (data.isNotEmpty()) {
        Log.d("singular-app", data.toString())
    }

    // Forward payload data to intent
    processNotification(title, body, data)
}

@Override
public void onMessageReceived(@NonNull RemoteMessage message) {
    super.onMessageReceived(message);
    String title = "";
    String body = "";

    if (message.getNotification() != null) {
        Log.d("singular-app", message.getNotification().toString());
        title = message.getNotification().getTitle();
        body = message.getNotification().getBody();
    }

    Map<String, String> data = message.getData();
    if (!data.isEmpty()) {
        Log.d("singular-app", data.toString());
    }

    // Forward payload data to intent
    processNotification(title, body, data);
}

알림 데이터 처리 및 전달

알림 페이로드(payload)를 첨부한 인텐트로 MainActivity를 실행하여 Singular가 추적 데이터를 수신하도록 하세요.

private fun processNotification(title: String, body: String, data: Map<String, String>) {
    val intent = Intent(this, MainActivity::class.java).apply {
        flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK

        // Attach notification data to the intent
        data.forEach { (key, value) ->
            putExtra(key, value)
        }
    }

    val pendingIntent = PendingIntent.getActivity(
        this,
        0,
        intent,
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
    )

    val notificationBuilder = NotificationCompat.Builder(this, "your_channel_id")
        .setSmallIcon(R.drawable.ic_notification)
        .setContentTitle(title)
        .setContentText(body)
        .setPriority(NotificationCompat.PRIORITY_HIGH)
        .setAutoCancel(true)
        .setContentIntent(pendingIntent)

    val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
    notificationManager?.notify(0, notificationBuilder.build())
}

private void processNotification(String title, String body, Map<String, String> data) {
    Intent intent = new Intent(this, MainActivity.class);
    intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);

    // Attach notification data to the intent
    for (Map.Entry<String, String> entry : data.entrySet()) {
        intent.putExtra(entry.getKey(), entry.getValue());
    }

    PendingIntent pendingIntent = PendingIntent.getActivity(
            this,
            0,
            intent,
            PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
    );

    NotificationCompat.Builder notificationBuilder = new NotificationCompat.Builder(this, "your_channel_id")
            .setSmallIcon(R.drawable.ic_notification)
            .setContentTitle(title)
            .setContentText(body)
            .setPriority(NotificationCompat.PRIORITY_HIGH)
            .setAutoCancel(true)
            .setContentIntent(pendingIntent);

    NotificationManager notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
    if (notificationManager != null) {
        notificationManager.notify(0, notificationBuilder.build());
    }
}

푸시 페이로드(payload)용 SDK 구성

SDK 구성에 푸시 알림 페이로드(payload) 셀렉터(selectors)를 추가하여 Singular 링크가 알림 데이터 구조의 어디에 위치하는지 지정하세요.

val pushSelectors = arrayOf(
    arrayOf("sng_link"),
    arrayOf("rootObj", "nestedObj", "anotherNested", "singularLink")
)

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withPushNotificationPayload(intent, pushSelectors)

Singular.init(applicationContext, config)

String[][] pushSelectors = {
    {"sng_link"},
    {"rootObj", "nestedObj", "anotherNested", "singularLink"}
};

SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withPushNotificationPayload(getIntent(), pushSelectors);

Singular.init(getApplicationContext(), config);

셀렉터(selectors) 구성:

• 단순 키: 페이로드(payload)의 최상위 키에는 arrayOf("sng_link") 를 사용하세요.
• 중첩 키: 중첩된 JSON 구조를 탐색하려면 arrayOf("rootObj", "nestedObj", "key") 를 사용하세요.
• 여러 경로: 여러 셀렉터(selectors) 배열을 정의하여 Singular 링크가 위치할 수 있는 여러 경로를 확인하세요.

검증 가이드

Start Session에서 페이로드(payload) 검증

Start Session API 호출을 검사하여 푸시 알림 링크가 Singular에 올바르게 전달되었는지 확인하세요.

Singular SDK는 유저가 알림을 탭할 때 Start Session 요청에 singular_link 파라미터로 푸시 알림 페이로드(payload)를 포함합니다.

Start Session 요청 사용 예시:

https://sdk-api-v1.singular.net/api/v1/start?
a=<SDK-Key>
&singular_link=https://singularassist2.sng.link/C4nw9/r1m0?_dl=singular://test&_smtype=3
&i=net.singular.singularsampleapp
&s=1740905574084
&sdk=Singular/v12.6.2

고급 구성

ESP 도메인 구성

Singular 링크를 이메일 서비스 제공업체(ESP) 또는 기타 서드파티 도메인으로 래핑한 경우 외부 도메인을 구성하세요.

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withESPDomains(listOf("sl.esp.link", "custom.domain.com"))

SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withESPDomains(Arrays.asList("sl.esp.link", "custom.domain.com"));

동적 딥링크 라우팅

하나의 Singular 추적 링크에 동적 리디렉트 오버라이드를 구성하여 Singular 알림에서 여러 딥링크 목적지를 구현할 수 있습니다.

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

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

여러 개의 추적 링크를 만드는 대신 하나의 Singular 링크를 사용하고 유저의 선택에 따라 동적으로 리디렉트를 오버라이드하세요. 구현 세부 정보는 Singular 추적 링크에서 리디렉트 오버라이드 를 참조하세요.

중요 고려 사항

구현 참고 사항

• 콜백 핸들러 없음: withSingularLink 와 달리, 푸시 알림 기능은 페이로드(payload) 콜백을 제공하지 않습니다. 유저를 앱 내 특정 콘텐츠로 라우팅하려면 자체 딥링크 로직을 구현하세요.
• 어트리뷰션 흐름: 유저가 알림을 탭하면 Singular가 페이로드(payload)를 가져와 Singular.init() 에 의해 트리거되는 Start Session 이벤트에 포함시킵니다. 백엔드는 이 데이터를 처리하여 푸시 알림 터치포인트를 어트리뷰션하고 리인게이지먼트 추적을 등록합니다.
• 도메인 제한: 기본적으로 Manage Links 페이지에 등록된 Singular 링크 도메인( sng.link )만 허용됩니다. 래핑된 링크를 사용하려면 withESPDomains() 로 ESP 도메인을 명시적으로 구성하세요.